Sistema de herramientas

Cómo funcionan las herramientas

Cuando Claude Code recibe una instrucción, no se limita a generar texto: ejecuta acciones sobre el sistema de archivos, la terminal y la web mediante un conjunto de herramientas integradas. Cada herramienta es una operación atómica que el agente puede invocar durante su ciclo de razonamiento. Claude decide qué herramienta usar, prepara los parámetros y, si la configuración de permisos lo requiere, solicita aprobación antes de ejecutarla.

El flujo de trabajo sigue un patrón constante: Claude analiza la instrucción, selecciona una o varias herramientas, las ejecuta y utiliza sus resultados para decidir el siguiente paso. Una sola instrucción como "refactoriza el módulo de autenticación" puede desencadenar decenas de llamadas a herramientas: lecturas de archivos, búsquedas de patrones, ediciones y ejecución de tests.

Las herramientas son el mecanismo que transforma a Claude Code de un modelo conversacional a un agente de desarrollo. Sin ellas, Claude solo podría generar texto. Con ellas, puede leer, escribir, buscar, ejecutar comandos y navegar la web.

Las herramientas se organizan en cuatro categorías según el tipo de operación que realizan:

flowchart LR
    A["Instrucción del usuario"] --> B["Claude Code"]
    B --> C["Archivos<br>Read, Write, Edit, MultiEdit"]
    B --> D["Búsqueda<br>Glob, Grep, LS"]
    B --> E["Terminal<br>Bash"]
    B --> F["Web<br>WebSearch, WebFetch"]
    B --> G["Gestión<br>Agent, TodoWrite, Notebook"]

Cada herramienta tiene un nivel de permisos asociado. Las herramientas de solo lectura (Read, Grep, Glob, LS) se ejecutan sin solicitar aprobación. Las herramientas que modifican archivos (Edit, Write, MultiEdit) requieren confirmación hasta el final de la sesión. Los comandos Bash piden aprobación de forma permanente por proyecto y comando.

Herramientas de lectura y escritura de archivos

Read

La herramienta Read lee el contenido de un archivo y lo incorpora a la ventana de contexto. Soporta archivos de texto, imágenes (JPEG, PNG, GIF, WebP), PDFs y notebooks de Jupyter. Es la herramienta más utilizada: Claude la invoca constantemente para entender el código antes de modificarlo.

Read acepta parámetros opcionales de offset y limit para leer secciones concretas de archivos grandes, evitando cargar cientos de líneas innecesarias en el contexto. Las líneas se numeran a partir de 1, lo que facilita las referencias posteriores.

Read("src/auth/login.ts")
Read("src/auth/login.ts", offset=10, limit=30)

En el primer caso, Claude lee el archivo completo. En el segundo, solo las líneas 10 a 39, lo que resulta útil cuando el agente ya sabe en qué zona del archivo necesita trabajar.

Write

Write crea un archivo nuevo o sobrescribe uno existente con el contenido proporcionado. Claude la utiliza para generar archivos desde cero: configuraciones, tests, componentes o cualquier artefacto que no exista previamente.

Write("src/utils/validators.ts", contenido)

Write sobrescribe el contenido completo del archivo. Cuando Claude necesita modificar solo una parte de un archivo existente, utiliza Edit o MultiEdit en su lugar.

Edit

Edit realiza un reemplazo exacto de texto dentro de un archivo existente. Claude proporciona la cadena original (old_string) y la cadena de reemplazo (new_string). La operación falla si old_string no se encuentra o no es única en el archivo, lo que actúa como mecanismo de seguridad frente a ediciones ambiguas.

Edit("src/auth/login.ts", old_string="...", new_string="...")

El reemplazo exacto obliga a Claude a incluir suficiente contexto circundante para identificar de forma unívoca la sección que quiere modificar. Esto evita errores como reemplazar la instancia equivocada de un patrón repetido.

MultiEdit

MultiEdit permite aplicar varios reemplazos en un mismo archivo en una sola operación. Cada reemplazo funciona igual que Edit, con su par old_string/new_string. Es más eficiente que invocar Edit varias veces cuando los cambios afectan a distintas zonas del mismo archivo.

