Uso de herramientas en AI Agent: MCP, CLI, Skills y ejecución de código

Viacheslav Dubrov

2026-03-24 · Actualizado 2026-09-06 · 27 min · Agentes de IA

Traducción automática Este artículo se tradujo automáticamente a partir de la versión original en inglés.

Actualización del artículo

Publicado originalmente el 24 de marzo de 2026. Revisado y actualizado el 6 de septiembre de 2026. La actualización cubre la especificación revisada de MCP, el programmatic tool calling y las nuevas evidencias sobre los costes y las limitaciones del tool use.

Un agent necesita una forma de actuar: un JSON tool call, un servicio MCP, un comando CLI o código en un sandbox. También puede necesitar instrucciones para elegir y utilizar ese mecanismo. Skills proporciona esas instrucciones. El harness es el programa convencional que rodea al modelo: construye prompts, comprueba una llamada propuesta, ejecuta una llamada aprobada y decide cuándo ha terminado la tarea.

Este tercer artículo de la serie añade la capa de acción a los reasoning loops de la Parte 1 y a la memoria de la Parte 2. La Parte 4 examina la comprobación de policy previa a la ejecución, y la Parte 6 analiza el harness que ejecuta tanto la llamada como esa comprobación.

La situación de las herramientas cambió en 2025–2026. MCP, el Model Context Protocol, proporcionó a los vendors una forma compartida de exponer servicios externos. Los agents con ejecución de código demostraron que, en ocasiones, un modelo puede componer un programa pequeño de forma más eficiente que emitir una larga secuencia de llamadas JSON. Anthropic comunicó una reducción del 98,7 % en tokens para un workflow de Google Drive a Salesforce, y el artículo de CodeAct comunicó mejoras de hasta 20 puntos porcentuales en task success en su configuración de benchmark. Esos resultados describen sus tareas y harnesses, no una ventaja universal de la ejecución de código.

Comparo JSON tool calling, herramientas MCP, herramientas CLI y ejecución de código, y después muestro dónde encajan las Skills. Una sección posterior aplica los principios de diseño de Agent-Computer Interface (ACI) al Market Analyst Agent, un pequeño agent de investigación basado en LangGraph que construí para la Parte 1 y que obtiene datos de mercado y redacta un informe de analista.

Para una decisión breve sobre interfaces, consulta AI Agent Tool Interfaces.

Superficies de ejecución y guía procedimental

El reasoning loop propone una llamada. El harness comprueba sus argumentos y si la llamada está permitida; después la envía a una herramienta o sandbox y devuelve el resultado. Los JSON schemas, el transporte MCP, los wrappers CLI y los code runners pueden restringir las entradas, pero ninguno decide si la acción solicitada está permitida. Las Skills proporcionan instrucciones para ese recorrido. Estas superficies de ejecución intercambian coste en tokens, flexibilidad y enforcement de formas diferentes.

1. JSON tool calling: el baseline

El patrón original: defines los tool schemas como JSON, el LLM emite function calls estructuradas y tu código las ejecuta. Es un patrón conocido y funciona bien para toolsets pequeños.

# Schema cost depends on its text, structure, and the model tokenizer
tools = [
    {
        "name": "get_stock_price",
        "description": "Get the current stock price for a ticker symbol",
        "input_schema": {
            "type": "object",
            "properties": {
                "ticker": {"type": "string", "description": "Stock ticker (e.g., NVDA)"}
            },
            "required": ["ticker"]
        }
    }
]

Cuenta los tokens de tus schemas reales. El coste depende de su longitud y de cuántos cargue el host; un lookup de precios compacto y un contrato de API profundamente anidado no son unidades equivalentes. El deferred discovery puede evitar cargar el registry completo.

2. MCP para integraciones compartidas

MCP es el estándar en el que han convergido la mayoría de vendors. Un servidor MCP es un proceso que anuncia una lista de herramientas mediante un wire protocol definido: stdio para un proceso local y HTTP para uno remoto. Tu agent ejecuta un cliente MCP que se conecta, pregunta al servidor qué herramientas tiene y reenvía las llamadas del modelo, de modo que el mismo servidor funciona con cualquier cliente que hable el protocolo. Anthropic donó el protocolo a la Linux Foundation en diciembre de 2025, dentro de la Agentic AI Foundation, que cofundó con OpenAI y Block. Google, Microsoft y AWS respaldan la fundación como miembros platinum. OpenAI añadió compatibilidad con MCP en su Responses API. Según el anuncio de la donación de diciembre de 2025 de Anthropic, el ecosistema contaba con más de 10.000 servidores MCP públicos activos y más de 97 millones de descargas mensuales de SDKs entre los SDKs de Python y TypeScript.

MCP encaja en integraciones SaaS entre vendors (Figma, Notion, Salesforce), servicios sin equivalentes CLI y entornos que necesitan orquestación de OAuth. Su valor reside en ofrecer una capa compartida de discovery y transporte. La gobernanza sigue dependiendo de los controles de autenticación, autorización, logging y despliegue del servidor.

