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 ideas para casos de uso y antes de implementar el servidor.
Cada herramienta debe ayudar a cumplir un objetivo del usuario. No repliques una API interna sin considerar cómo las personas solicitarán y usarán esa capacidad.
Relacionar los casos de uso con las herramientas
Para cada caso de uso admitido:
- Escribe el resultado que espera el usuario.
- Enumera la información necesaria para obtener ese resultado.
- Identifica las operaciones de lectura, escritura o las acciones externas que debe realizar el servidor.
- Agrupa las operaciones que representan una sola acción coherente.
- Separa las operaciones cuando tengan distintos permisos, riesgos de seguridad o requisitos de confirmación.
Por ejemplo, un complemento de proyectos podría ofrecer:
list_projectspara encontrar proyectos.get_projectpara inspeccionar un proyecto.create_projectpara crear un proyecto.update_projectpara cambiar los detalles de un proyecto.archive_projectpara realizar un cambio de estado con consecuencias importantes.
Separa las operaciones de lectura y escritura para que el modelo y el usuario puedan distinguir la recuperación de información de las acciones que cambian el estado.
Definir cada contrato
Documenta lo siguiente para cada herramienta propuesta:
| Campo | Qué definir |
|---|---|
| Nombre | Un identificador estable y orientado a la acción. |
| Título | Una acción expresada de forma concisa y comprensible para las personas. |
| Descripción | El objetivo del usuario y las condiciones que deben activar la herramienta. |
| Esquema de entrada | Parámetros obligatorios y opcionales, tipos, valores permitidos y límites. |
| Esquema de salida | Campos estructurados que el modelo puede inspeccionar y reutilizar. |
| Autorización | La cuenta, el rol o el acceso a los recursos que debe verificar el servidor. |
| Efectos secundarios | Datos o estado externo que la herramienta puede cambiar. |
| Comportamiento ante fallas | Errores que el modelo puede explicar o de los que puede recuperarse. |
Usa entradas explícitas. No dependas de que el modelo adivine identificadores, el alcance de la cuenta u otros valores necesarios para un funcionamiento correcto.
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.
Redactar descripciones que faciliten la selección
El modelo usa las descripciones de las herramientas para decidir cuándo una herramienta es adecuada para una solicitud. Describe la intención del usuario, no la implementación.
Las buenas descripciones:
- Indican qué hace la herramienta.
- Explican cuándo usarla.
- La distinguen de herramientas similares.
- Destacan los límites o requisitos previos importantes.
Evita las descripciones que solo repiten el nombre de la herramienta o usan terminología de servicios internos que los usuarios no conocen.
Planificar las anotaciones de seguridad
Asigna las anotaciones según el comportamiento real. Consulta el
esquema
ToolAnnotations de MCP
para conocer las definiciones canónicas, los valores predeterminados y las interacciones entre estas indicaciones:
readOnlyHintestruesolo cuando la herramienta no puede cambiar el estado.destructiveHintestruecuando la herramienta puede causar resultados irreversibles o difíciles de revertir.openWorldHintestruecuando la herramienta accede a la internet pública o a entidades externas sin un alcance delimitado, incluso mediante acciones de solo lectura como la búsqueda web. Una cuenta o un espacio de trabajo privados y de alcance delimitado no se consideran de mundo abierto solo por estar alojados externamente.
Las anotaciones no reemplazan la autorización del lado del servidor, la validación de entradas ni la confirmación para acciones con consecuencias importantes.
Verificar la cobertura y los límites
Compara las herramientas propuestas con el inventario completo de casos de uso:
- Confirma que cada caso de uso admitido tenga una forma de llegar a un resultado útil.
- Identifica las herramientas que no responden a un caso de uso documentado.
- Busca operaciones de lectura faltantes que los usuarios necesiten antes de realizar una acción de escritura.
- Verifica que, ante solicitudes no admitidas, se comunique una limitación comprensible en lugar de ofrecer una aproximación insegura.
- Comprueba si dos herramientas similares tienen descripciones que se superponen y podrían causar confusión al seleccionarlas.
Conserva el plan de herramientas resultante como lista de verificación para la implementación y la evaluación. Luego, crea el servidor MCP y prueba cada contrato con entradas representativas, inválidas y no autorizadas.