← Volver al listado de tecnologías ← Índice de Claude Certified Architect

Cap 6: Diseño de Tools Efectivos

Por: Artiko
claude-certifiedtoolsdesignmcpapi

Tool Descriptions: el mecanismo de selección

Cuando Claude tiene acceso a múltiples tools, la description es el mecanismo principal que usa para decidir cuál invocar. No es el nombre, no es el schema — es la description la que determina si el modelo selecciona correctamente.

El problema de descriptions mínimas

{
  "name": "analyze_content",
  "description": "Analyzes content"
}

Con una description tan escueta, Claude no puede distinguir de forma confiable entre tools similares. Si además tienes analyze_document con description “Analyzes a document”, el modelo va a hacer misrouting constantemente.

Qué incluir en una buena description

Una description efectiva contiene:

  1. Qué hace el tool — propósito específico, no genérico
  2. Input formats — qué tipo de datos acepta
  3. Example queries — cuándo debería invocarse
  4. Edge cases — qué NO hacer con este tool
  5. Boundary explanations — dónde termina su responsabilidad
{
  "name": "analyze_sentiment",
  "description": "Analyzes emotional sentiment of customer feedback text. Input: raw text string from support tickets or reviews (max 5000 chars). Use this for: determining if feedback is positive/negative/neutral, extracting emotion keywords. Do NOT use for: document summarization, content classification by topic, or structured data analysis. Returns: sentiment score (-1 to 1), dominant emotion, confidence level."
}

Overlap ambiguo entre tools

El problema

Cuando dos tools tienen nombres o descriptions que se superponen, Claude no puede determinar cuál usar:

Tool ATool BProblema
analyze_contentanalyze_document¿Cuál es para texto plano vs PDF?
search_recordsfind_entriesSinónimos sin distinción clara
process_datatransform_dataVerbos genéricos, misma semántica

Diagnóstico de misrouting

Si observas que Claude invoca el tool equivocado:

  1. Revisa las descriptions — ¿hay palabras compartidas que crean ambigüedad?
  2. Compara los schemas de input — ¿aceptan los mismos tipos?
  3. Verifica si el system prompt crea asociaciones no intencionadas

System prompt y asociaciones no deseadas

El wording del system prompt puede crear asociaciones implícitas con tools. Si tu prompt dice:

“Cuando el usuario pida analizar algo, usa las herramientas disponibles”

Claude puede asociar “analizar” con cualquier tool que tenga “analyze” en el nombre, ignorando la intención real.

Solución: ser específico en el system prompt sobre cuándo usar cada tool:

“Para análisis de sentimiento de feedback, usa analyze_sentiment. Para clasificación de documentos por categoría, usa classify_document.”

Estrategias para eliminar overlap

1. Renombrar tools con verbos específicos

❌ analyze_content → ✅ extract_sentiment
❌ analyze_document → ✅ classify_document_type
❌ process_data → ✅ normalize_csv_records

2. Actualizar descriptions al renombrar

Renombrar sin actualizar la description no resuelve nada. El nombre es una señal secundaria; la description es la primaria.

3. Splittear tools genéricos

Un tool genérico que hace “de todo” es peor que varios tools específicos con contratos claros.

Antes — un tool genérico:

{
  "name": "data_tool",
  "description": "Handles all data operations",
  "inputSchema": {
    "type": "object",
    "properties": {
      "action": { "enum": ["search", "create", "update", "delete"] },
      "data": { "type": "object" }
    }
  }
}

Después — tools específicos con contratos I/O definidos:

[
  {
    "name": "search_customers",
    "description": "Search customer records by name, email or ID. Input: search query string or partial match. Returns: array of matching customer objects with id, name, email, status.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "query": { "type": "string" },
        "limit": { "type": "number", "default": 10 }
      },
      "required": ["query"]
    }
  },
  {
    "name": "create_customer",
    "description": "Creates a new customer record. Requires name and email. Returns: created customer object with generated ID. Fails if email already exists.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string", "format": "email" }
      },
      "required": ["name", "email"]
    }
  }
]

4. Contratos I/O definidos

Cada tool debe tener:

{
  "name": "resize_image",
  "description": "Resizes an image to specified dimensions. Input: image URL or base64 (max 10MB, formats: PNG/JPG/WebP). Width and height in pixels (min 1, max 4096). Returns: base64 encoded resized image. Fails if: image exceeds size limit, unsupported format, dimensions out of range."
}

Regla de oro

Si no puedes explicar en una oración cuándo usar tool A versus tool B, tus usuarios (y Claude) tampoco podrán.

La prueba definitiva: describe a un colega cuándo debería usar cada tool. Si necesitas más de 10 segundos para difereciarlos, necesitas rediseñar.

← Cap 5: Anterior · Índice · Cap 7: MCP Servers →

← Volver al listado de tecnologías ← Índice de Claude Certified Architect