Diseño de herramientas y MCP: descripciones, errores y alcance

Escenario Customer Support Resolution Agent. Un cliente escribe: «¿Dónde está mi pedido 4500012345?». El agente, en lugar de consultar el pedido, llama a get_customer. Lo revisas y las descripciones de las dos herramientas son de una línea: «Obtiene información del cliente» y «Obtiene detalles del pedido». Las dos aceptan identificadores parecidos. Para Claude, son casi la misma herramienta.

Claude no ve tu código ni tu backend. Ve un nombre, una descripción y un esquema. Con eso decide qué llamar, con qué argumentos y qué hacer si algo falla. El dominio 2, Tool Design & MCP Integration (18 %, unas 11 preguntas), va de diseñar bien esa superficie: descripciones, errores, reparto de herramientas entre agentes, configuración de servidores MCP y uso de las herramientas integradas.

Las descripciones son la interfaz (2.1)

La guía lo dice sin rodeos: la descripción es el mecanismo principal que usa el modelo para elegir herramienta. Si es mínima, la selección entre herramientas parecidas será poco fiable. Una buena descripción cuenta qué hace, qué formato de entrada espera, un par de ejemplos de consultas, casos límite y, sobre todo, cuándo usarla frente a la herramienta parecida. Mira la diferencia:

lookup_order
Obtiene detalles del pedido.

Tres técnicas más que aparecen en los task statements:

• Renombrar para quitar solapes. Si analyze_content y analyze_document se confunden, renombra la primera a algo específico como extract_web_results y ajusta su descripción al caso web.
• Partir herramientas genéricas en herramientas con contrato claro: un analyze_document que lo hace todo se convierte en extract_data_points, summarize_content y verify_claim_against_source.
• Revisar el prompt del sistema. Una instrucción del tipo «ante cualquier duda sobre cuentas, consulta al cliente» puede crear una asociación por palabra clave que tapa descripciones bien escritas.

Errores que ayudan a decidir (2.2)

Un error genérico («Operation failed») deja al agente sin saber si reintentar, pedir otro dato o explicar algo al cliente. En MCP, una herramienta comunica que ha fallado con la marca isError en su resultado. Lo que la guía añade es metadatos estructurados en ese error: una categoría, si es reintentable y una explicación legible.

Un resultado de error bien construido se parece a esto (el formato exacto de los campos es tuyo; lo que cuenta es que el agente pueda decidir):

{
  "isError": true,
  "content": [{ "type": "text", "text": "{\"errorCategory\": \"business\", \"isRetryable\": false, \"message\": \"El plazo de devolución de 30 días terminó el 12 de septiembre\"}" }]
}

Y una distinción que el examen repite en los dominios 2 y 5: un fallo de acceso no es un resultado vacío. «No he podido consultar» y «he consultado y no hay coincidencias» son cosas distintas. Si devuelves un vacío como éxito cuando en realidad hubo timeout, el agente concluirá algo falso.

Cuántas herramientas y para quién (2.3)

Más herramientas no es mejor. La guía pone el ejemplo de un agente con 18 herramientas frente a uno con 4 o 5: cuantas más opciones, peor elige. Y un agente con herramientas fuera de su especialidad tiende a usarlas mal, como un subagente de síntesis que se pone a buscar en la web.

• Restringe por rol. Cada subagente, solo lo que necesita.
• Sustituye lo genérico por lo acotado. Mejor un load_document que valida que la URL es un documento que un fetch_url abierto a cualquier cosa.
• Herramientas cruzadas con alcance limitado. Si síntesis necesita verificar datos simples muy a menudo, dale un verify_fact acotado para ese caso frecuente y deja lo complejo al coordinador.

Aquí entra tool_choice, que en la API admite auto (Claude decide si llama a una herramienta; es el valor por defecto con herramientas), any (tiene que llamar a alguna, la que elija), una herramienta concreta por nombre (tiene que llamar a esa) y none. La guía usa any para garantizar que el modelo llame a una herramienta en vez de contestar con texto, y el forzado por nombre para asegurar que un paso, como extract_metadata, va primero.

Ojo con un matiz de hoy: según la documentación de la API, Claude Opus 5.5, Sonnet 5.5 y Fable 5.1 rechazan con un error 400 el uso forzado (any o una herramienta concreta). En esos modelos la alternativa es auto con strict tool use para garantizar entradas válidas, o structured outputs si necesitas una respuesta con forma JSON fija. Haiku 5.5 sí lo admite, aunque entonces llama a la herramienta sin pensar antes. Para el examen, sabe qué hace cada opción de tool_choice, tal como la describe la guía; para tus proyectos, comprueba qué admite el modelo que uses.

MCP en Claude Code y en tus agentes (2.4)

Un servidor MCP expone herramientas (acciones) y recursos (contenido que se puede leer). Cuando Claude Code o tu agente se conecta a varios servidores, descubre las herramientas de todos al conectar y las tiene disponibles a la vez.

La configuración en Claude Code tiene alcances distintos, y el examen pregunta cuál usar:

Un .mcp.json de equipo, con el secreto fuera del fichero (${VAR} toma el valor de la variable de entorno y ${VAR:-valor} añade uno por defecto):

{
  "mcpServers": {
    "incidencias": {
      "type": "http",
      "url": "${INCIDENCIAS_URL:-https://mcp.ejemplo.interno}/mcp",
      "headers": { "Authorization": "Bearer ${INCIDENCIAS_TOKEN}" }
    }
  }
}

Más criterios de la guía para este task statement:

• Usa servidores de la comunidad para integraciones estándar (Jira, por ejemplo) y reserva los servidores propios para flujos específicos del equipo. En SAP es igual: antes de escribir un servidor que envuelva una API OData publicada, mira si ya existe uno mantenido y avalado; y usa siempre las vías oficiales (tienes más en Claude y SAP y Conexiones).
• Describe bien las herramientas MCP. Si la descripción es pobre, el agente preferirá una herramienta integrada como Grep aunque la MCP sea más capaz.
• Expón catálogos como recursos. Un índice de incidencias, la jerarquía de la documentación o el esquema de una base de datos como recurso MCP dan visibilidad al agente sin que tenga que hacer llamadas exploratorias.

En el Agent SDK, las herramientas MCP se nombran mcp__<servidor>__<herramienta>: un process_refund en un servidor llamado soporte es mcp__soporte__process_refund. Ese es el nombre que usas en listas de herramientas permitidas y en los matchers de los hooks.

Las herramientas integradas: cada una a lo suyo (2.5)

El escenario Developer Productivity with Claude gira alrededor de las herramientas integradas. El examen espera que sepas elegir la adecuada sin dudar:

Dos hábitos que la guía considera buena práctica: construir el entendimiento de forma incremental (Grep para encontrar la entrada, Read para seguir el hilo) en lugar de leer todos los archivos al principio, y, para rastrear el uso de funciones a través de módulos que las reexportan, listar primero todos los nombres exportados y luego buscar cada uno.

Para el examen

Siguiente paso

Próxima lección: Workflows con Claude Code: CLAUDE.md, reglas por rutas, commands y skills, plan mode y CI/CD (dominio 3).