Mejores prácticas de tool calling para agentes: por qué tu agente elige la herramienta equivocada

Mejores prácticas de tool calling para agentes: por qué tu agente elige la herramienta equivocada

Las mejores prácticas de tool calling para agentes son lo que separa una demo que funciona de un agente que, en producción, llama en silencio a la herramienta equivocada. El equipo de ingeniería de Anthropic midió cómo una sola descripción reescrita recortaba el resultado de una herramienta de 206 tokens a 72, y Claude Code ahora limita a la fuerza toda respuesta de herramienta a 25.000 tokens porque la sangría es real. Tu agente falla de cuatro maneras: herramienta equivocada, argumentos incorrectos, bucle descontrolado y fuga de tokens, y cada una tiene una solución que puedes lanzar esta semana.

Conclusiones clave:

• El tool calling de agentes falla de exactamente cuatro maneras: herramienta equivocada, argumentos incorrectos, bucles descontrolados y fuga de tokens.
• Las descripciones de herramientas son la única instrucción que el modelo ve en el momento de elegir, así que corrigen la mayoría de las llamadas a la herramienta equivocada.
• Los esquemas planos, con forma de tarea y con entradas validadas eliminan la mayoría de los fallos de argumentos incorrectos.
• Las respuestas de herramienta concisas y un bucle de evaluación en cada cambio mantienen medibles el coste de tokens y las regresiones.

¿Por qué falla el tool calling de agentes en producción?

El tool calling de agentes falla de cuatro maneras: el modelo elige la herramienta equivocada, escribe argumentos incorrectos, gira en un bucle descontrolado o pierde tokens con respuestas gordas. Cada fallo golpea un paso distinto del bucle de llamadas, así que el orden de las correcciones importa. Empieza por la selección, porque una elección de herramienta equivocada envenena todos los pasos posteriores.

La receta completa de un vistazo:

Recórrelas en este orden. Las prácticas 1 y 2 toman una tarde y eliminan la mayoría de los fallos de herramienta equivocada y argumentos incorrectos que ves hoy. Una descripción de herramienta no es documentación. Es la única instrucción que el modelo recibe en el momento de elegir.

Fase 1: Diseña herramientas que el modelo realmente pueda usar

Las ganancias de fiabilidad más baratas en el tool calling de agentes están en tus definiciones de herramientas, no en tus prompts ni en tu elección de modelo. El modelo nunca lee tu documentación de API ni tu README. Ve un nombre, una cadena de descripción y un esquema JSON, y decide solo con eso. Acierta con esos tres y la precisión de selección mejora antes de que toques nada más.

Práctica 1: Escribe descripciones que el modelo pueda seguir

Escribe las descripciones de herramientas como instrucciones para el modelo, no como documentación de API. Una descripción que satisface a un desarrollador humano («wrapper REST para el endpoint de usuarios») no le da al modelo nada con lo que decidir. La guía de ingeniería de Anthropic sobre cómo escribir herramientas y sus buenas prácticas de definición de herramientas empujan el mismo patrón: di cuándo usar la herramienta, qué devuelve y cuándo NO usarla.

{
  "name": "get_user",
  "description": "Fetches a user profile. Use ONLY when you already have a user_id. Do NOT use to search or list users; call search_users instead. Returns name, email, plan. Errors if user_id is not a valid UUID."
}

frente a la versión que la mayoría de los equipos lanza:

{
  "name": "get_user",
  "description": "Gets a user."
}

Dos reglas hacen la mayor parte del trabajo aquí. Primero, nombra los parámetros para que su significado sea inequívoco: user_id, nunca user ni id, porque user invita al modelo a pasar un nombre o un email donde va un UUID. Segundo, declara las exclusiones explícitamente. «No usar para buscar usuarios» evita más llamadas a la herramienta equivocada que cualquier cantidad de descripción positiva, porque los modelos confunden herramientas solapadas mucho más a menudo de lo que malinterpretan herramientas únicas y claramente delimitadas. Para la mecánica a nivel de proveedor de cómo estas definiciones llegan a las APIs de OpenAI, Anthropic y Google, consulta nuestra guía de function calling multiproveedor.

Práctica 2: Mantén los esquemas planos y con forma de tarea

