Tool Design: El Cinturón de Batman y el Arte de Diseñar Herramientas que Claude Puede Usar

Los 4 componentes de una herramienta bien diseñada, cómo Claude decide cuál usar, qué es el tool overload, y el principio de single responsibility aplicado al diseño de tools.

Cerraste el Módulo 1 dominando la arquitectura agéntica: el loop, los patrones de coordinación, las herramientas desde el lado del agente, stopping criteria, estado multi-turno, comunicación entre agentes, y seguridad adversarial. Eso era el 27% del examen.

Ahora arranca el siguiente Módulo: Tool Design y MCP. El 18% del CCA-F. Y si en el módulo anterior aprendiste a usar herramientas como consumidor, acá aprendés a diseñarlas como creador.

Batman no lleva un gadget universal con un botón que dice 'resolver problema'. Tiene un batarang para desarmar, un gancho para escalar, un kit forense para analizar evidencia, y un comunicador con Alfred para acceso remoto. Cada gadget: un nombre claro, una función específica, parámetros definidos.

Ese es exactamente el estándar de tool design que el examen te va a pedir. Cada herramienta hace una sola cosa, tiene una descripción precisa, y el agente — Claude — sabe exactamente cuándo usarla y con qué argumentos.

Anatomía de una herramienta: los 4 componentes

Una herramienta en el SDK de Anthropic tiene cuatro componentes. El examen pregunta sobre cada uno, y hay uno que la mayoría subestima.

El componente que más importa: la description

Escuchá esto bien porque el examen lo pregunta: Claude NUNCA ve el código de tu herramienta. No sabe cómo está implementada. Solo lee la description para decidir si usarla, cuándo usarla, y cómo construir los argumentos.

Si la description es mala, el model use va a ser malo — sin importar qué tan buena sea la implementación. Podés tener la lógica más sofisticada detrás de la herramienta, pero si la description dice 'Busca información' sin más contexto, el modelo no sabe cuándo preferirla sobre otra.

Una description bien escrita tiene tres partes: qué hace la herramienta, cuándo usarla, y qué no hacer (limitaciones o cuándo preferir otra herramienta). Esas tres partes le dan a Claude el contexto que necesita para tomar la decisión correcta.

💡 EXAMEN: 'La description es el componente más crítico de una herramienta porque es la única información que el modelo tiene para decidir si y cómo usarla.' Esa frase va a aparecer, reformulada, en el examen.

Tool overload: el error más común en D2

Batman no lleva el cinturón de utilidades completo en cada misión. Si va a interrogar a un informante en un café, no necesita las cargas explosivas ni el traje de buceo. Arma el cinturón según lo que esa misión específica requiere.

El error de tool overload es darle al agente más herramientas de las que necesita para la tarea. El modelo tiene que leer y evaluar TODAS las herramientas en cada paso del loop. Más herramientas = más tokens = más costo y más latencia.

Tool overload no es solo un problema de rendimiento. Con demasiadas herramientas similares, Claude puede elegir la equivocada. Y cuando algo sale mal en un set de cincuenta herramientas, encontrar el error es significativamente más difícil.

Tres consecuencias concretas. Primera: el modelo tarda más en decidir — más herramientas para evaluar en cada iteración significa más tokens de razonamiento, más latencia, más costo. Segunda: con herramientas similares, Claude elige la equivocada con más frecuencia. Si tenés cinco variantes de 'buscar', el modelo puede confundirlas. Tercera: los errores son más difíciles de debuggear.

La solución es el principio de menor privilegio aplicado a herramientas. Cada agente recibe solo las herramientas que necesita para su rol. El orchestrator tiene unas herramientas. El sub-agente de análisis forense tiene otras. El sub-agente de investigación de campo tiene otras distintas. Nadie tiene todo.

💡 EXAMEN: El principio de menor privilegio (least privilege) aparece tanto en D2 (tool design) como en D1 (seguridad agéntica). Para herramientas, se aplica a nivel de agente: cada agente recibe solo las tools necesarias para SU tarea específica.

 Single responsibility: una herramienta, una función

El batarang no tiene modo gancho. El gancho no tiene modo batarang. Cada gadget del cinturón hace una sola cosa — y eso es exactamente lo que los hace tan efectivos. Batman sabe cuándo usar cada uno sin pensarlo dos veces.

