Diseño de tools, el arte de la descripción

El problema infravalorado

Has escrito tu MCP server, todas las tools funcionan, todo va. Pero Claude nunca las llama.

¿Por qué? Porque el modelo no sabe que tus tools existen, o no entiende qué hacen.

La descripción de la tool es más importante que su código. El código se llama 10 veces. La descripción la lee el modelo cada vez que piensa qué tool necesita.

Las tres reglas para nombres de tools

1. Verbo + objeto. get_customer es mejor que customer. send_email es mejor que email. El modelo necesita el verbo para entender la acción.

2. Específico, no genérico. get_stripe_customer es mejor que get_customer si tu server es multi-fuente. fetch_latest_blog_post es mejor que fetch_data.

3. Consistente entre tools. Si usas get_X, list_X, create_X, mantenlo. No get_customer en una tool, fetch_user en la siguiente y luego retrieve_account. Unificar.

La descripción de la tool

Es el texto más importante del server. 1-3 frases que expliquen:

1. Qué hace la tool.
2. Cuándo usarla (lo olvidan la mayoría).
3. Cuándo NO usarla (aún más lo olvidan).

Ejemplo, malo:

Devuelve una lista de clientes.

Ejemplo, bueno:

Lista clientes desde la base de datos CRM. Úsalo cuando el usuario pida varios clientes o un resumen. Para un cliente concreto usa get_customer en su lugar. Devuelve máximo 100 entradas, paginar con el parámetro offset.

El segundo texto ayuda al modelo a decidir. El primero es pura documentación.

Los input schemas son parte de la descripción

Cada parámetro debería:

• Tener nombre claro (customer_id, no id).
• Tener descripción (usa schemas Zod con .describe(...)).
• Tener un default sensato si es opcional.

El modelo lee el schema junto con la descripción de la tool. Parámetros poco claros llevan a llamadas equivocadas.

Diseño del output

El modelo también lee el output. Dos reglas:

1. Texto corto cuando se pueda, JSON cuando haga falta. Tools simples devuelven un único bloque de texto:

"Cliente Max Mustermann encontrado. Email: max@example.com, Último pedido: 2025-11-15 (Producto X, 250 EUR)."

Tools que entregan datos estructurados devuelven JSON:

{"customers": [{"id":"123","name":"Max","email":"max@example.com","lastOrder":"2025-11-15"}]}

2. Explica los errores con claridad. En errores, no {"error":"failed"}. Sino:

"No pude encontrar al cliente. Posibles motivos: ID inválido, DB connection caída. Prueba con `list_customers` para encontrar el ID correcto."

El modelo decide mejor cuando sabe POR QUÉ algo no funcionó.

La pista de MCP discovery

En servers stdio, Claude lee la lista de tools al arranque. En servers HTTP puedes además poner un system prompt global que explica QUÉ puede hacer tu server. Es las "instructions" en el setup del server:

const server = new Server(
  {
    name: "mi-crm-server",
    version: "0.1.0",
    description: "Integración CRM. Da acceso a clientes, deals, interacciones. Úsalo para flujos de sales, no para tickets de support."
  },
  { capabilities: { tools: {} } }
);

El texto de descripción se le muestra al modelo cuando decide qué tool es relevante. Aprovéchalo.

La regla final

Lee tus descripciones de tools en voz alta. Si suenan a documentación, están mal. Si suenan a instrucciones para un compañero, están bien.

Siguiente lección

Deployment. De server local a paquete npm, Cloud Run o MCPize. Cómo pasar de "funciona en mi máquina" a "instalable para otros".