Las herramientas son las acciones y los datos que el servidor MCP de un complemento pone a disposición de ChatGPT y Codex. Defínelas después de explorar posibles casos de uso y antes de implementar el servidor.
Cada herramienta debe ayudar al usuario a lograr un objetivo. Antes de replicar una API interna, considera cómo pedirán los usuarios esa función y cómo la usarán.
Asocia los casos de uso con las herramientas
Para cada caso de uso admitido:
- Describe el resultado que espera el usuario.
- Enumera la información necesaria para obtener ese resultado.
- Identifica las operaciones de lectura y escritura o las acciones externas que debe realizar el servidor.
- Agrupa las operaciones que, en conjunto, representan una sola acción.
- Separa las operaciones cuando tengan distintos permisos, riesgos de seguridad o requisitos de confirmación.
Por ejemplo, un complemento para gestionar proyectos podría ofrecer estas herramientas:
list_projectspara buscar proyectos.get_projectpara consultar un proyecto específico.create_projectpara crear un proyecto.update_projectpara modificar los detalles de un proyecto.archive_projectpara realizar un cambio de estado con consecuencias importantes.
Separa las operaciones de lectura de las de escritura para que el modelo y el usuario puedan distinguir la consulta de información de las acciones que modifican el estado.
Define el contrato de cada herramienta
Documenta lo siguiente para cada herramienta propuesta:
| Campo | Qué definir |
|---|---|
| Nombre | Un identificador estable que indique la acción. |
| Título | Una frase breve que describa la acción en lenguaje claro. |
| Descripción | El objetivo del usuario y las condiciones en las que se debe invocar la herramienta. |
| Esquema de entrada | Los parámetros obligatorios y opcionales, sus tipos, los valores permitidos y los límites. |
| Esquema de salida | Los campos estructurados que el modelo puede examinar y reutilizar. |
| Autorización | La cuenta, el rol o los permisos de acceso a los recursos que el servidor debe verificar. |
| Efectos secundarios | Los datos o el estado externo que la herramienta puede modificar. |
| Comportamiento ante fallos | Los errores que el modelo puede explicar o de los que puede recuperarse. |
Define las entradas de forma explícita. Evita que el modelo tenga que adivinar los identificadores, el alcance de la cuenta u otros valores necesarios para que la operación se realice correctamente.
Devuelve identificadores estables y suficiente información estructurada para las llamadas posteriores. Excluye de los resultados los secretos, los tokens de acceso, los diagnósticos internos y los datos personales innecesarios.
Redacta descripciones que faciliten la selección
El modelo usa las descripciones para decidir cuándo una herramienta es adecuada para una solicitud. Céntrate en lo que el usuario quiere lograr y evita los detalles de implementación.
Una buena descripción:
- Indica qué hace la herramienta.
- Explica cuándo usarla.
- La distingue de otras herramientas similares.
- Destaca los límites o requisitos previos importantes.
Evita las descripciones que se limitan a repetir el nombre de la herramienta o que usan términos internos del servicio que los usuarios desconocen.
Planifica las anotaciones de seguridad
Asigna las anotaciones según el comportamiento real de la herramienta. Consulta el esquema ToolAnnotations de MCP para conocer las definiciones oficiales, los valores predeterminados y cómo interactúan estas indicaciones:
readOnlyHintsolo tiene el valortruecuando la herramienta no puede modificar el estado.destructiveHinttiene el valortruecuando la herramienta puede producir efectos irreversibles o difíciles de revertir.openWorldHinttiene el valortruecuando la herramienta accede a la internet pública o a un conjunto no delimitado de entidades externas, incluso mediante acciones de solo lectura como la búsqueda web. Si el acceso se limita a una cuenta privada o a un Espacio de trabajo privado, el alojamiento externo por sí solo no convierte ese entorno en uno abierto.
Las anotaciones no sustituyen la autorización en el servidor, la validación de las entradas ni la confirmación de las acciones que tienen consecuencias importantes.
Revisa la cobertura y los límites
Compara las herramientas propuestas con el inventario completo de casos de uso:
- Confirma que, para cada caso de uso admitido, haya una forma de obtener un resultado útil.
- Identifica las herramientas que no cubren ningún caso de uso documentado.
- Comprueba si falta alguna operación de lectura que los usuarios necesiten antes de realizar una operación de escritura.
- Verifica que, ante una solicitud no admitida, se explique claramente la limitación en vez de ofrecer una aproximación insegura.
- Comprueba si las descripciones de dos herramientas similares se superponen y pueden generar dudas sobre cuál elegir.
Usa el plan de herramientas resultante como lista de verificación durante la implementación y la evaluación. Luego, implementa el servidor MCP y prueba cada contrato con entradas representativas, inválidas y no autorizadas.