La versión del protocolo es ahora una decisión práctica de migración. La revisión del 28/07/2026 cambia comportamientos que asumen muchos tutoriales antiguos:

La misma revisión depreca Roots, Sampling, Logging y OAuth Dynamic Client Registration; la deprecación no implica una eliminación inmediata. El registro de clientes actual favorece Client ID Metadata Documents. Las integraciones existentes pueden seguir utilizando una revisión anterior, así que inspecciona el SDK instalado y el contrato del servidor antes de adoptar una funcionalidad nueva.

La realidad en producción es más compleja de lo que sugieren las cifras principales.

El Vulnerable MCP Project recopila informes relacionados con prompt injection, validación de entradas, autenticación y controles de red. Esta recopilación ayuda a identificar casos de prueba; sin un denominador de exposición no puede establecer una comparación entre MCP y shell o llamadas directas a una API.

Tool poisoning es la clase de ataque que más me preocupa. Invariant Labs demostró que las herramientas MCP envenenadas pueden exfiltrar datos aunque nunca se invoquen. Basta con que el modelo lea los metadatos de la herramienta para activar el ataque. Los benchmarks de MCPTox, que probaron 20 LLM agents contra 45 servidores MCP reales, comunicaron un 72,8 % de attack success medio para o1-mini en su configuración de tool poisoning. Es el resultado del benchmark de un modelo, no la media de los 20 agents ni una tasa de incidentes reales.

El token overhead es el problema operativo. Un equipo que ejecutaba servidores MCP para GitHub, Slack y Sentry (unas 40 herramientas en total) encontró 55.000 tokens de definiciones de schemas inyectados antes de que el usuario preguntara nada. Otro equipo comunicó que las definiciones de herramientas por sí solas consumían 143.000 de los 200.000 tokens disponibles (72 %).

El informe Tool Search Tool de Anthropic comunicó unos extremos de contexto de aproximadamente 77.000 tokens antes de empezar el trabajo y 8.700 después del deferred discovery, con unos 72.000 tokens de definiciones de herramientas en la configuración tradicional. Solo carga las tres a cinco herramientas que necesita una solicitud, pero añade un paso de discovery antes de la invocación; resulta menos útil para toolsets pequeños y compactos cuyas herramientas se utilizan con frecuencia en todas las sesiones.

3. Las Skills empaquetan expertise, no ejecución

Las agent skills son un formato abierto para empaquetar instrucciones y archivos auxiliares. Las herramientas proporcionan capacidades (lo que pueden hacer los agents), mientras que las skills proporcionan expertise (lo que los agents saben sobre cómo realizar tareas complejas).

El formato SKILL.md define una skill como un archivo markdown con YAML frontmatter. El estándar abierto solo exige name y description; el ejemplo siguiente también utiliza dos extensiones de Claude Code, argument-hint y user-invocable, además de su placeholder posicional de argumentos $0:

---
name: deploy
description: Deploy the application to production
argument-hint: "[environment]"
user-invocable: true
---
Deploy the application to the $0 environment (default: staging).
Steps:
1. Run the test suite
2. Build the production bundle
3. Deploy using the deploy script
4. Verify the deployment health check

Las Skills utilizan progressive disclosure. Al arrancar, el agent recibe unos 100 tokens de name y description. Carga el SKILL.md completo solo cuando necesita la skill y, después, carga los scripts, documentos o assets referenciados según sea necesario. Ese coste inicial es mucho menor que los aproximadamente 55.000 tokens que pueden consumir unas 40 herramientas MCP antes de que empiece el razonamiento. Una skill activa sigue añadiendo sus instrucciones y recursos al contexto.

Usa Skills para conocimiento de dominio, procedimientos de varios pasos y trabajo recurrente, como migraciones de bases de datos o integraciones de pagos. Encajan en tareas en las que el agent necesita instrucciones sobre cómo utilizar una capacidad existente.

4. Herramientas CLI y shell

Las interfaces CLI pueden ser mucho más baratas en contexto cuando el modelo ya conoce el comando. Scalekit comunicó una diferencia de 4 a 32 veces en tokens entre sus recorridos CLI y MCP en 75 ejecuciones. Ese case study mide sus herramientas y tareas; no sustituye una comparación con tus propias definiciones de herramientas y salidas de comandos.

Los comandos ampliamente documentados, como git, docker, kubectl, gh, curl y jq, suelen necesitar poco schema introductorio. Las CLI menos habituales o internas siguen necesitando help descubrible, ejemplos y una salida estable legible por máquinas.

La guía de Ugo Enyioha “Writing CLI Tools That AI Agents Actually Want to Use” codificó ocho reglas de diseño:

1. La structured output es obligatoria — admite --json
2. Los exit codes son control flow — usa códigos distintos para tipos de error diferentes
3. Los comandos deben ser idempotentes
4. Autodocumentación --help con ejemplos realistas
5. Diseña para la composabilidad — --quiet para valores sin formato y compatibilidad con stdin
6. Proporciona flags --dry-run y --yes
7. Admite la introspección de versiones
8. Gestiona la autenticación mediante variables de entorno

