Qué es MCP y cómo escribir tools que Claude elige bien

Cuantas más tools tiene disponibles un agente, más depende el resultado de cómo fueron nombradas y descritas — no solo del schema. Esta página explica el MCP (Model Context Protocol) y las prácticas que deciden si Claude elige la tool correcta o se equivoca por ambigüedad.

Qué estandariza realmente el MCP

MCP es un protocolo que estandariza cómo un agente se conecta a fuentes externas de datos y acción. En el vocabulario del protocolo, Claude Code actúa como host; las tools son controladas por el modelo, que decide cuándo llamar a cada una; los resources son controlados por la aplicación; y los prompts son controlados por el usuario. Cada primitiva tiene un dueño distinto de la decisión de cuándo se usa — confundir las tres es la fuente más común de malentendidos sobre lo que hace el MCP.

Esto importa en la práctica: un servidor MCP puede exponer las tres primitivas a la vez, y no toda integración exige el mismo transporte — la elección entre ejecutarlo localmente y exponerlo vía HTTP remoto depende de dónde corre el servidor y de quién necesita autorizar el acceso.

Por qué dos tools con el mismo nombre rompen la selección

Cuando la biblioteca de tools crece a través de varios servicios, es común que dos módulos distintos del mismo agente expongan una tool con el mismo nombre — dos `get_user`, uno del servicio de autenticación y otro del de facturación, por ejemplo. Claude tiene que elegir entre las dos incluso antes de completar cualquier parámetro, y un nombre idéntico no aporta información alguna para esa elección — la selección se vuelve suerte.

La corrección documentada es nombrar con namespace por servicio: `auth_get_user`, `billing_get_user`. Un parámetro extra para desambiguar después no lo resuelve, porque la ambigüedad ocurre un paso antes — en la selección de la tool, no al completarla — y un prefijo lo resuelve sin tocar ningún schema.

La descripción es el canal de señal principal, no el nombre

Dado un nombre sin ambigüedad, lo que más afecta que Claude elija bien es la descripción: qué hace la tool, cuándo usarla y el formato exacto de cada parámetro. Una descripción vaga ("gestiona transacciones") deja la decisión librada a la inferencia; una descripción específica sobre cuándo usarla reduce eso a casi cero.

El mismo cuidado vale para el retorno: en caso de error, la tool debe devolver `is_error: true` con un mensaje accionable, no un texto genérico. Y cuando varias operaciones relacionadas tienen sentido juntas, consolidar en menos tools que devuelvan solo información de alta señal suele funcionar mejor que una tool diminuta para cada operación.

tool_choice: cuando la elección no puede depender del modelo

Hay momentos en que la elección no puede depender de la interpretación del modelo — por ejemplo, forzar que una verificación de identidad ocurra antes de cualquier otra acción. Para eso, `tool_choice` permite forzar una tool nombrada específica en ese turno, en lugar de confiar en que la descripción bastará.

Es el mismo patrón del dominio de permisos aplicado a tools: una buena descripción aumenta la probabilidad de acierto; un parámetro estructurado de la API garantiza el comportamiento cuando el acierto no puede ser opcional.

Dos tool calls en el mismo turno no siempre deben ejecutarse en paralelo

La Messages API permite que Claude devuelva más de un bloque tool_use en el mismo turno, pero eso no significa que las dos llamadas deban ejecutarse al mismo tiempo del lado de la aplicación. Cuando una operación depende del resultado de la otra, o cuando ambas tienen un efecto secundario sobre el mismo recurso, ejecutarlas en paralelo puede aplicar una en el orden equivocado, o aplicar las dos aunque la primera debiera haber impedido la segunda.

Le corresponde a la aplicación, no al modelo, decidir el orden real de ejecución de las tool calls que recibe — el papel de Claude es decidir cuáles llamar; el papel del código que procesa la respuesta es decidir cómo y cuándo ejecutarlas con seguridad.