Mantén los esquemas de entrada planos, con todos los campos que la tarea realmente necesita y ninguno que no. Los objetos anidados con ramas opcionales son el caldo de cultivo de los fallos de argumentos incorrectos: el modelo debe inferir una estructura de la que nunca ve ejemplos. La guía de function calling de OpenAI acepta cualquier JSON Schema, pero permisivo no es lo mismo que fiable.

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "ticket": {
        "type": "object",
        "properties": {
          "details": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "meta": { "type": "object" }
            }
          }
        }
      }
    }
  }
}

Aplánalo a la tarea:

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high"] },
      "assignee_id": { "type": "string" }
    },
    "required": ["title", "priority"]
  }
}

Los enums ganan al texto libre en cualquier campo con un conjunto acotado de valores. Los arrays de campos requeridos ganan a que todo sea opcional. Si el modelo casi siempre necesita un campo, hazlo requerido en el esquema de la herramienta incluso cuando tu API lo llame opcional. No estás reflejando tu API. Estás diseñando una superficie que un modelo concreto pueda rellenar correctamente.

Fase 2: Gestiona el conjunto de herramientas, no solo las herramientas

La calidad individual de las herramientas deja de ser suficiente cuando un agente carga más de un puñado de ellas, porque los errores de selección crecen con el tamaño de la lista que lee el modelo.

Práctica 3: Envuelve las secuencias de API multipaso en herramientas atómicas

Colapsa cualquier secuencia fija de llamadas de API en una sola herramienta atómica. La publicación de ingeniería de Anthropic usa schedule_event y get_customer_context como modelo: una llamada que hace todo el trabajo gana a tres llamadas que el agente debe encadenar correctamente cada vez. Cada eslabón de una cadena es otro turno donde el modelo puede atascarse, reintentar mal o entrar en bucle.

# What the agent does WITHOUT an atomic tool: 3 calls, 3 chances to fail
calendar = call_tool("list_calendars", {})
free = call_tool("find_free_slot", {"calendar_id": calendar["items"][0]["id"], "duration": 30})
call_tool("create_event", {"calendar_id": calendar["items"][0]["id"], "start": free["start"]})

# One atomic tool: the sequence lives in your code, not the model's head
call_tool("schedule_event", {"duration": 30, "attendees": ["[email protected]"]})

La regla práctica: si el modelo siempre debe llamar a B después de A, A y B son una herramienta con dos disfraces.

Práctica 4: Usa espacios de nombres, poda y filtra las herramientas dinámicamente

Pon un espacio de nombres a cada herramienta y muestra a cada agente solo el subconjunto que su tarea actual necesita. Los nombres genéricos colisionan en el momento en que conectas dos integraciones. Imagina un agente conectado a dos servidores MCP que ambos exponen una herramienta llamada search: dos verbos idénticos, sin forma de distinguirlos. Anthropic documenta mejoras medibles en evaluaciones gracias a los espacios de nombres con prefijo:

Podar importa tanto como nombrar. Un agente de soporte no necesita sus herramientas de facturación cargadas mientras responde una pregunta de contraseña. El patrón planificador-trabajador, donde un planificador enruta una tarea a un trabajador que carga solo las herramientas relevantes, es la solución estándar; el how-to de LangGraph sobre carga dinámica de herramientas recorre la implementación. ¿Cuántas herramientas son demasiadas? Trata 5-10 por agente como un rango de trabajo, no como una ley: la precisión se degrada a medida que la lista crece, y la cura es el filtrado, no un modelo más grande. Si estás eligiendo la propia capa de enrutamiento y filtrado, compara tus opciones en nuestro resumen de las mejores bibliotecas de function calling.

Fase 3: Controla lo que vuelve y lo que sale

El bucle corre en ambas direcciones, y la mayoría de los equipos solo diseña la mitad saliente. Lo que tus herramientas devuelven determina cuánto de la ventana de contexto sobrevive hasta el siguiente turno, y lo que tu validación rechaza determina si el modelo aprende de sus errores o los repite.

Práctica 5: Devuelve resultados concisos y con mucha señal

Devuelve el resultado más pequeño con el que el modelo pueda actuar, con identificadores legibles por humanos en lugar de IDs crudos. La publicación de ingeniería de Anthropic documenta una herramienta cuyo resultado por defecto llegaba a 206 tokens; un ajuste conciso de response_format cortó el mismo resultado a 72 tokens, más o menos un tercio del tamaño. Multiplica eso por docenas de llamadas por tarea y decide si tu agente llega a terminar.