CLI no dispone de discovery a nivel de protocolo. JSON tool calling puede transportar schemas tipados, mientras que MCP estandariza el discovery de herramientas y, para transportes HTTP, un modelo de autorización. Ninguno proporciona governance por sí mismo: el host, el servidor o el harness debe aplicar la policy y registrar las llamadas que necesite auditar. Un default práctico es usar CLI para desarrollo y operaciones locales, y MCP para integraciones compartidas con servicios externos cuando el discovery entre clientes o la orquestación de OAuth compensen el overhead del servidor.

5. Ejecución de código para trabajo de varios pasos

Este es el cambio en tooling para agents que considero más relevante. En lugar de emitir JSON estructurado para invocar funciones predefinidas una a una, el agent escribe un script de Python o bash. El script llama a varias herramientas, procesa los resultados con loops y conditionals, y devuelve al contexto del modelo solo el resumen final.

Anthropic introdujo Programmatic Tool Calling (PTC) en beta. La guía actual de la API utiliza la Messages API normal con code_execution_20260120 o posterior; el lanzamiento beta original es contexto histórico. La base académica es el artículo de CodeAct (Wang et al., ICML 2024), que probó 17 LLMs y descubrió que las code actions alcanzaban hasta 20 puntos porcentuales más de task success y un 30 % menos de acciones que las alternativas JSON.

Tres case studies de first-party muestran dónde puede ayudar este patrón: Vercel y Cloudflare a continuación, y después el ejemplo de análisis de gastos de Anthropic. Trátalos como evidencia de vendors y repite la comparación con tus propias tareas.

• Vercel reconstruyó d0, su data agent de lenguaje natural a SQL. Su antiguo ejemplo de código nombra 17 herramientas; el nuevo expone ExecuteCommand y ExecuteSQL. Vercel presenta el rediseño como una eliminación del 80 % de sus herramientas, pero esa afirmación es el titular de Vercel, no un porcentaje que se desprenda de las herramientas nombradas en los ejemplos. En cinco consultas representativas, Vercel comunica que el task success pasó de 4/5 a 5/5, que el tiempo medio de ejecución se redujo 3,5 veces (de 274,8 s a 77,4 s) y que el uso medio de tokens bajó un 37 % (de unos 102.000 a unos 61.000). Su formulación es: «Los mejores agents podrían ser los que tienen menos herramientas».

• Cloudflare desarrolló «Code Mode», que permite a los agents escribir TypeScript para llamar a su API en lugar de definir tool schemas, reduciendo así el overhead de contexto. Su razonamiento: «Los LLMs tienen una cantidad enorme de TypeScript del mundo real en sus datasets de entrenamiento, pero solo un pequeño conjunto de ejemplos artificiales de tool calls».

Este es el patrón de la documentación de PTC de Anthropic. En la ilustración secuencial de análisis de gastos de Anthropic, el tool calling tradicional requiere más de 20 pasadas de inferencia independientes, con los datos intermedios fluyendo por el contexto. Después del lookup del equipo, un host que admita parallel tool calls puede agrupar las solicitudes de gastos independientes; la cifra de más de 20 no lo impide. Anthropic comunica que el código generado para responder a la misma pregunta reduce lo que llega al contexto desde 200 KB de filas de gastos sin procesar —más de 2.000 líneas— hasta 1 KB de resultados. El script siguiente ilustra ese control flow mediante adaptadores Python async personalizados: aceptan argumentos posicionales y devuelven listas y diccionarios decodificados. No es el contrato nativo del wrapper de PTC.

# Custom decoded Python adapters, not native Claude PTC wrappers.
import asyncio
import json

async def main() -> None:
    team = await get_team_members("engineering")
    levels = list(set(member["level"] for member in team))
    budgets = dict(zip(
        levels,
        await asyncio.gather(*(get_budget_by_level(level) for level in levels)),
    ))
    expenses = await asyncio.gather(
        *(get_expenses(member["id"], "Q3") for member in team)
    )
    over_budget = []
    for member, employee_expenses in zip(team, expenses):
        total = sum(expense["amount"] for expense in employee_expenses)
        limit = budgets[member["level"]]["travel_limit"]
        if total > limit:
            over_budget.append(
                {"name": member["name"], "spent": total, "limit": limit}
            )
    # Only this final summary returns to the LLM context
    print(json.dumps(over_budget))

asyncio.run(main())

Para utilizar los wrappers nativos de Claude PTC, pasa a cada herramienta un diccionario de argumentos, decodifica su string JSON devuelto y usa await en el entorno de ejecución gestionado en lugar de iniciar un event loop con asyncio.run. El ejemplo de adaptadores personalizados anterior asume un runtime de script Python normal; tampoco es un ejemplo de conector MCP nativo listo para usar. Las restricciones actuales de la API de PTC excluyen las herramientas strict: true y las herramientas de conectores MCP nativos del calling programático, y restringen los schemas recursivos. Un puente personalizado de código a MCP es una integración separada. allowed_callers guía cómo Claude llama a una herramienta; no es un límite de autorización. El host debe validar cada invocación devuelta, incluida una llamada directa inesperada.

