---
title: "Diseño de tools, el arte de la descripción — StudioMeyer Academy"
description: "Por qué el 80% de los servidores MCP se ignoran. El diseño de los tools decide si el modelo te encuentra."
canonical: "https://studiomeyer.academy/es/lernwege/fuer-entwickler/lektionen/03-tool-design"
language: es
image: "https://studiomeyer.academy/og/academy-og-share.png"
publisher: "StudioMeyer Academy, https://studiomeyer.academy (llms.txt: https://studiomeyer.academy/llms.txt)"
---

## 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:

```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:

```typescript
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".

Puedes leer todo libremente. Con una cuenta se guarda tu progreso.

[Iniciar sesión](https://studiomeyer.academy/es/login?next=%2Fes%2Flernwege%2Ffuer-entwickler%2Flektionen%2F03-tool-design)

Para desarrolladores · Módulo 1 de 1

## Para desarrolladores

[Volver a la ruta](https://studiomeyer.academy/es/lernwege/fuer-entwickler)

## Tus notas

Inicia sesión para guardar tus propias notas sobre esta lección.

[Iniciar sesión](https://studiomeyer.academy/es/login?next=%2Fes%2Flernwege%2Ffuer-entwickler%2Flektionen%2F03-tool-design)

## Sitemap

Páginas públicas de este sitio como Markdown: [sitemap](https://studiomeyer.academy/sitemap.md). Punto de entrada curado: [llms.txt](https://studiomeyer.academy/llms.txt), texto completo: [llms-full.txt](https://studiomeyer.academy/llms-full.txt).