Una publicación de r/openclaw preguntó por qué su asistente es tonto. La respuesta rara vez es el LLM y casi siempre el nombre o la atribución de herramientas. Esto sigue el patrón de depuración.
Requisitos previos
- Un agente fallido
- Registro configurado para capturar llamadas a herramientas
- Paciencia para leer entre 5 y 10 rastros reales
Guia paso a paso
Paso 1: Capture cada llamada a la herramienta con nombre + argumentos + resultado
La mayoría de los marcos de agentes registran esto; enciéndelo.
Text
# OpenClaw: set CLAW_LOG_LEVEL=DEBUG
# LangChain: callbacks=[StdOutCallbackHandler()]
# Inspect 5-10 actual traces before guessing the issue.Paso 2: Comprobar la semántica del nombre de la herramienta
Las herramientas llamadas search_v1, fetch_url, do_thing fallan más que las herramientas llamadas web_search, reddit_search, extract_markdown.
Text
# Bad: name='search', description='search the web'
# Good: name='reddit_search', description='Search Reddit threads. Returns posts with score and comment_count.'Paso 3: Verifique las descripciones de las herramientas para detectar ambigüedades
Si dos herramientas tienen descripciones superpuestas, el LLM elige mal con frecuencia.
Text
# Common bug: 'search' and 'web_search' both attached. LLM guesses.
# Fix: keep only one, with a clear description.Paso 4: Reducir el número de herramientas adjuntas
Los agentes con más de 12 herramientas obtienen puntuaciones más bajas que los agentes con entre 4 y 6 herramientas bien nombradas.
Text
# If the agent has access to 15 MCP servers, drop to 4-6 you actually need per task.
# Scavio MCP exposes 11 tools but they have unambiguous names; multi-MCP setups usually conflict.Paso 5: Agregar andamiaje explícito de selección de herramientas
Si el enrutamiento sigue siendo incorrecto, anteponga un paso "elija su herramienta".
Text
# System prompt addition:
# 'For each user request, first state which tool you will use and why. Then call it.'
# Improves routing accuracy on agents with 5+ tools.Ejemplo en Python
Python
# Debug protocol: log -> read 10 traces -> rename / dedupe tools -> retest. 90% of 'dumb agent' issues end here.Ejemplo en JavaScript
JavaScript
// Same debug protocol works for any agent framework, JS or Python.Salida esperada
JSON
Agent that picks the right tool first try. The LLM rarely needs upgrading; the tool surface usually does.