El LLM solo ve el resumen JSON final, no las miles de líneas de gastos procesadas en el sandbox. El ahorro no es específico de los informes de gastos: el artículo independiente de Anthropic sobre ejecución de código ofrece la cifra más contundente para este patrón: un workflow de Google Drive a Salesforce que pasó de unos 150.000 tokens a unos 2.000, una reducción del 98,7 %.

La guía actual de PTC también comunica un contraejemplo: en las tareas de aerolíneas, retail y telecomunicaciones de tau2-bench, PTC dejó las puntuaciones sin cambios y costó aproximadamente un 8 % más. En un benchmark independiente de gestión de proyectos con 75 herramientas, redujo los input tokens facturados aproximadamente un 38 % sin cambiar la accuracy. Estas evaluaciones internas solo identifican un modelo Claude de producción, no un ID exacto. Los workflows secuenciales pequeños pueden no ahorrar lo suficiente como para compensar el overhead del contenedor y de la generación de código.

La eficiencia en tokens es una posible ventaja. Los loops y conditionals salen gratis, y la ejecución de código puede gestionar errores con handlers explícitos en lugar de obligar al modelo a razonar sobre los fallos en lenguaje natural. Una ruta de ejecución de código puede mantener datos intermedios sensibles fuera del contexto del modelo, pero eso no equivale a confidencialidad: el aislamiento, los controles de egress, las credenciales con scope y el logging necesitan enforcement independiente.

Cuándo sigue teniendo sentido JSON tool calling: operaciones atómicas individuales, entornos sin infraestructura de sandboxing, modelos pequeños con una generación de código débil o requisitos de auditoría que necesiten registrar cada invocación de herramienta por separado.

Comparación de la ejecución de herramientas para AI agents

JSON tool calling, MCP, CLI y la ejecución de código son superficies de ejecución. Las Skills son instrucciones que guían una de esas superficies, por lo que su latencia, contexto y configuración dependen del mecanismo seleccionado. «Meta-tools» significa los pocos entry points genéricos que necesita un agent con ejecución de código —por ejemplo, ExecuteCommand y ExecuteSQL de Vercel— en lugar de un schema para cada operación. Las filas de composabilidad y latencia describen llamadas cuyos argumentos posteriores dependen de resultados anteriores. JSON tool calling y MCP pueden emitir llamadas independientes conjuntamente, pero las llamadas dependientes suelen necesitar otro model turn. PTC mueve ese control flow y filtering dependientes a un script y después devuelve un resumen al modelo. Las celdas de tokens y task success resumen ejemplos citados, no un benchmark controlado único entre las cinco columnas.

La Agent-Computer Interface (ACI) para herramientas de AI agents

El término «Agent-Computer Interface» (ACI) fue acuñado por John Yang, Carlos E. Jimenez y sus colaboradores de Princeton en su artículo sobre SWE-agent (NeurIPS 2024). La calidad de las interfaces humanas cuenta con toda una disciplina dedicada a ella: la interacción persona-ordenador, o HCI. El artículo sostiene que los agents basados en language models merecen el mismo tratamiento: son «una nueva categoría de usuarios finales con sus propias necesidades y capacidades, y se beneficiarían de interfaces creadas específicamente para ellos».

Sus resultados de ablation ponen una cifra a esa afirmación. Utilizando el mismo modelo base GPT-4 Turbo, la ablation de SWE-bench Lite del artículo alcanzó un 18,0 % con la ACI completa de SWE-agent en 300 tareas, frente al 7,3 % de la condición basada solo en shell sin una demostración guiada y al 11,0 % con una. La comparación muestra que las condiciones de interfaz y demostración cambiaron materialmente el rendimiento en esta configuración; no aísla el diseño de interfaz de todas las demás diferencias ni demuestra que el modelo no realizara trabajo. Dentro de la misma ablation de interfaz, habilitar el linting elevó la condición de edición del 15,0 % al 18,0 %; en el conjunto completo de pruebas de SWE-bench, el 51,7 % de las ejecuciones de SWE-agent intentó al menos una edición que el linter rechazó antes de que pudiera propagarse.

Anthropic adoptó ACI como concepto fundamental en su guía “Building Effective Agents”, donde lo incluye como uno de los tres principios esenciales: «Diseña cuidadosamente tu agent-computer interface mediante una documentación y unas pruebas exhaustivas de las herramientas». Su recomendación práctica es: «Una regla general es pensar en cuánto esfuerzo se dedica a las interfaces persona-ordenador y planificar invertir el mismo esfuerzo en crear buenas agent-computer interfaces».

Cuatro principios de ACI en la práctica

1. Las acciones deben ser simples y fáciles de entender. El error más común es envolver los endpoints de una API uno a uno. En lugar de list_users, list_events y create_event, implementa schedule_event, que encuentra la disponibilidad y programa en una sola llamada. En lugar de read_logs, implementa search_logs, que devuelve solo las líneas relevantes con contexto.