// Before: 206 tokens (shape per Anthropic's documented example)
{
  "status": "success",
  "data": {
    "id": "8f14e45f-ceea-3f9c-a2f3-90c1b5e0a7d2",
    "object": "task", "created_at": "2026-07-02T09:14:00Z",
    "updated_at": "2026-07-11T16:40:12Z", "completed_at": null,
    "assignee": {"id": "c9a1...f2", "object": "user"},
    "projects": [{"id": "b7d3...91", "object": "project"}],
    "permalink": "https://app.asana.com/0/.../f"
  }
}

// After: 72 tokens
{ "task": "Fix login redirect", "assignee": "Dana Kim", "project": "Web App", "due": "2026-07-20" }

Dos detalles más de la misma fuente: Anthropic soporta un enum response_format (detallado frente a conciso) en las definiciones de herramientas, así que puedes declarar la forma que quieres en lugar de parsear la manguera. Y Claude Code limita las respuestas de herramientas a 25.000 tokens, un techo duro que trunca los resultados inflados de todos modos. Anthropic también reporta, como hallazgo suyo, que resolver UUIDs a nombres semánticos redujo de forma medible las alucinaciones de recuperación, y por eso el payload «después» de arriba dice «Dana Kim» y no c9a1...f2. Las respuestas gordas son también un problema de coste; consulta nuestra guía para reducir costes de API de LLM para la imagen completa.

Práctica 6: Valida cada llamada y haz que los errores enseñen al modelo

Valida cada llamada de herramienta en el servidor y devuelve errores que contengan la solución. El artículo de Martin Fowler sobre function calling lo plantea sin rodeos: nunca confíes en la salida del modelo. Pasará cadenas donde van enums e inventará IDs que no existen.

def create_ticket(args):
    if args.get("priority") not in {"low", "medium", "high"}:
        return {"error": f"priority must be one of: low, medium, high. Got '{args.get('priority')}'. Pass priority='medium' for normal issues."}
    if not is_valid_uuid(args.get("assignee_id")):
        return {"error": "assignee_id must be a UUID. Call list_team_members to get valid IDs, then retry."}
    return db.create_ticket(**args)

La cadena de error es todo el juego. Compara:

# Unhelpful: the model retries the same bad call
{"error": "invalid input"}

# Helpful: the model knows exactly what to change
{"error": "priority must be one of: low, medium, high. Got 'urgent'. Use 'high'."}

Cada error de validación que tu herramienta devuelve es un prompt que estás escribiendo para el siguiente intento del modelo. Los errores que nombran la restricción y apuntan a la herramienta correctora convierten un bucle de reintentos en una recuperación de un solo tiro. Esta es también tu primera línea de defensa de seguridad; nuestra guía de guardrails de LLM lo cubre en profundidad.

Fase 4: ¿Cómo lo haces seguro y luego medible?

La seguridad y la medición son la misma fase porque una acción destructiva sin control y una regresión no medida afloran ambas como incidentes que no viste venir. Pon tras una confirmación las acciones que no se pueden deshacer y luego instrumenta todo para que el próximo cambio de herramienta sea una decisión con evidencia detrás, no una esperanza.

Práctica 7: Pon las acciones destructivas tras una confirmación humana

Separa las herramientas de lectura de las de escritura y pon una confirmación humana en cualquier cosa destructiva. Las anotaciones de herramientas de la especificación MCP existen exactamente para esto: destructiveHint marca las herramientas que realizan actualizaciones destructivas, y openWorldHint señala las herramientas que tocan sistemas externos, para que los clientes puedan preguntar antes de ejecutar. Úsalas.

El modo de fallo no es hipotético. Laurent Kubaski documentó un caso, en su análisis de tool calling de julio de 2025 con el informe original enlazado, donde un usuario pidió a Copilot en Excel que actuara sobre la fila 4 y el agente actuó sobre la fila 8. Ninguna confirmación se interponía entre la fila equivocada y la escritura. La solución es el patrón que AWS documenta para Bedrock Agents: el agente prepara la acción, la devuelve para aprobación y solo ejecuta después de que un humano confirma. Cursor hace lo mismo con las ediciones de archivos. Limita las credenciales a solo lectura cuando leer es todo lo que la tarea necesita, y trata las confirmaciones como parte de tu superficie de inyección, el tema de nuestra guía de prevención de prompt injection.

