Cómo implementar herramientas, quién las ejecuta, cómo fallan y cuántas dar

Un desarrollador escribe una rama del dispatcher para la búsqueda web y nunca recibe una llamada. Otro equipo tiene un agente con 38 herramientas que elige mal entre tres búsquedas parecidas y una vez borró una cuenta. Un tercero le devuelve al modelo un stack trace de 120 líneas. Las tres situaciones salen de no tener claro cómo funciona el uso de herramientas (tool use (function calling)).

Quién ejecuta cada herramienta

Tipo	Quién la ejecuta	Qué hace tu código
Herramientas del cliente (client tools): las tuyas y las de esquema de Anthropic, como bash o el editor de texto	Tu aplicación	Recibe stop_reason: tool_use, ejecuta cada bloque tool_use y devuelve un tool_result con su tool_use_id
Herramientas del servidor (server tools): búsqueda web, web fetch, ejecución de código	Anthropic, en su infraestructura	Nada: el resultado llega en la misma respuesta

De ahí salen dos reglas del examen:

• No hay que escribir un manejador para una herramienta del servidor: nunca te va a llegar un tool_use para ejecutar.
• Una herramienta del servidor no entra a tu red privada. Para consultar un servicio interno detrás de una VPN, definís una herramienta propia que ejecute tu código dentro de la red (o lo exponés con un servidor MCP).

Descripciones que eligen bien

Claude decide qué herramienta usar por su nombre y su descripción de la herramienta (tool description). Una buena descripción dice qué hace, cuándo usarla y cuándo no, qué significa cada parámetro y qué devuelve. Si dos herramientas se parecen, o se unifican o cada descripción aclara en qué caso va. Para que los parámetros respeten siempre el esquema, está el modo estricto (strict: true).

Errores que ayudan a recuperarse

Cuando la herramienta falla, el error vuelve como tool_result con resultado con error (is_error) en true y un mensaje corto que diga qué falló y qué conviene hacer: “número de unidad inexistente; pedile al usuario el número de 6 dígitos” o “servicio no disponible; reintentá en un minuto”. Un stack trace crudo gasta contexto y no le dice al modelo nada útil; un resultado vacío lo hace creer que no había datos.

Aprobaciones en el harness, no en el prompt

Si una acción necesita aprobación humana, el patrón de aprobación (approval pattern) va en el código que ejecuta la herramienta: el harness intercepta refund_order, deja pasar los montos chicos y deja los grandes pendientes hasta que un supervisor apruebe. Una regla en el system prompt (“pedí aprobación arriba de cierto monto”) falla en algún porcentaje de casos.

Un set de herramientas sano

• Solo lo que el rol necesita: un agente de mesa de ayuda no lleva herramientas de borrar cuentas ni de nómina.
• Sin herramientas que se pisen entre sí.
• Credenciales y conexiones a sistemas externos del lado de tu código, nunca en el prompt.

Las trampas típicas

• Escribir un manejador para la búsqueda web o esperar que una herramienta del servidor llegue a una API interna.
• Devolver excepciones crudas o resultados vacíos en lugar de is_error con un mensaje claro.
• Poner la aprobación como regla del prompt.
• Sumar herramientas “por si acaso”, incluidas las de administración.
• Arreglar una mala elección de herramienta cambiando de modelo en lugar de mejorar las descripciones.

En el examen

Primero ubicá quién ejecuta la herramienta del escenario: eso descarta varias opciones. Si el modelo elige mal, buscá descripciones más claras o menos herramientas. Si falla y no se recupera, buscá is_error con un mensaje instructivo. Y si hay una política de montos o de aprobación, buscá el harness.