2. Las acciones deben ser compactas y eficientes. Consolida las operaciones importantes en el menor número posible de acciones. En el Market Analyst Agent, combino la obtención de precios con métricas básicas en una única herramienta get_stock_snapshot, en lugar de exigir llamadas separadas para el precio, el volumen, la capitalización bursátil y el ratio PE.

3. El feedback del entorno debe ser informativo, pero conciso. Evita devolver HTML sin procesar o payloads completos de una API. Resuelve los IDs crípticos a nombres semánticos. Las pruebas de Anthropic añadieron un enum response_format para que el agent pueda solicitar una respuesta concisa (unos 72 tokens) o detallada (unos 206 tokens), una diferencia aproximada de 3 veces en el coste de tokens.

4. La validación debe mitigar la propagación de errores. La detección automática de errores ayuda a los agents a reconocer y corregir los fallos rápidamente. En SWE-agent, un editor de archivos personalizado con linting integrado rechaza automáticamente los errores de sintaxis: es el paso de validación que está detrás de la cifra del 51,7 % anterior. Esta es la validación de las entradas y salidas de una herramienta, no el filtrado de contenido que rodea una llamada al modelo y que realizan los productos de guardrails de la Parte 4; se utiliza la misma palabra para ambas cosas. Aplico el mismo principio en el Market Analyst Agent validando los argumentos de las herramientas con esquemas Pydantic antes de la ejecución:

from pydantic import BaseModel, Field, field_validator

from market_analyst.utils import normalize_ticker

class StockQuery(BaseModel):
    """Validated input for stock queries.

    Pydantic catches malformed tickers before the API call,
    preventing error propagation through the reasoning loop.
    """
    ticker: str = Field(description="Stock ticker symbol (e.g., NVDA)")

    @field_validator("ticker")
    @classmethod
    def validate_ticker(cls, v: str) -> str:
        return normalize_ticker(v)

class StockHistoryQuery(StockQuery):
    """Validated input for price history queries."""

    period: str = Field(default="1mo", description="Time period: 1d, 5d, 1mo, 3mo, 6mo, 1y")

    @field_validator("period")
    @classmethod
    def validate_period(cls, v: str) -> str:
        valid = {"1d", "5d", "1mo", "3mo", "6mo", "1y"}
        if v not in valid:
            raise ValueError(f"Invalid period: {v}. Must be one of {valid}")
        return v

El normalizer compartido elimina espacios y convierte a mayúsculas el valor; después acepta dígitos de ticker y sufijos con puntos o guiones, como BRK.B y BF-B; StockHistoryQuery, no StockQuery, es quien posee period.

Patrones de diseño de herramientas para AI agents que funcionan

La guía de Anthropic “Writing effective tools for agents” presenta las herramientas como «un nuevo tipo de software que refleja un contrato entre sistemas deterministas y agents no deterministas».

Trata las descripciones de herramientas como prompt engineering

Las descripciones deberían tener al menos tres o cuatro frases, cubriendo cuándo utilizar la herramienta, los parámetros obligatorios frente a los opcionales, el formato de salida y los edge cases. Anthropic comunica que la elección entre namespacing basado en prefijo y en sufijo (asana_search frente a search_asana) tuvo «efectos no triviales» en sus propias evaluaciones de tool use. No indica qué esquema gana, así que prueba ambos en tu toolset en lugar de asumir que los prefijos son mejores. Anthropic también introdujo los transcripts de sus agents de evaluación en Claude Code y dejó que reescribiera las herramientas. En test sets reservados, ese loop encontró mejoras adicionales «incluso por encima de las que conseguimos con implementaciones de herramientas “expertas”», tanto si esas herramientas habían sido escritas a mano por sus investigadores como si las había generado Claude.

# Bad: vague, no context for when to use
tools = [{
    "name": "search",
    "description": "Search for items",
}]

# Good: specific, with input examples and edge cases
tools = [{
    "name": "search_news",
    "description": (
        "Search for recent news articles about a specific stock or company. "
        "Use this tool when the user asks about recent events, earnings, "
        "announcements, or market-moving news for a specific ticker. "
        "Returns up to 10 articles sorted by relevance. "
        "For company competitors rather than news, use search_competitors instead."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Search query. Examples: 'NVDA earnings Q3 2025', 'Tesla delivery numbers'"
            },
            "max_results": {
                "type": "integer",
                "description": "Max articles to return (1-10, default 5)",
                "default": 5
            }
        },
        "required": ["query"]
    }
}]

Las pruebas internas de Anthropic mostraron que añadir un campo input_examples elevó la accuracy en el manejo de parámetros complejos del 72 % al 90 %.

Devuelve una salida de alto signal y legible por máquinas

Usa etiquetas semánticas en lugar de identificadores de bajo nivel (uuid, mime_type) en la respuesta por defecto. Conserva un ID cuando otra herramienta lo necesite después u ofrece una respuesta detallada que lo incluya. Por ejemplo, un resultado de búsqueda para Jane puede ser conciso, mientras que un resultado detallado incluye el ID que necesita send_message. Estructura la respuesta para que el agent pueda razonar sobre ella sin analizar boilerplate:

