Dimensiona las respuestas para una ventana de contexto, no como un volcado de base de datos

Devuelve solo lo que el agente necesita para la tarea, en páginas que pueda pedir, con valores por defecto razonables, y avisa cuando cortas algo y cómo obtener el resto.

Por qué

Todo lo que devuelve una herramienta llega a la ventana de contexto del agente, que es limitada y compartida con la tarea, la conversación y el resto de resultados. Una búsqueda que devuelve 5.000 filas o un registro con todos sus campos internos puede desplazar la información que el agente sí necesita, o ser recortada por el cliente sin más. La guía de Anthropic para quien construye herramientas es directa: implementa alguna combinación de paginación, selección de rangos, filtrado y truncado, con valores por defecto razonables, en cualquier respuesta que pueda ocupar mucho contexto. Claude Code limita por defecto las respuestas de herramientas a 25.000 tokens, así que una respuesta mayor no llega entera al modelo si el servidor no la dimensiona. Cuando truncas, Anthropic recomienda orientar al agente con instrucciones, y sugiere un parámetro response_format para que el agente pida una respuesta concisa o detallada (en su ejemplo, 72 tokens frente a 206). MCP estandariza la paginación: el servidor elige el tamaño de página, devuelve un nextCursor cuando hay más resultados y debería mantener estables los cursores. Las directrices de apps de OpenAI añaden qué dejar fuera por completo: devuelve solo datos relevantes para la petición y el propósito de la herramienta, sin campos de diagnóstico, identificadores de traza o de petición ni metadatos de registro salvo que la consulta los necesite.

Haz

Pagina y filtra por defecto, ofrece un modo conciso y marca el truncado con una pista sobre cómo obtener más.

No hagas

Devolver todas las filas y todos los campos internos, ni truncar sin avisar.

Artefacto

{
  "results": [
    { "id": "ord_812", "customer": "Acme Ltd", "total": "129.00 EUR", "status": "shipped" }
  ],
  "nextCursor": "eyJwYWdlIjogMn0=",
  "truncated": true,
  "hint": "Showing 20 of 1,284 orders. Filter by status or date range, or pass nextCursor for the next page."
}

Entrada de la herramienta: { "query": "orders", "status": "shipped", "limit": 20, "response_format": "concise" }