MultiEdit("src/auth/login.ts", edits=[
  { old_string="...", new_string="..." },
  { old_string="...", new_string="..." }
])

Claude utiliza MultiEdit en refactorizaciones donde un cambio implica actualizar varias secciones de un archivo: renombrar una variable, actualizar imports y modificar el cuerpo de una función en una sola llamada.

Herramientas de búsqueda

Glob

Glob busca archivos por patrón de nombre en el sistema de archivos. Devuelve rutas de archivos que coinciden con el patrón, ordenadas por fecha de modificación. Los patrones que no empiezan con **/ se completan automáticamente para buscar de forma recursiva.

Algunos ejemplos de patrones habituales:

| Patrón | Resultado | |---|---| | *.ts | Todos los archivos TypeScript (recursivo) | | src/**/*.test.ts | Tests dentro de src/ | | **/package.json | Todos los package.json del proyecto | | src/components/*.tsx | Componentes en un directorio concreto |

Glob es la herramienta que Claude utiliza para descubrir la estructura del proyecto. Antes de editar un módulo, suele ejecutar un Glob para localizar todos los archivos relevantes.

Grep

Grep busca contenido dentro de archivos utilizando expresiones regulares. Está construida sobre ripgrep (rg), lo que la hace rápida incluso en proyectos grandes. Soporta filtrado por tipo de archivo, patrones glob y distintos modos de salida.

Grep(pattern="function authenticate", type="ts")
Grep(pattern="TODO|FIXME", glob="*.py")
Grep(pattern="class UserService", output_mode="files_with_matches")

Los modos de salida disponibles son:

• content (por defecto): muestra las líneas que coinciden con el patrón.
• files_with_matches: devuelve solo las rutas de los archivos que contienen coincidencias.
• count: muestra el número de coincidencias por archivo.

Grep acepta también parámetros de contexto (-A, -B, -C) para mostrar líneas antes y después de cada coincidencia, lo que ayuda a Claude a entender el código circundante sin necesidad de leer archivos completos.

Grep es la herramienta preferida cuando Claude sabe qué buscar (un nombre de función, una cadena, un patrón). Glob es la herramienta preferida cuando Claude sabe qué tipo de archivo buscar pero no su ubicación exacta.

LS

LS lista el contenido de un directorio. Muestra los archivos y subdirectorios con información básica. Es útil para explorar la organización del proyecto de forma rápida.

LS("src/")
LS("src/components/")

Herramientas de ejecución

Bash

Bash ejecuta comandos de terminal en una sesión persistente. El directorio de trabajo y las variables de entorno se mantienen entre llamadas, lo que permite encadenar operaciones como haría un desarrollador en su terminal.

Bash("npm run build")
Bash("git status")
Bash("python -m pytest tests/")

La persistencia de la sesión significa que si Claude ejecuta cd src/ en una llamada, la siguiente llamada a Bash ya estará en el directorio src/. Del mismo modo, las variables de entorno definidas en una llamada están disponibles en las siguientes.

Bash es la herramienta que requiere mayor precaución en permisos. Puede ejecutar cualquier comando disponible en el sistema, desde compiladores y gestores de paquetes hasta comandos destructivos como rm -rf. Por eso, Claude solicita aprobación antes de ejecutar cada comando nuevo, y la aprobación se almacena de forma permanente por proyecto y comando.

Bash es la herramienta más versátil de Claude Code y la que mayor riesgo conlleva. Un comando aprobado permanece aprobado para el proyecto, por lo que conviene revisar cada aprobación con atención.

Herramientas web

WebSearch

WebSearch realiza búsquedas en la web y devuelve un resumen de los resultados junto con URLs relevantes. Claude la utiliza cuando necesita información actualizada que puede no estar en sus datos de entrenamiento: documentación de una librería reciente, estado de una issue en GitHub o la última versión de un framework.

WebSearch("Flask 3.1 async support")
WebSearch("PostgreSQL 17 new features")

WebFetch

WebFetch recupera el contenido de una URL específica y lo convierte a formato markdown legible. Es útil para consultar documentación oficial, leer páginas de referencia o extraer información de URLs concretas.

WebFetch("https://docs.python.org/3/library/asyncio.html")

WebFetch tiene algunas restricciones: no soporta autenticación, no funciona con URLs que requieran credenciales ni con hosts locales (localhost, IPs privadas), y no descarga contenido binario como imágenes o PDFs directamente.

Herramientas de gestión

Agent

La herramienta Agent lanza subagentes especializados que trabajan en contextos independientes. Cada subagente tiene su propia ventana de contexto, lo que permite abordar tareas complejas sin saturar el contexto de la conversación principal.

Agent(prompt="Busca todos los endpoints REST y documenta sus parámetros",
      subagent_type="explore")

Los tipos de subagente disponibles incluyen:

• explore: búsqueda rápida en el codebase. Ideal para localizar archivos, patrones y responder preguntas sobre la estructura del proyecto.
• generalPurpose: tareas complejas con acceso completo a todas las herramientas.
• shell: especializado en operaciones de terminal y Git.

Agent permite lanzar varios subagentes en paralelo, lo que resulta especialmente eficiente cuando las tareas son independientes entre sí. Por ejemplo, Claude puede buscar la estructura de la API en un subagente mientras otro analiza los tests existentes.

TodoWrite

TodoWrite gestiona una lista de tareas estructurada dentro de la sesión. Claude la utiliza para organizar trabajos complejos con múltiples pasos, marcar el progreso y asegurar que no se olvida ninguna subtarea.

Cada tarea tiene un estado (pendiente, en progreso, completada o cancelada) y la lista persiste entre compactaciones de contexto, lo que permite mantener el seguimiento en sesiones largas.

NotebookRead y NotebookEdit

Estas herramientas permiten leer y editar celdas de notebooks de Jupyter (archivos .ipynb). NotebookRead carga el contenido del notebook con el índice de cada celda. NotebookEdit permite crear celdas nuevas o modificar el contenido de celdas existentes mediante reemplazo de texto.

Herramientas MCP

Además de las herramientas integradas, Claude Code puede acceder a herramientas proporcionadas por servidores MCP (Model Context Protocol). Estas herramientas externas amplían las capacidades del agente con integraciones como bases de datos, APIs de terceros o servicios internos.

Las herramientas MCP aparecen con el prefijo mcp__ seguido del nombre del servidor y de la herramienta. Por ejemplo, mcp__github__create_issue corresponde a la herramienta create_issue del servidor MCP de GitHub.

Para gestionar las conexiones con servidores MCP y sus herramientas, se utiliza el comando /mcp dentro de una sesión interactiva o la configuración en settings.json.

Las herramientas MCP no sustituyen a las integradas: las complementan. Claude Code mantiene su catálogo completo de herramientas y añade las que proporcionan los servidores MCP conectados.

Tabla resumen de herramientas

| Herramienta | Categoría | Descripción | Permiso | |---|---|---|---| | Read | Archivos | Lee archivos de texto, imagen, PDF y notebooks | Sin aprobación | | Write | Archivos | Crea o sobrescribe archivos | Aprobación por sesión | | Edit | Archivos | Reemplazo exacto de texto en un archivo | Aprobación por sesión | | MultiEdit | Archivos | Múltiples reemplazos en un archivo | Aprobación por sesión | | Glob | Búsqueda | Busca archivos por patrón de nombre | Sin aprobación | | Grep | Búsqueda | Busca contenido en archivos con regex | Sin aprobación | | LS | Búsqueda | Lista el contenido de un directorio | Sin aprobación | | Bash | Ejecución | Ejecuta comandos de terminal | Aprobación permanente | | WebSearch | Web | Búsqueda en la web | Sin aprobación | | WebFetch | Web | Recupera contenido de una URL | Sin aprobación | | Agent | Gestión | Lanza subagentes especializados | Sin aprobación | | TodoWrite | Gestión | Gestiona lista de tareas de la sesión | Sin aprobación | | NotebookRead | Gestión | Lee celdas de notebooks Jupyter | Sin aprobación | | NotebookEdit | Gestión | Edita celdas de notebooks Jupyter | Aprobación por sesión |