# Bad: raw API response dumped to agent
def get_stock_snapshot(ticker: str) -> dict:
    response = api.get(f"/v1/quotes/{ticker}")
    return response.json()  # 500+ tokens of nested JSON

# Good: high-signal summary the agent can immediately reason about
def get_stock_snapshot(ticker: str) -> dict:
    data = api.get(f"/v1/quotes/{ticker}").json()
    return {
        "ticker": ticker,
        "price": data["regularMarketPrice"],
        "change_pct": round(data["regularMarketChangePercent"], 2),
        "volume": data["regularMarketVolume"],
        "market_cap_b": round(data["marketCap"] / 1e9, 1),
        "pe_ratio": data.get("trailingPE"),
        "summary": f"{ticker} at ${data['regularMarketPrice']:.2f} "
                   f"({'up' if data['regularMarketChangePercent'] > 0 else 'down'} "
                   f"{abs(data['regularMarketChangePercent']):.1f}%)"
    }

Devuelve errores sobre los que el loop pueda actuar

La gestión de errores necesita cuatro mecanismos separados, porque cada uno gestiona una clase de fallo distinta:

1. Retry con exponential backoff para errores transitorios
2. Cadenas de fallback del modelo para caídas del proveedor
3. Error classification routing: los errores transitorios se reintentan, los errores recuperables por el LLM vuelven al agent con contexto y los errores que requieren intervención humana se escalan
4. Checkpoint recovery para sobrevivir a crashes

La guía de Anthropic “Writing effective tools for agents” defiende errores de herramientas claros y un diseño de herramientas guiado por evaluaciones, pero no establece una cifra universal sobre lo que recuperan estos cuatro mecanismos. Mide recovery rate, reintentos y escalados en tu propia task suite.

import httpx
from tenacity import retry, retry_if_exception, stop_after_attempt, wait_exponential

def is_transient_error(error: BaseException) -> bool:
    if isinstance(error, (httpx.TimeoutException, httpx.NetworkError)):
        return True
    if isinstance(error, httpx.HTTPStatusError):
        return error.response.status_code == 429 or 500 <= error.response.status_code < 600
    return False

@retry(
    retry=retry_if_exception(is_transient_error),
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=2, max=10),
    reraise=True,
)
def call_stock_api(ticker: str) -> dict:
    """Fetch stock data with automatic retry on transient failures.

    Mechanism 1 of the four above: exponential backoff for rate limits
    and network blips.
    This only retries transient transport failures. If attempts are exhausted,
    Tenacity re-raises the original httpx exception.
    """
    response = httpx.get(
        f"https://api.example.com/v1/quotes/{ticker}",
        timeout=10.0,
    )
    response.raise_for_status()
    return response.json()

El caller o el harness sigue necesitando el paso siguiente: convertir esa excepción en un resultado estable que indique qué operación falló, si debe reintentarse y qué hacer después. Un 4xx no reintentable omite este decorator y necesita el mismo tratamiento. Reintentar una solicitud no clasifica su error ni recupera un checkpoint.

Aplicación de los patrones al Market Analyst Agent

El Market Analyst Agent de la Parte 1 hace visible el efecto de la interfaz.

Consolidación de herramientas

Los módulos de herramientas originales definían get_stock_price, get_company_metrics, get_price_history, dos herramientas de búsqueda y execute_trade. Para un análisis básico, el agent tenía que elegir tanto la llamada de precio como la de métricas; la capitalización bursátil y el P/E eran campos de get_company_metrics, no herramientas independientes. El código fuente anterior a la consolidación muestra esa superficie.

Reorganicé la superficie de datos de mercado en 5 herramientas de alto nivel, siguiendo el principio de ACI de acciones compactas y eficientes. La lista de herramientas ReAct del repo incluye otras cuatro: un skill loader, dos wrappers CLI y un evaluador Python in-process restringido (una allowlist de AST, no un sandbox; la Parte 4 lo aborda), que cubren tres de las cinco modalidades anteriores. MCP aparece como sidecar, no como una herramienta de esta lista:

Esto traslada el precio y la valoración a una única definición orientada a la tarea y añade los estados financieros como acción explícita. Si mejora la selección de herramientas es una afirmación que debe probarse con solicitudes y traces representativos.

Salidas estructuradas para resultados de herramientas

Las herramientas de acciones y noticias devuelven respuestas validadas con Pydantic. Los wrappers CLI y de ejecución de código devuelven str, por lo que los modelos siguientes describen los resultados estructurados de las herramientas, no cada wrapper del repositorio:

from pydantic import BaseModel

class StockSnapshot(BaseModel):
    """Structured tool response — the agent never sees raw API noise."""
    ticker: str
    price: float
    change_pct: float
    volume: int
    market_cap_b: float
    pe_ratio: float | None
    summary: str  # Human-readable one-liner for direct use in reports

class NewsItem(BaseModel):
    """One news item pre-processed for agent consumption."""
    headline: str
    source: str
    date: str
    relevance_score: float  # Pre-ranked so the agent doesn't waste tokens sorting
    key_points: list[str]  # Extracted by the tool, not the agent

