Crear herramientas que Claude elige

La demostración de este video se grabó en septiembre de 2026. Se ejecutó en Claude Sonnet 5 (claude-sonnet-5). Los resultados pueden diferir en modelos más nuevos.

Supongamos que tu bucle de herramientas funciona, y luego ocurre uno de estos casos:

• Claude llama a la herramienta equivocada.
• Hace tres llamadas a herramientas para un solo dato.
• Pasa 0142 donde tu código espera MEG-2026-0142.

Claude nunca recibe la función que ejecuta tu herramienta. Solo ve la definición que envías y los resultados que devuelves. Por eso, cuando Claude usa mal una herramienta, fíjate primero en la definición.

Meridian tiene un asistente interno para las preguntas de los empleados sobre proyectos, permisos y facturación. Reescribir sus definiciones de herramientas elevó su puntuación de 14 a 26 de 30 preguntas de prueba, en el mismo modelo.

Lo que Claude ve de tu herramienta

Una definición de herramienta es un bloque de JSON que le indica a Claude que una herramienta existe. La envías en la lista tools de cada solicitud.

Aquí está la definición reescrita de la herramienta de proyectos de Meridian. Tiene cuatro partes.

{
  "name": "lookup_project_status",
  "description": "Returns current facts about a single Meridian …",
  "input_schema": {
    "type": "object",
    "properties": {
      "project_id": {
        "type": "string",
        "description": "Full Meridian job number in the format MEG-YYYY-NNNN, e.g. MEG-2026-0142."
      },
      "fields": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": ["phase", "status", "lead", "hours", "deadline", "site", "client"]
        },
        "description": "Which fields to return. Omit to return everything."
      }
    },
    "required": ["project_id"]
  },
  "input_examples": [
    {"project_id": "MEG-2026-0142", "fields": ["phase", "status"]},
    {"project_id": "MEG-2025-0417", "fields": ["lead", "hours"]},
    {"project_id": "MEG-2024-0233"}
  ]
}

• name es cómo Claude llama a la herramienta.
• description es texto sin formato que tú escribes y Claude lee. Aquí aparece acortado y se muestra completo en la siguiente sección.
• input_schema enumera los parámetros de la herramienta en JSON Schema, cada uno con un nombre, un tipo y su propia descripción. required indica cuáles deben proporcionarse.
• input_examples es opcional. Le muestra a Claude cómo se ve una buena entrada, como un número de trabajo completo. Cada ejemplo debe ser válido según input_schema, o la API devuelve un error 400.

Claude decide si hace una llamada a una herramienta leyendo la solicitud del usuario y la descripción de cada herramienta.

Escribe una descripción detallada

De las cuatro partes, la descripción es la que más influye.

Apunta a al menos tres o cuatro oraciones, más si la herramienta es compleja. Cubre cuatro aspectos:

1. Qué hace la herramienta
2. Cuándo usarla, y cuándo no
3. Qué significa cada parámetro
4. Qué no devuelve

Aquí está la descripción completa de Meridian:

Returns current facts about a single Meridian project: phase,
schedule status, project lead, hours budgeted and consumed,
deadline, site city, and client. Use this only when the user asks
about a specific project by name or job number; if only a partial
number is given (e.g. 'the 0142 job'), normalize it to the full
MEG-YYYY-NNNN format before calling. Pass the fields parameter to
fetch just the fields the question needs instead of the whole
record. This tool does not return permit or invoicing information.
Use get_permit_status or get_billing_summary for those.



Decir cuándo usar la herramienta, y cuándo no, ayuda a Claude a evitar llamar a la herramienta equivocada. La descripción de Meridian limita la herramienta a preguntas sobre un solo proyecto. Para permisos y facturación, nombra las herramientas que se deben usar.

Combina herramientas superpuestas en una sola

Una buena descripción no ayuda mucho cuando varias herramientas hacen casi el mismo trabajo.

El primer conjunto de Meridian tenía seis herramientas livianas, cada una con una descripción de una sola línea. Cuatro de ellas devolvían un solo dato del proyecto cada una. Esas cuatro se superponían, así que Claude tenía que adivinar cuáles necesitaba una pregunta.

La solución es combinar las cuatro en una sola herramienta, lookup_project_status, con un parámetro fields que indica qué datos devolver. Las otras dos, para permisos y facturación, hacen trabajos distintos, así que se mantienen. Seis herramientas se convierten en tres.

Mide el cambio con una evaluación

Una evaluación es un conjunto fijo de preguntas de prueba con respuestas correctas conocidas, que se ejecuta contra Claude y se puntúa. Muestra si las nuevas definiciones son mejores.

La evaluación de Meridian comprueba si Claude llama a las herramientas correctas. Tiene 30 preguntas que haría un empleado, cada una etiquetada con las llamadas a herramientas correctas. Meridian ejecutó las 30 preguntas dos veces en claude-sonnet-5, una vez con cada conjunto de herramientas.

Corrige solo la parte responsable

Para corregir una falla, encuentra la parte de la definición responsable, cambia solo esa parte y vuelve a ejecutar tu evaluación.

Solución de problemas de uso de herramientas enumera más síntomas y soluciones.

Puntos clave

• Escribe descripciones de al menos tres o cuatro oraciones, e indica cuándo no usar la herramienta.
• Combina herramientas superpuestas en una sola herramienta con parámetros.
• Mide los cambios con una evaluación.
• Para corregir una falla, cambia solo la parte responsable.