English

Describe tus herramientas como si entrenaras a alguien nuevo

Tu agente tiene la herramienta correcta. Simplemente no la está usando. Este es el motivo: un agente de IA no lee tu código. Lee la descripción de la herramienta. Esa es toda la interfaz entre el modelo y tu función — no la implementación, no los nombres de las variables, solo el texto que escribiste para describir qué hace. Una descripción vaga produce una suposición equivocada, o ninguna suposición en absoluto.

Por qué la descripción es toda la interfaz

Cuando un agente decide qué herramienta llamar, no está razonando sobre tu código fuente — está razonando sobre la lista de herramientas disponibles y sus descripciones, comparando la solicitud del usuario con lo que cada una dice hacer. Una descripción de herramienta específica y precisa hace que el modelo produzca el resultado esperado con más frecuencia; una vaga lo deja adivinando.

Esto no es exclusivo de las "herramientas de agente" en el sentido formal. El mismo mecanismo aparece en los docstrings de funciones simples y en las definiciones de nodos específicas de cada framework. Un docstring de Python le da contexto al agente para que entienda para qué sirve la función — no solo para la persona que lee el código más tarde. En LangGraph, el docstring de un nodo le dice al LLM qué hace realmente esa función, porque las decisiones de enrutamiento del grafo dependen de que el modelo lea ese texto, no el cuerpo de la función.

La diferencia en la práctica

Compara dos descripciones de herramienta para exactamente la misma función subyacente:

• get data — no le dice casi nada al modelo. ¿Qué datos? ¿De dónde? ¿En qué condiciones debería llamarse esta en lugar de alguna otra herramienta?
• searches home inventory in Air Table — le dice al modelo exactamente cuándo recurrir a esta: el dominio (inventario del hogar), la fuente (una tabla) y la acción (buscar).

Ante una solicitud del usuario como "qué hay en mi inventario", un modelo que elige entre una docena de herramientas con nombres vagos tiene que adivinar. Ante la segunda descripción, no tiene que adivinar — la descripción ya responde la pregunta de cuándo aplica esta herramienta.

Cómo escribir descripciones que funcionan

1. Escríbela como si entrenaras a un empleado nuevo en su primer día. Indica qué hace la herramienta y cuándo alguien debería recurrir a ella — no solo su nombre.
2. Nombra el dominio, no solo la acción. "Searches home inventory" le gana a "search" — el dominio le dice al modelo cuál de varias herramientas similares aplica a la solicitud actual.
3. Cubre el caso negativo implícitamente. Si dos herramientas son fáciles de confundir, asegúrate de que cada descripción deje claro qué no hace, o qué la distingue de su vecina.
4. Aplica el mismo estándar a los docstrings de funciones, no solo a los esquemas de llamada de herramientas. Si un agente (o un framework como LangGraph) lee un docstring para decidir qué hace un nodo, ese docstring es funcionalmente lo mismo que una descripción de herramienta — escríbelo con el mismo cuidado.
5. Prueba con un prompt ambiguo. Dale al agente una solicitud que podría coincidir plausiblemente con dos herramientas y observa cuál elige. Si elige mal, el problema suelen ser las descripciones — no el modelo.

Errores comunes

• No supongas que el modelo inferirá la intención a partir del nombre de la función. Los nombres de funciones y herramientas suelen estar abreviados o ser genéricos (get_data, process); la descripción es la que carga el significado real.
• No escribas descripciones solo para un público humano. Un docstring que se lee bien en una revisión de código pero omite cuándo usar la función sigue siendo una descripción de herramienta subespecificada desde el punto de vista del agente.
• No dejes que las descripciones de las herramientas se desvíen de lo que la herramienta hace realmente. Si el comportamiento de una herramienta cambia pero su descripción no, los agentes seguirán llamándola en situaciones donde ya no aplica — este es un modo de fallo silencioso fácil de pasar por alto en las pruebas.

Recursos

• Anthropic — Tool use overview (writing effective tool descriptions)
• LangGraph — Nodes and how docstrings/descriptions inform routing