Escribe las descripciones de herramientas para el modelo, no para la persona

Las descripciones de herramientas son cómo el modelo decide qué invocar. Hazlas explícitas y sin ambigüedad, con ejemplos de entrada y salida.

Por qué

La calidad de la descripción de una herramienta determina directamente la selección correcta de herramientas. La guía de producción de Anthropic es clara: las descripciones deben indicar cuándo usar la herramienta, qué parámetros recibe, qué devuelve, si tiene efectos secundarios e incluir un ejemplo resuelto. Una etiqueta escueta como "search" es peor que inútil: no le dice nada al modelo sobre cuándo invocarla ni qué esperar. Un estudio de 856 herramientas en 103 servidores MCP (arxiv:2602.14878) encontró que el 97.1% de las descripciones tenía al menos un defecto de calidad y el 56% nunca indicaba con claridad su propósito, y que mejorar esas descripciones aumentó el éxito de las tareas en una mediana de 5.85 puntos porcentuales. Estas descripciones no son texto de interfaz: son el sustrato de decisión del modelo.

Haz

Indica cuándo usarla, los parámetros y una llamada de ejemplo. Mal: "search". Bien: "search_orders: find a customer's orders by email or order ID; returns up to 50, newest first".

No hagas

Reutilizar etiquetas escuetas de interfaz pensadas para personas.

Artefacto

{
  "name": "search_orders",
  "description": "Use this to find a customer's orders by email or order ID. Returns up to 50, newest first. Does not modify anything.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Email or order ID" },
      "limit": { "type": "integer", "default": 20, "maximum": 50 }
    },
    "required": ["query"]
  },
  "examples": [{ "query": "[email protected]", "limit": 10 }]
}