Comienza por el recorrido crítico
Qué es: Una tool nace de un objetivo real del usuario, no de cada botón o función que ya existe en el código.
Por qué aprender: Mapear el inicio, la decisión, el efecto y la evidencia evita que la integración copie la interfaz sin comprender la intención.
Antes de modelar
Escribe la solicitud de la persona, el estado actual y la evidencia que probará la finalización.
Error de inicio
Empezar por el nombre de una función o por un botón produce una tool sin un objetivo humano claro.
Anticípate antes de abrir el código
¿Qué información cambia la decisión? ¿Qué efecto debe aparecer en la interfaz? Responde antes de implementar.
jornada: "encontrar e reservar uma vaga"
estado_inicial: "catálogo aberto"
resultado: "reserva preparada, ainda não confirmada"Profundiza: evidencia que vale la pena guardar
Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.
Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.
Conceptos clave
objetivo observable
estado inicial
efecto esperado
evidencia final
Asigna una responsabilidad a cada tool
Qué es: Las herramientas pequeñas llevan a cabo una intención completa y no compiten por la misma llamada.
Por qué aprender: Cuando dos descripciones parecen responder a la misma solicitud, la LLM tiene que adivinar y la tasa de selección correcta disminuye.
| Pregunta | Contrato sólido | Contrato débil |
|---|---|---|
| ¿Cuándo usarlo? | La descripción expresa la intención y el contexto. | “Hace cosas” o “gestiona”. |
| ¿Qué recibes? | Solo los datos necesarios. | Objeto genérico e ilimitado. |
| ¿Qué devuelve? | Estado y próxima acción verificables. | Texto sin protocolo. |
| ¿Cómo falla? | Código, motivo y recuperación. | Excepción opaca. |
Haz
- ✓ Usa verbos específicos.
- ✓ Delimita las entradas.
- ✓ Declara la evidencia.
Evita
- ✗ Mezclar intenciones.
- ✗ Aceptar cualquier objeto.
- ✗ Ocultar efectos.
buscar_cursos({ tema, nivel })
consultar_curso({ cursoId })
verificar_vagas({ cursoId, turmaId })Profundiza: evidencia que vale la pena guardar
Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.
Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.
Conceptos clave
sin superposición
verbo preciso
límite claro
salida propia
Diseña las entradas para el agente
Qué es: La entrada debe pedir solo los datos necesarios y representar las alternativas cerradas con enums cuando sea posible.
Por qué aprender: Los schemas enfocados reducen los argumentos inventados, pero la validación real sigue siendo obligatoria en execute y en el backend.
Observa
Captura el estado, la entrada y el contexto antes de la acción.
Decide
Valida las precondiciones y elige la transición permitida.
Ejecuta
Aplica la regla compartida y respeta la cancelación.
Demuestra
Actualiza la interfaz y devuelve un resultado estructurado.
Punto de control
Si el paso 2 no se aprueba, la tool no intenta «arreglárselas»: devuelve una recuperación explícita.
nivel: {
type: "string",
enum: ["iniciante", "intermediario", "avancado"]
}Profundiza: evidencia que vale la pena guardar
Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.
Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.
Conceptos clave
campos mínimos
enum útil
descripción concreta
validación real
Elige IDs y nombres comprensibles
Qué es: El agente puede conocer el nombre que menciona el usuario antes de conocer el identificador interno del sistema.
Por qué aprender: Separar la búsqueda, la resolución y la acción evita exigir IDs opacos demasiado pronto o aceptar nombres ambiguos demasiado tarde.
CÓDIGO DE REFERENCIA
const curso = await buscar_cursos({ tema: "WebMCP" });
await consultar_curso({ cursoId: curso.id });Es pequeña, está descrita y se puede validar.
Reutiliza la regla real de la aplicación.
Permite verificar el efecto y continuar.
Lee el código como contrato
Subraya dónde se valida la entrada, dónde ocurre el efecto, dónde llega la cancelación y dónde se actualiza la UI.
Profundiza: evidencia que vale la pena guardar
Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.
Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.
Conceptos clave
el nombre permite descubrir
ID identifica
resolución explícita
ambigüedad tratada
Registra solo lo que tiene sentido ahora
Qué es: El catálogo debe reflejar la ruta, la selección, la autenticación y la etapa actual del recorrido.
Por qué aprender: Menos herramientas disponibles significan menos contexto y menos llamadas imposibles.
Fallo provocado
Ejecuta el escenario con estado ausente, entrada no válida o capacidad no disponible.
Recuperación esperada
La respuesta informa qué falló, qué sigue siendo seguro y qué acción puede continuar.
Matriz mínima de pruebas
✓ camino feliz reproducible
✓ entrada inválida accionable
✓ la cancelación termina el trabajo
✓ el fallback preserva el recorrido
✓ la interfaz refleja el estado
✓ el backend mantiene la autorización
await modelContext.registerTool(confirmarInscricao, {
signal: etapaConfirmacao.signal
});Profundiza: evidencia que vale la pena guardar
Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.
Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.
Conceptos clave
catálogo contextual
registro dinámico
sesión visible
cleanup
Refactoriza un catálogo deficiente
Qué es: Los nombres genéricos y superpuestos deben convertirse en una secuencia que revele la intención y el efecto.
Por qué aprender: La entrega demuestra que el catálogo orienta al agente y también explica el flujo a producto, seguridad y QA.
Ejercicio de síntesis
- 1. Explica el problema sin usar el nombre de la tecnología.
- 2. Diseña el estado anterior y el posterior.
- 3. Implementa la prueba funcional más pequeña.
- 4. Provoca un fallo y registra la recuperación.
- 5. Entrega código, evidencia y una limitación conocida.
Desafío del módulo
Refactoriza un catálogo ambiguo en una secuencia de tools con responsabilidades únicas y criterios de selección.
Criterio del Integrator responsable
La entrega debe funcionar, explicar sus límites y preservar la opción humana cuando la capacidad experimental no esté disponible.
// antes
curso(); gerenciar_curso(); resolver_inscricao();
// depois
buscar_cursos(); iniciar_inscricao(); confirmar_inscricao();Profundiza: evidencia que vale la pena guardar
Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.
Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.
Conceptos clave
inventario
refactorización
prueba de selección
documentación
📦 Entrega del módulo
Refactoriza un catálogo ambiguo en una secuencia de tools con responsabilidades únicas y criterios de selección.
Criterio de aceptación
La entrega funciona con soporte de WebMCP y mantiene la opción manual cuando la API no existe.
Evidencia
Incluye código, escenario probado, resultado observado y una limitación conocida.
Fuentes técnicas
- Draft y repositorio oficial de WebMCP
- Especificación renderizada
- Snapshot oficial: 26/08/2026 · commit 41d12f0. La API declarativa sigue siendo experimental; valida el draft antes de producción.