Empieza por la solicitud del usuario
Qué es: El descubrimiento comienza con la intención, las restricciones y el estado actual, no con la enumeración ciega de todas las tools.
Por qué aprender: Un objetivo normalizado reduce el ruido incluso antes de presentar capacidades al modelo.
Antes de modelar
Escribe la solicitud de la persona, el estado actual y la evidencia que probará que se completó.
Error de inicio
Empezar por el nombre de una función o por un botón produce una herramienta 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.
const objetivo = { acao: "buscar", entidade: "curso", tema: "WebMCP", nivel: "iniciante" };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 WebMCP.
Conceptos clave
intención
restricciones
contexto
criterio de éxito
Lee el catálogo como contrato
Qué es: El nombre, la descripción, inputSchema y annotations conforman la interfaz que el agente puede usar para razonar.
Por qué aprender: Tratar el descriptor como dato permite validarlo, indexarlo, compararlo y registrar decisiones.
| Pregunta | Contrato sólido | Contrato débil |
|---|---|---|
| ¿Cuándo usarlo? | La descripción nombra la intención y el contexto. | “Hace cosas” o “administra”. |
| ¿Qué recibe? | 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. |
Hazlo
- ✓ Usa verbos específicos.
- ✓ Delimita las entradas.
- ✓ Declara la evidencia.
Evita
- ✗ Mezclar intenciones.
- ✗ Aceptar cualquier objeto.
- ✗ Ocultar efectos.
const tools = await document.modelContext.getTools();
for (const tool of tools) validarDescritor(tool);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 WebMCP.
Conceptos clave
name
description
inputSchema
annotations
Filtra antes de llamar al modelo
Qué es: Las reglas deterministas eliminan las tools incompatibles con la ruta, la autenticación, el riesgo o la entidad.
Por qué aprender: El filtro reduce los tokens e impide opciones que ya sabemos que son inválidas.
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 la etapa 2 falla, la tool no intenta «arreglarlo»: devuelve una recuperación explícita.
const candidatas = tools.filter(tool =>
policy.isVisible(tool, pageState, userSession)
);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 WebMCP.
Conceptos clave
ruta actual
sesión
riesgo
precondición
Crea representaciones útiles
Qué es: El agente necesita descripciones breves, esquemas completos y ejemplos coherentes, sin volcar detalles internos de implementación.
Por qué aprender: Una representación estable mejora la selección y permite comparar modelos o prompts.
CÓDIGO DE REFERENCIA
const promptTools = candidatas.map(({ name, description, inputSchema }) =>
({ name, description, inputSchema })
);Es pequeña, descriptible y validable.
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 WebMCP.
Conceptos clave
serialización
límite de contexto
ejemplo
redacción
Reacciona al catálogo efímero
Qué es: La navegación, el inicio de sesión y la selección pueden cambiar las herramientas disponibles durante la misma conversación.
Por qué aprender: El agente debe invalidar las instantáneas y volver a descubrir las capacidades cuando el documento indique un cambio.
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 prueba
✓ 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
document.modelContext.addEventListener("toolchange", () => {
catalogCache.invalidate(location.href);
});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 WebMCP.
Conceptos clave
cambio de herramienta
snapshot
invalidación
redescubrimiento
Mide la calidad del descubrimiento
Qué es: La cobertura, la precisión y la herramienta correcta en el top-k revelan si el pipeline recupera buenas candidatas.
Por qué aprender: Sin evals de descubrimiento, una respuesta final deficiente puede atribuirse al componente equivocado.
Ejercicio de síntesis
- 1. Explica el problema sin usar el nombre de la tecnología.
- 2. Diseña el estado anterior y 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
Construir un inspector que capture el catálogo actual, explique cada tool y seleccione solo las candidatas relevantes para una solicitud.
Criterio de Agent Developer responsable
La entrega debe funcionar, explicar sus límites y preservar la vía humana cuando la capacidad experimental no exista.
caso: "curso iniciante"
esperadas: ["buscar_cursos"]
proibidas: ["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 WebMCP.
Conceptos clave
recuperación
precisión
top-k
dataset
📦 Entrega del módulo
Construir un inspector que capture el catálogo actual, explique cada tool y seleccione solo las candidatas relevantes para una solicitud.
Criterio de aceptación
La entrega funciona con soporte de WebMCP y mantiene la vía 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 WebMCP
- Especificación renderizada
- Snapshot oficial: 26/08/2026 · commit 41d12f0. La API declarativa sigue siendo experimental; valida el draft antes de producción.