Práctica 8: Ejecuta un bucle de evaluación en cada cambio de herramienta

Ejecuta un pequeño conjunto de evaluación antes y después de cada cambio de herramienta, y lee las métricas en un orden fijo. La guía de optimización de Paragon propone un marco de cuatro métricas que vale la pena adoptar:

El cookbook de evaluación de herramientas de Anthropic, construido sobre evaluaciones reales de MCP de Slack y Asana, muestra cómo se ven las tareas de evaluación buenas y malas:

# Weak: vague, many valid paths, impossible to score
"Use the Asana tools to organize some work."

# Strong: one correct tool, checkable arguments, binary outcome
"Create a task titled 'Renew TLS cert' in project 'Infra' assigned to [email protected], due 2026-08-15. Expect exactly one create_task call with those four fields."

Nuestra interpretación, etiquetada como tal: los números publicados te dan el orden de trabajo. Comprueba primero la corrección de herramienta, porque las propias mediciones de Anthropic muestran que los cambios de descripción y de nombres la mueven directamente (la reescritura de 206 a 72 tokens, el hallazgo de alucinación de UUID a nombre), y deja la eficiencia de tarea para el final, ya que sobre todo refleja fallos que las tres primeras métricas ya detectaron. Para el conjunto inicial, diseña 15-30 tareas, dos o tres por herramienta, cada una con una sola llamada esperada y una condición binaria de aprobado. Ese tamaño basta para detectar una regresión de una reescritura de descripción sin una semana de etiquetado, y leemos la configuración de Slack y Asana del cookbook como evidencia de que un conjunto así de pequeño es el punto de partida previsto, no un atajo. La mecánica más profunda vive en nuestra guía sobre evaluar agentes de IA en producción, y si tus resultados de evaluación dicen que las herramientas en sí están bien pero la orquestación no, ese es el momento de revisar tu elección de framework frente a los mejores frameworks de agentes de IA.

Tool calling de agentes frente a MCP: ¿cuál es la diferencia?

MCP es un estándar de transporte y registro, no una capa de fiabilidad, así que las mismas ocho prácticas se aplican tanto si tus herramientas llegan por MCP como si están definidas en línea. El tool calling nativo es el contrato del proveedor del modelo: cómo el modelo emite un tool_call y lee un tool_result. MCP estandariza cómo las herramientas llegan al modelo; no hace nada sobre si el modelo elige la correcta.

Un servidor MCP que expone una herramienta llamada search con la descripción «busca cosas» falla de forma idéntica a una función en línea definida igual. Arregla la definición y luego preocúpate por el transporte. Nuestra guía de Model Context Protocol cubre el lado del protocolo de extremo a extremo.

Cómo aplica Techsy estas ocho prácticas

En cada construcción de agente para clientes, hacemos cumplir tres de estas antes de que nada salga: descripciones escritas como instrucciones (Práctica 1), validaciones en cada herramienta de escritura (Práctica 6) y un conjunto de evaluación que corre antes del despliegue, no después de un incidente (Práctica 8). Esas tres cubren las llamadas a la herramienta equivocada, las llamadas con argumentos incorrectos y las regresiones que reintroducen ambas, que es donde empezó cada incidente de agente en producción que hemos depurado. Las otras cinco prácticas siguen a medida que el agente crece. Si tu agente pasó de la fase de demo y elige las herramientas equivocadas, obtén una consulta gratuita y te diremos cuál de las ocho arreglar primero.

Preguntas frecuentes

¿Qué es el tool calling de agentes?

El tool calling de agentes es el mecanismo por el que un LLM decide invocar una función externa, emite un tool_call estructurado y espera a que tu código devuelva un tool_result sobre el que razonar. Es lo que convierte un modelo de chat en un agente que puede consultar bases de datos, llamar a APIs y ejecutar acciones: el modelo elige la herramienta y los argumentos, tu ejecutor los corre.

¿Cómo funciona el bucle de tool calling de agentes?

El bucle tiene cinco pasos: la petición del usuario llega al modelo, el modelo elige una herramienta y escribe un tool_call, tu ejecutor lo corre, un tool_result vuelve al modelo y el modelo responde o emite otra llamada. Ese ciclo se repite hasta que la tarea termina. Los cuatro modos de fallo de esta guía viven cada uno en un paso concreto de este bucle.

