Contrato de herramientas

Referencia de lo que el Gateway envía a cada herramienta y de lo que espera de vuelta.

Métodos del protocolo

El Gateway solo acepta resultados con resultType: "complete", que es lo que el SDK emite por defecto. El patrón de varias vueltas (input_required) no se consume: toda herramienta se resuelve en una sola llamada.

Transporte

• Un único endpoint HTTPS POST, certificado válido.
• Sin estado: la revisión 2026-07-28 eliminó las sesiones de protocolo y el saludo de inicialización. Cada petición es autónoma.
• Cabeceras estándar Mcp-Method y Mcp-Name en cada POST.
• Sin reanudación de flujo: si la conexión se corta antes de recibir la respuesta, el Gateway reintenta como petición nueva, con un identificador de petición nuevo y la misma clave de idempotencia. De ahí la exigencia de la garantía 1. Esto es distinto de un tiempo de espera agotado: ahí el Gateway no reintenta, informa al agente y la conversación sigue sin la herramienta.
• tools/list DEBERÍA devolver las herramientas en orden estable. El propio estándar lo recomienda: un orden cambiante invalida la caché del modelo y degrada la latencia.

Definición de una herramienta

{
  "name": "abrir_caso_soporte",
  "title": "Abrir caso de soporte",
  "description": "Registra un caso de soporte para un cliente identificado y devuelve su número de radicado. Úsala solo cuando el cliente ya describió el problema. No la uses para consultar el estado de un caso existente.",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["documento", "tipo", "descripcion"],
    "properties": {
      "documento":   { "type": "string", "maxLength": 20 },
      "tipo":        { "enum": ["falla", "instalacion", "cobro"] },
      "descripcion": { "type": "string", "maxLength": 400 },
      "prioridad":   { "type": ["string", "null"], "enum": ["alta", "normal", null] }
    }
  },
  "outputSchema": {
    "type": "object",
    "required": ["radicado", "estado"],
    "properties": {
      "radicado":  { "type": "string" },
      "estado":    { "enum": ["abierto", "en_cola"] },
      "sla_horas": { "type": "integer" }
    }
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true
  }
}

Reglas del esquema

Clasificación de la herramienta: _meta en su definición

Cada herramienta DEBE declarar en el _meta de su propia definición a qué escenario del agente pertenece y con qué verbo se le describe al modelo. No se manda en un archivo aparte ni se configura en un panel: viaja con el catálogo, así que cuando usted añade una herramienta, ya viene clasificada.

{
  "name": "abrir_caso_soporte",
  "description": "…",
  "inputSchema": { "…": "…" },
  "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true },
  "_meta": {
    "com.asixto/capabilities": ["pqr", "soporte", "garantia"],
    "com.asixto/verb": "abrir un caso de soporte"
  }
}

Nombres y longitudes

• snake_case, verbo + entidad: consultar_cliente, crear_cita, mover_etapa.
• Estables. Renombrar equivale a publicar otra herramienta y obliga a recertificar.
• El prefijo lo pone el Gateway; no aparece en su servidor.

Descripciones

La descripción es el texto que decide si el agente acierta al elegir la herramienta. No es documentación interna.

• Una o dos frases: qué hace y cuándo NO usarla.
• Sin tono, sin marca, sin instrucciones dirigidas al modelo ("responde amablemente…"). Esa capa la pone el agente; si usted la duplica, entra en conflicto.
• Sin datos volátiles (precios, horarios, inventario): eso va en la respuesta, no en la descripción, que se cachea.

Anotaciones y su efecto

Las anotaciones son pistas, no autoridad: el estándar las define como no verificables por el consumidor. El Gateway las usa para clasificar el nivel; la decisión de exponer o no es del control de acceso de Asixto y de la configuración del tenant. Declarar de solo lectura una herramienta que escribe es un incumplimiento de contrato y bloquea la certificación.

Metadatos que envía el Gateway

Van en el campo _meta de los params de tools/call, no en arguments. Esto es deliberado: _meta es el punto de extensión que define el propio estándar, así que su inputSchema puede seguir cerrado sin rechazar nada. El SDK se los entrega sin que usted declare nada.

{
  "method": "tools/call",
  "params": {
    "name": "abrir_caso_soporte",
    "arguments": { "documento": "CC1032…", "tipo": "falla", "descripcion": "…" },
    "_meta": {
      "com.asixto/idempotencyKey": "9f2a7c…",
      "com.asixto/conversationId": "cnv_77b…",
      "com.asixto/requestId": "req_c41…",
      "com.asixto/channel": "voice",
      "com.asixto/companyId": "cmp_31a…",
      "com.asixto/priceListId": "pl_mayorista",
      "com.asixto/currency": "COP",
      "com.asixto/timezone": "America/Bogota"
    }
  }
}

Forma de la respuesta

• content: texto breve para el modelo. Es lo que puede terminar leído en voz alta.
• structuredContent: los datos, conformes a su outputSchema.

Devuelva datos ya resueltos: el nombre en vez del identificador, el precio final en vez de sus componentes, la fecha completa en vez de un código interno. Una respuesta pensada para una tabla en pantalla no sirve en una llamada telefónica.

Tamaño: 3.000 caracteres. No es un consejo: el runtime sanea y recorta a 3.000 caracteres todo resultado antes de inyectarlo al modelo, dejando una marca de truncado. No es un error, así que su servidor no se entera: simplemente el agente responde con datos incompletos. Si su respuesta natural es más grande, pagine (página 07).

Una búsqueda sin resultados es un éxito, no un error. Devuelva la lista vacía y el total en 0. Si la reporta como error, el agente entra en la rama de fallo técnico y reintenta o cambia de paso en vez de decirle al cliente, con naturalidad, que no encontró nada.

Prohibido en la respuesta: identificadores internos, datos de terceros, campos administrativos, trazas, tokens. El resultado entra al contexto del modelo y queda en la traza de la conversación.

Un fallo de negocio usa la misma respuesta, marcada como error. No es un error de transporte: se devuelve con isError: true y el objeto de error en structuredContent. La forma exacta y los seis valores admitidos están en la página 06.

{
  "isError": true,
  "content": [{ "type": "text", "text": "{\"error\":{…}}" }],
  "structuredContent": { "error": { "error_type": "NOT_FOUND", "user_message": "No encontré una cita con esos datos." } }
}

El campo resultType que exige el estándar lo pone el SDK, no usted.

Media (imágenes, PDF, audio): no en la v1. El envío de archivos por el canal exige un identificador de media resuelto contra el backend de Asixto; una URL o un adjunto que devuelva su herramienta no se le entrega al cliente final, y en llamada se elimina del texto. Si su caso de uso lo necesita, escálelo antes de construirlo.