# AX-SYS-11: Escribe las descripciones de herramientas para el modelo, no para la persona

> Tools and capabilities · foundational · AX-SYS-11

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

```json
{
  "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": "jane@acme.com", "limit": 10 }]
}
```

## Fuentes

1. [Anthropic — Writing Effective Tools for AI Agents](https://www.anthropic.com/engineering/writing-tools-for-agents) — Tool description quality is the primary determinant of correct tool selection; descriptions should state when to use the tool, what it returns, whether it has side effects, and include an example
2. [arxiv:2602.14878 — MCP Tool Descriptions Are Smelly](https://arxiv.org/abs/2602.14878) — Across 856 tools on 103 MCP servers, 97.1% of descriptions had at least one quality smell and 56% failed to state their purpose clearly; augmenting descriptions improved task success by a median of 5.85 percentage points
3. [MCP Specification 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25) — MCP tools are defined with JSON Schema input parameters; description quality is the model's primary signal for deciding which tool to invoke

---
Source: Agent Experience Principles (axprinciples.com)