class NewsSearchResult(BaseModel):
    query: str
    results: list[NewsItem]
    summary: str

El campo summary proporciona al agent un string listo para utilizar en un informe. NewsItem.key_points evita que el modelo tenga que analizar el cuerpo de los artículos. Si una acción posterior necesita un ID, consérvalo en la respuesta detallada u ofrece modos conciso y detallado; no lo elimines en todas partes.

Trade-offs y consideraciones

Más allá de las salvedades específicas de cada patrón anterior, algunas cuestiones transversales condicionan la elección:

• El coste operativo varía según la dimensión. La ejecución de código ahorra tokens, pero añade latencia de cold start del sandbox. MCP ahorra tiempo de desarrollo en integraciones SaaS, pero añade overhead de despliegue del servidor. CLI puede arrancar sin coste, pero es más difícil de gobernar a escala. Optimiza para tu cuello de botella real, ya sea el coste de tokens, la latencia o la complejidad operativa.

• Las capacidades del equipo importan. La ejecución de código presupone que tus agents —y los modelos que los respaldan— pueden generar Python o TypeScript fiable. CLI presupone familiaridad con las convenciones de Unix. MCP requiere comprender los protocolos de transporte y los flujos de OAuth. Adapta la modalidad a los puntos fuertes de tu equipo.

• La consolidación de herramientas puede llevarse demasiado lejos. Si una herramienta acumula modos y argumentos no relacionados, el agent se enfrenta a un problema de selección distinto dentro del schema. Utiliza evaluaciones de selección de herramientas y task success para encontrar la superficie adecuada para tu workload.

• Las Skills se basan en prompts, no en enforcement. Una skill contiene instrucciones que el agent debería seguir, no guardrails que deba seguir. Un bundle de skills puede incluir archivos arbitrarios y scripts ejecutables, así que confía en su origen, revisa el bundle y haz que el host aplique los permisos de cada recurso que pueda leer, modificar o ejecutar. En workflows críticos, combina las skills con validación determinista.

• Los requisitos de auditoría condicionan la elección. Las llamadas MCP y JSON estructuradas son eventos cómodos de registrar, pero ninguno de los dos protocolos crea de serie un audit trail completo. El host, el servidor o el harness debe registrar invocaciones y resultados, y después aplicar autorización, policy, retención y revisión. La ejecución de código necesita la misma instrumentación alrededor del sandbox; su script y su salida por sí solos no constituyen un registro de compliance.

Tres direcciones para el tooling de AI agents a escala

La primera es tool RAG para escalar. Antes de que el modelo elija una herramienta, recupera las pocas descripciones que coincidan con la solicitud y deja que elija de ese subconjunto, en lugar de hacerlo del registry completo. En las tareas de benchmark y el MCP stress test de RAG-MCP, la accuracy baseline de selección de herramientas fue del 13,62 %; la recuperación la elevó al 43,13 %, una mejora de 3,2 veces, y redujo los prompt tokens de 2.133,84 a 1.084 (aproximadamente un 49,2 %). El abstract del artículo dice «más del 50 %» y sus descripciones del generador y del evaluador difieren entre secciones; esas inconsistencias limitan la interpretación. El resultado es evidencia para esa configuración de evaluación, no una tasa universal para la selección ingenua a medida que crecen los toolsets.

La segunda son los agents que crean sus propias herramientas. El framework LATM («LLMs As Tool Makers») estableció un paradigma en dos fases en el que un LLM potente crea funciones Python reutilizables y un LLM ligero las utiliza. En el benchmark de 15 tareas de ToolMaker, basado en artículos con repositorios de código públicos y proporcionado mediante URLs de GitHub y descripciones breves de las tareas, implementó correctamente 12 de 15 tareas; el benchmark contiene más de 100 tests en total. Este pequeño benchmark de tareas sobre repositorios no establece una fiabilidad de producción. Ambos trabajos apuntan más allá del tool use, hacia la creación de herramientas y, después, hacia la gestión de una library de herramientas generadas.

La tercera es el stack de doble protocolo A2A + MCP. Google transfirió A2A a la Linux Foundation en junio de 2025. La documentación del protocolo A2A separa sus responsabilidades: MCP conecta un agent con herramientas y recursos, mientras que A2A permite a agents independientes descubrirse, negociar interacciones, gestionar tareas compartidas y delegar trabajo.

Compara las interfaces con tareas y operaciones permitidas idénticas. Registra los discovery tokens, la entrada con y sin caché, la salida de ejecución, los reintentos, la latencia y el éxito del estado final. Prueba tanto el discovery fallido como el ahorro de tokens; en los programas generados, cuenta los errores de sintaxis, los errores de runtime y la finalización parcial.

Conclusiones clave

