Imported from DavinsonA/random_state_42_codefest (
arpia-bundle/.claude/skills/tool-integration/SKILL.md). Install upstream withnpx skills add DavinsonA/random_state_42_codefest --skill tool-integration. Copyright stays with the author.
Tools e integracion de APIs
El docstring ES el prompt
El modelo decide si invoca una tool leyendo su nombre, firma tipada y docstring. Un docstring de una linea produce un agente erratico. Mejorar el docstring rinde mas que cambiar de modelo.
Estructura obligatoria (ver src/tools/corpus.py como referencia):
@registry.register
def nombre_tool(arg: str, k: int = 8) -> str:
"""Una linea: que hace.
Usar cuando <condiciones concretas>.
NO usar para <casos concretos>. Para <caso limite>, hacer <alternativa>.
Args:
arg: que es, en que formato, con que restriccion.
k: que controla y cuando conviene cambiarlo del valor por defecto.
Returns:
Que devuelve y que pasa si no hay resultados.
"""Reglas
- Una tool nunca lanza excepcion hacia el grafo. El decorador
@registry.registercaptura y devuelve texto de error legible para que el agente decida que hacer. - Devuelve texto o dicts serializables, nunca objetos arbitrarios.
- Clasifica por riesgo: lectura libre; escritura acotada a su espacio; accion irreversible con confirmacion humana.
- Minimo privilegio en credenciales de servicios externos.
MCP: cuando SI y cuando NO
MCP anade una capa de orquestacion entre agente y tools. Vale la pena si varios agentes comparten muchas tools, o si el control de permisos debe centralizarse. No vale la pena si es un agente con pocas tools: anade latencia y una dependencia mas. Una funcion de Python simple no necesita envolverse en MCP.
Integracion de APIs externas
httpxcontimeoutexplicito. Sin timeout, un servicio lento cuelga el grafo.- Cachea respuestas de APIs con rate limit.
- Credenciales por variable de entorno, jamas en codigo.
- Ante fallo del servicio, devuelve un mensaje util: el agente puede recurrir a otra fuente si sabe que esta fallo.