¿Para qué sirve el docstring del @tool en LangChain? La interfaz que el LLM usa para razonar
El docstring de un @tool en LangChain no es documentación para desarrolladores — es el texto que el LLM lee para decidir cuándo y cómo invocar la herramienta. Tratarlo como un prompt cambia los resultados.
Qué hace el decorator @tool
El decorator @tool de LangChain convierte una función Python estándar en una herramienta que el LLM puede invocar. Internamente, LangChain extrae tres cosas de la función para construir la descripción de la herramienta que el modelo recibe: el nombre de la función, el docstring, y el esquema de los parámetros inferido de los type hints.
Esas tres piezas se serializan en JSON y se envían al modelo junto con el mensaje del usuario. El modelo las lee y, basándose en esa descripción, decide si invocar la herramienta, con qué argumentos, y en qué orden si hay varias disponibles. El docstring es el texto principal que guía esa decisión.
La consecuencia práctica: el docstring no viaja al desarrollador que lee el código — viaja al LLM que decide si ejecutar la función. Es un fragmento de prompt embebido dentro del código Python.
Docstring vago vs preciso: la diferencia en resultados
El ejemplo más ilustrativo es una herramienta de búsqueda de tickets. La diferencia entre un docstring vago y uno preciso no es estética — produce comportamientos radicalmente distintos en producción:
@tool
def search_jira(query: str) -> str:
"""Searches Jira."""
# implementación...El LLM no sabe cuándo usarla, con qué queries, ni qué esperar como resultado. Invocaciones impredecibles.
@tool
def search_jira(query: str) -> str:
"""
Busca tickets existentes en Jira usando palabras clave.
SIEMPRE invoca esta herramienta ANTES de crear un ticket nuevo
para detectar duplicados. Devuelve una lista de tickets con su
ID, título y estado. Si no hay resultados, devuelve lista vacía.
Args:
query: Palabras clave o descripción del problema a buscar.
"""
# implementación...El docstring como fragmento de prompt
Un buen docstring de herramienta responde tres preguntas que el LLM necesita resolver en tiempo real: ¿cuándo debo usar esta herramienta? ¿Qué argumentos tiene sentido pasarle? ¿Qué voy a recibir como respuesta y cómo debo interpretarlo?
El docstring del ejemplo preciso incluye una directiva de comportamiento explícita: "SIEMPRE invoca esta herramienta ANTES de crear un ticket nuevo". Esto no es documentación — es una instrucción en mayúsculas que el modelo sigue con alta fidelidad. Es la misma técnica que se usa en los system prompts para reforzar comportamientos críticos.
Errores comunes en docstrings de herramientas
Docstring orientado al desarrollador
Describe la implementación interna ("llama a la API de Jira con autenticación OAuth") en lugar del comportamiento observable desde la perspectiva del agente.
Sin contexto de cuándo usar la herramienta
El modelo tiene que inferir cuándo es apropiado invocarla. Las inferencias son inconsistentes. Las instrucciones explícitas son deterministas.
Sin descripción del valor de retorno
El modelo no sabe cómo interpretar el resultado — si es texto plano, JSON, una lista, un booleano. Esto lleva a errores al procesar la respuesta.
Demasiado largo y genérico
Un docstring de 500 palabras que describe todos los casos edge posibles confunde más que guía. La precisión importa más que la exhaustividad.
El takeaway
¿Quieres aplicar esto en tu equipo?
En Kuuli Technologies llevamos estas metodologías a equipos reales. Escríbenos si quieres una sesión de trabajo o una consultoría sobre agentes IA y SDD.