¿Por qué importa esto para Claude? Tres razones concretas. Primera: la description es más fácil de escribir — si la herramienta hace una sola cosa, podés describirla en dos oraciones. Si hace cinco cosas, la description se vuelve confusa y el modelo elige mal. Segunda: el debugging es más simple — si algo salió mal, sabés exactamente qué herramienta falló y en qué paso. Tercera: las herramientas son reutilizables — 'analizar_huella_dactilar' funciona en cualquier caso, no solo en el que la diseñaste.

Si una herramienta hace A, B y C, en realidad son tres herramientas que todavía no separaste. La señal: si tu description usa 'y' o 'también' para describir las funciones principales, es momento de dividir.

Diseño bueno

Fijate en tres mejoras clave. El nombre 'buscar_sospechoso_gcpd' especifica exactamente dónde y para qué. El campo tipo_evidencia es un enum — Claude no puede inventar un tipo que no existe. Y generar_reporte_caso tiene una instrucción explícita de cuándo NO usar: en medio de la investigación. Eso evita que Claude salte al reporte antes de recolectar la evidencia.

Demo: el Detective Batman en acción

Con las herramientas bien diseñadas, el agente sigue el orden correcto sin que vos lo hardcodees en la lógica de ejecución. La description sola guía el razonamiento.

Corrés esto y vas a ver el orden: primero busca al sospechoso por el alias, después analiza la huella forense, y SOLO AL FINAL genera el reporte. El agente no se saltó pasos ni invirtió el orden — porque la description de generar_reporte_caso decía explícitamente 'usar solo al final'. Eso es lo que hace una buena description: guía el razonamiento sin que vos lo hardcodees.

Las 4 trampas del examen sobre tool design

Trampa 1: 'Una description más larga siempre es mejor'

FALSO. Una description muy larga con información redundante es tan mala como una demasiado corta. El objetivo es precisión, no extensión. Una description ideal tiene tres partes concretas: qué hace, cuándo usarla, cuándo no. Si necesitás cinco párrafos, probablemente la herramienta hace demasiado.

Trampa 2: 'El input_schema solo sirve para validación de tipos'

INCOMPLETO. El schema hace dos cosas. Sí valida tipos en tiempo de ejecución. Pero más importante: le dice a Claude qué argumentos construir y con qué restricciones. Los enums son especialmente poderosos — reducen dramáticamente los errores de argumentos inválidos porque el modelo solo puede elegir entre las opciones definidas.

Trampa 3: 'El return value no forma parte del diseño de la herramienta'

FALSO para el examen. El return value es parte del contrato de la herramienta. Si Claude no sabe qué esperar del resultado, no puede usarlo para decidir el siguiente paso correctamente. El return value tiene que estar documentado en la description: qué formato tiene, qué indica éxito, qué indica error.

Trampa 4: 'Más herramientas disponibles siempre dan más capacidades al agente'

FALSO. Más herramientas = más contexto que Claude debe procesar = más tokens de razonamiento = más costo y latencia. Peor aún, con herramientas similares el modelo puede elegir la equivocada. La capacidad del agente no es proporcional al número de herramientas — es proporcional a la calidad del diseño de cada una y a que cada agente reciba solo las que necesita.

Lo que te llevás de este módulo

Tool design es el arte de diseñar el cinturón de Batman correcto para tu agente. Los cuatro componentes de toda herramienta son name, description, input_schema y return value. La description es el más crítico porque es la única información que Claude tiene para decidir si y cómo usar la herramienta. El tool overload genera confusion, costo y errores — la solución es least privilege por agente. Y single responsibility: si tu herramienta hace dos cosas, dividila.

La diferencia entre un agente que funciona bien y uno que falla consistentemente casi siempre está en el tool design — no en el modelo, no en el sistema prompt general. Cuando un agente usa la herramienta equivocada o pasa argumentos inválidos, la primera pregunta es: ¿cómo está escrita la description?

En el siguiente capítulo vamos a ver MCP — el Model Context Protocol. Qué es, por qué existe como estándar, y cómo se diferencia de las herramientas directas en la API. Spoiler: MCP es lo que te permite compartir herramientas entre múltiples agentes sin duplicar código.Código del video