¿Por qué mi agente elige la herramienta equivocada?

Normalmente porque dos herramientas se solapan y sus descripciones no dicen cuál es cuál. El modelo elige solo por nombres y descripciones, así que «obtiene un usuario» frente a «busca usuarios» se lee como intercambiable. Arréglalo con líneas de exclusión («no usar para buscar»), nombres con espacio de nombres y menos herramientas en contexto. La prueba con cuatro modelos de Kubaski mostró que incluso modelos fuertes se equivocan con listas ambiguas.

¿Cómo obligo a un agente de tool calling a estructurar su salida?

Restringe el esquema, no el prompt. Usa enums para campos acotados, arrays de requeridos para todo lo que la tarea necesite y objetos planos en lugar de anidados. Para la respuesta final en vez de la llamada a herramienta, funciones del proveedor como las salidas estructuradas de OpenAI y los modos tool-choice de Anthropic fuerzan una forma concreta. Nuestra guía de salidas estructuradas cubre ambos caminos con código.

Tool calling de agentes frente a MCP: ¿cuál es la diferencia?

El tool calling nativo es el contrato entre tu código y un proveedor de modelo: el formato de mensajes tool_call y tool_result. MCP es una capa de protocolo que estandariza cómo se descubren y entregan las herramientas a cualquier cliente compatible. MCP cambia la fontanería, no la fiabilidad. Una herramienta mal descrita falla igual por cualquiera de los dos caminos, como explica nuestra guía de Model Context Protocol.

¿Cuántas herramientas son demasiadas para un agente LLM?

Trata 5-10 herramientas por agente como un rango de trabajo, no como una ley. La precisión de selección se degrada a medida que la lista visible crece, sobre todo cuando nombres o descripciones se solapan. La solución no es un modelo más grande sino filtrado: carga solo el subconjunto que la tarea actual necesita, usando una división planificador-trabajador. Pon espacio de nombres a todo para que dos integraciones nunca expongan ambas un search desnudo.

¿Cuál es el mejor modelo para tool calling?

No hay una única respuesta, y los benchmarks publicados envejecen mal en este campo. Los modelos frontera de OpenAI, Anthropic y Google superan todos las tareas básicas de uso de herramientas, mientras que modelos más pequeños emparejados con herramientas bien diseñadas a menudo completan tareas casi con la misma frecuencia por una fracción del coste de tokens. Construye el conjunto de evaluación de 15-30 tareas de la Práctica 8 y prueba los candidatos contra tus propias herramientas.

¿Cómo reduzco el coste de tokens del tool calling?

Corta lo que vuelve. Devuelve resultados concisos y con mucha señal en lugar de payloads crudos de API: Anthropic documentó un corte de 206 a 72 tokens por un solo cambio de response_format. Resuelve UUIDs a nombres, elimina campos que el modelo nunca usa y recuerda que cada resultado de herramienta vuelve a entrar en la ventana de contexto en cada turno siguiente. Menos llamadas, vía herramientas atómicas, quita resultados enteros de la factura.

¿Cómo evalúo la calidad del tool calling?

Puntúa cuatro métricas en orden: corrección de herramienta (¿herramienta correcta?), precisión de entrada (¿argumentos válidos?), finalización de tarea (¿objetivo logrado?) y eficiencia de tarea (¿número de tokens y llamadas?). Escribe 15-30 tareas, cada una esperando una llamada concreta con argumentos comprobables y una condición binaria de aprobado. Ejecuta el conjunto antes y después de cada cambio de herramienta para que una reescritura de descripción nunca salga sin medir.

Conclusión

Diagnostica antes de optimizar. Tu agente elige la herramienta equivocada por una de cuatro razones, y tres de las ocho prácticas de arriba, descripciones, esquemas planos y filtrado, corrigen los fallos de selección que causan la mayoría de los incidentes en producción. Empieza ahí, porque cuestan una tarde y son la razón de que este problema se pueda arreglar. Mantén los errores de validación informativos, pon cualquier cosa destructiva tras una confirmación humana y ejecuta el bucle de evaluación en cada cambio para medir antes de cambiar de modelo. El problema de la herramienta equivocada no es un problema de modelo. Es un problema de diseño de herramientas, y el diseño es tuyo.