1. Elige la superficie de ejecución según la acción: JSON calls para operaciones tipadas pequeñas, MCP para servicios compartidos, CLI para comandos establecidos y código en un sandbox para composición local. Usa Skills para documentar cómo elegir y utilizar esa superficie.
2. Mantén las condiciones del benchmark asociadas al resultado. CodeAct, Anthropic, Vercel, Cloudflare, Apideck y Scalekit midieron modelos, tareas, herramientas y harnesses diferentes.
3. La calidad de ACI sobrevive a los cambios de protocolo. Las acciones claras, el feedback compacto, la validación y los errores útiles ayudan a todas las modalidades.
4. Consolida herramientas solapadas solo cuando las evaluaciones demuestren que una superficie más pequeña mejora la selección o el task success.
5. La seguridad se desplaza con la potencia de ejecución. Las interfaces shell y de código necesitan sandboxing; MCP necesita identidad con scope y policy del servidor; las Skills siguen siendo instrucciones, no enforcement.

La siguiente capa es la policy

La Parte 4, AI Agent Security, cubre la comprobación del harness entre una llamada propuesta a una herramienta y su ejecución. La Parte 5 introduce la herramienta y su sandbox en un runtime recuperable. La Parte 6 añade un contrato que el modelo no ve: una categoría de efecto, una regla de retry y un resultado estructurado que un acceptance check puede leer sin analizar prosa.

Referencias

Artículos

• Executable Code Actions Elicit Better LLM Agents (CodeAct) — Wang et al., ICML 2024 — Las acciones basadas en código comunican hasta 20 puntos porcentuales más de task success en las tareas del artículo
• SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering — Yang, Jimenez et al., NeurIPS 2024 — Principios de diseño de ACI y evaluación de SWE-bench (18,0 % para SWE-agent frente al 7,3 % para shell-only sin demostración en la ablation de 300 tareas de SWE-bench Lite del artículo; las condiciones de interfaz y demostración difieren)
• RAG-MCP: Mitigating Prompt Bloat in LLM Tool Selection — Sus tareas de benchmark y su MCP stress test mejoraron la accuracy de selección del 13,62 % al 43,13 %
• LLMs As Tool Makers (LATM) — Cai et al., 2023 — Paradigma en dos fases para la creación de herramientas de agents
• ToolMaker: LLM Agents Making Agent Tools — Wolflein et al., ACL 2025 — 80 % en su benchmark de 15 tareas sobre artículos con repositorios de código públicos
• MCPTox: A Benchmark for Tool Poisoning Attack on Real-World MCP Servers — 72,8 % de attack success medio para o1-mini en un benchmark con 20 agents y 45 servidores

Ingeniería de Anthropic

• Advanced Tool Use / Programmatic Tool Calling — Tool Search (extremos de contexto aproximados de unos 77K y 8,7K), PTC y ejemplos de tool use
• Code Execution with MCP — Reducción del 98,7 % en tokens (de 150K a 2K tokens) mediante orquestación de herramientas basada en código
• Writing Effective Tools for Agents — Ingeniería de descripciones de herramientas; los ejemplos de entrada mejoran la accuracy; enum response_format (72 frente a 206 tokens)
• Building Effective Agents — ACI como principio de diseño fundamental

Especificaciones de protocolos

• Google Cloud donates A2A to Linux Foundation — Anuncio del 23 de junio de 2025 sobre la transferencia del protocolo, el SDK y el tooling
• A2A and MCP: Detailed Comparison — Documentación del protocolo A2A sobre las responsabilidades complementarias entre agent-to-agent y agent-to-tool

Case studies del sector

• Vercel: We Removed 80% of Our Agent’s Tools — el ejemplo antiguo nombra 17 herramientas; el nuevo expone ExecuteCommand y ExecuteSQL; Vercel presenta el rediseño como una eliminación del 80 %; success de 4/5 a 5/5 en cinco consultas representativas, 3,5 veces más rápido y un 37 % menos de tokens
• Cloudflare: Code Mode — Llamadas a la API impulsadas por TypeScript que sustituyen a los tool schemas
• Apideck: MCP Server Eating Your Context Window — 550–1.400 tokens por herramienta, 55K tokens para unas 40 herramientas MCP y 143K/200K de contexto consumidos
• Scalekit: MCP vs CLI Token Benchmark — Overhead de tokens de 4 a 32 veces para MCP frente a CLI en 75 ejecuciones de benchmark

Seguridad

• Vulnerable MCP Project — Informes de vulnerabilidades para construir tests de threat modeling
• AuthZed: Timeline of MCP Breaches — 9 incidentes de seguridad importantes de MCP (abril–octubre de 2025)
• Invariant Labs: MCP Tool Poisoning Attacks — Tool poisoning, rug pulls y escalado cross-origin
• Pivot Point Security: MCP Security Analysis — 43 % de command injection y 43 % de fallos de autenticación OAuth

Diseño de CLI

• Writing CLI Tools That AI Agents Actually Want to Use — Ugo Enyioha — Ocho reglas de diseño para CLIs adaptadas a agents

Proyecto de demostración

• Market Analyst Agent — Implementación completa con consolidación de herramientas y patrones de ACI

El código completo del Market Analyst Agent, incluidos los diseños de herramientas descritos en este artículo, está en GitHub.