Tool Use Design

Capacidad

Diseñar cada tool como un contrato de routing y datos: nombre, descripción, input_schema, ejemplos válidos, opciones comunes, selección y frontera recíproca. Para Claude Platform también gobierna strict:true, tool_choice, allowed_callers, defer_loading, caching, privacidad de esquemas y versiones descritas por la referencia oficial. [DOC]

Frontera: este skill define el catálogo, no ejecuta tools. El bucle tool_use/tool_result pertenece a claude-api-tool-runtime; server tools a claude-api-server-tools; handlers Anthropic de memory/bash/editor/computer a claude-api-client-tools; contexto/cache a claude-api-context-management; extensiones de Claude Code a custom-tooling-extension. La selección y secuencia de built-ins para operar repositorios pertenece a katas-builtin-tool-selection. [CONFIG]

Cuándo usarla

• Estás definiendo o refactorizando el tool surface de un agente y dos tools se solapan en propósito (overloading).
• El agente elige el tool equivocado o pide aclaración cuando la decisión debería ser inmediata.
• Una descripción genérica del tipo "Analyzes content" no permite al modelo saber qué entrada espera ni dónde está su frontera.
• Necesitas definir name, description, input_schema o input_examples, activar strict:true, revisar tool_choice, o comparar versiones/opciones de la referencia de Claude Platform. [DOC]
• Claude selecciona la tool equivocada, inventa propiedades o valores, o necesita ejemplos válidos para una entrada compleja. [DOC]

Cómo construir

1. Inventaria el tool surface y detecta solapamientos: dos tools que un humano podría confundir son dos tools que el modelo confundirá.
2. Escribe cada descripción como contrato: propósito en una frase, input format explícito, 1–2 ejemplos de invocación y la frontera ("usa X para A; para B usa Y").
3. Resuelve el overloading con rename + split, no con prosa: un tool sobrecargado se divide en dos con nombres y fronteras recíprocas, en lugar de explicar matices en un párrafo. Si el solapamiento es parcial y legítimo (no resoluble por split limpio), prefiere una frontera explícita antes que fragmentar: el over-splitting infla el catálogo y degrada el routing tanto como el overloading.
4. Valida con el checklist antes de cerrar: fronteras recíprocas, decisión de tool inmediata y ejemplos compatibles con el esquema.
5. Para Claude Platform, aplica references/claude-platform-tool-definition-contract.md: valida nombre/campos, restricciones de ejemplos, los cuatro modos de tool_choice, pensamiento extendido, invalidación de caché, privacidad del esquema estricto, allowed_callers, defer_loading y versionado antes de emitir código. [DOC]

Patrón correcto

# GOOD — descripciones como contrato con frontera recíproca + estrategia Grep→Read→Edit
TOOLS = [
    {
        "name": "search_code",
        "description": (
            "Find files or symbols by pattern across the repo. "
            "Input: a regex or literal string. Returns matching paths + line numbers. "
            "Use this FIRST to locate. To read a known file's contents, use read_file instead."
        ),
    },
    {
        "name": "read_file",
        "description": (
            "Read the full contents of ONE known file path. "
            "Input: an absolute path. Use after search_code has located the file. "
            "Do NOT use to discover files — that is search_code's job."
        ),
    },
    {
        "name": "edit_file",
        "description": (
            "Replace an exact, UNIQUE anchor string in a file. "
            "Input: path, old_string (must be unique), new_string. "
            "FAILS if old_string is not unique. Fallback: read_file then write_file for a full rewrite."
        ),
    },
]

# Workflow the descriptions enforce: locate cheaply, read selectively, mutate precisely.
hits = search_code(pattern="def handle_payment")   # Grep
src = read_file(path=hits[0].path)                  # Read only the relevant file
edit_file(path=hits[0].path, old_string=unique_anchor, new_string=patched)  # Edit

Anti-patrón

# ANTI — descripciones genéricas + read masivo upfront
TOOLS = [
    {"name": "analyze", "description": "Analyzes content."},        # no input, no frontera
    {"name": "process", "description": "Processes the file."},      # solapa con analyze
]

# El agente, sin frontera, no sabe cuál elegir → pide aclaración o adivina.
# Y para "entender el repo" carga todo en contexto:
all_files = glob("**/*")
context = "".join(read_file(p) for p in all_files)  # ~200k tokens, satura la ventana
# Edit sin fallback documentado: si el anchor no es único, falla con error.

Checklist de validación

• ¿Cada descripción declara input format + 1–2 ejemplos + frontera recíproca con su vecina?
• ¿El overloading se resolvió con rename + split, no con un párrafo explicativo?
• ¿El modelo puede elegir el tool correcto por decisión rápida, sin pedir aclaración?
• ¿Está documentado el failure mode de Edit (anchor no único) y su fallback Read+Write?
• ¿La estrategia es Grep → Read → Edit, sin ningún Glob("**/*") + Read all upfront?
• ¿input_examples valida contra input_schema, strict:true se usa con restricciones verificadas y tool_choice es compatible con el modo/modelo activo? [DOC]
• ¿Se aplicaron el regex del nombre, la disponibilidad de campos opcionales y las restricciones de input_examples por tipo de tool? [DOC]
• ¿Se revisaron los cuatro modos de tool_choice, pensamiento extendido, invalidación de caché y la caché de esquema estricto de hasta 24 horas sin PHI? [DOC]
• ¿Los síntomas de selección errónea o parámetros inventados se corrigieron en descripción/esquema/ejemplos, dejando parsing y correlación al runtime? [DOC][CONFIG]

Katas y skills relacionadas

• Katas: katas-tool-description-quality, katas-builtin-tool-selection.
• Skills relacionadas: mcp-engineering, claude-api-tool-runtime, claude-api-server-tools, claude-api-client-tools.

Resources

• references/claude-platform-tool-definition-contract.md - definición completa, selección, caché/privacidad estricta, catálogo/versiones y troubleshooting. [DOC]

Contract

• Aceptación: cada tool tiene nombre/descripción que dice CUÁNDO usarla y contrato de error tipado. [EXPLICIT]
• Límites: diseña definiciones y selección; no ejecuta el loop, el servidor, el handler cliente ni una extensión de Claude Code. [EXPLICIT]
• Casos borde: descripción ambigua → el modelo no la selecciona o la usa mal. [EXPLICIT]
• Supuestos: Grep→Read→Edit como estrategia builtin por defecto. [SUPUESTO]
• Trade-off: descripciones ricas mejoran selección pero cuestan tokens de catálogo. [EXPLICIT]

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): references/ guías de profundidad (cargar UNA por etapa) · knowledge/ cuerpo de conocimiento · prompts/ prompts listos · examples/ salida de ejemplo · agents/ subagentes del packet · templates/ plantilla de output.