AI Agent Tool Use: MCP, CLI, Skills und Code Execution

Viacheslav Dubrov

2026-03-24 · Aktualisiert 2026-09-06 · 23 Min. · KI-Agenten

Automatische Übersetzung Dieser Artikel wurde automatisch aus der englischen Originalversion übersetzt.

Artikel-Update

Ursprünglich am 24. März 2026 veröffentlicht. Am 6. September 2026 geprüft und aktualisiert. Das Update behandelt die überarbeitete MCP-Spezifikation, Programmatic Tool Calling sowie neue Erkenntnisse zu Kosten und Einschränkungen von Tool Use.

Ein Agent benötigt eine Möglichkeit, Aktionen auszuführen: einen JSON Tool Call, einen MCP-Service, einen CLI-Befehl oder Code in einer Sandbox. Außerdem kann er Anweisungen dafür benötigen, wie dieser Mechanismus auszuwählen und zu verwenden ist. Skills liefern diese Anweisungen. Das Harness ist das gewöhnliche Programm rund um das Model: Es erstellt Prompts, prüft einen vorgeschlagenen Call, führt einen genehmigten Call aus und entscheidet, wann die Aufgabe abgeschlossen ist.

Dieser dritte Artikel der Serie ergänzt die Reasoning Loops aus Teil 1 und die Memory aus Teil 2 um die Action Layer. Teil 4 untersucht den Policy-Check vor der Ausführung, und Teil 6 behandelt das Harness, das sowohl den Call als auch diesen Check ausführt.

Die Tooling-Landschaft hat sich 2025–2026 verändert. MCP, das Model Context Protocol, gab Anbietern eine gemeinsame Möglichkeit, externe Services bereitzustellen. Code-executing Agents zeigten, dass ein Model manchmal effizienter ein kleines Programm zusammenstellen kann, als eine lange Folge von JSON Calls auszugeben. Anthropic berichtete für einen Google-Drive-to-Salesforce-Workflow von einer Token-Reduktion um 98,7 %, und das CodeAct-Paper meldete in seinem Benchmark-Setup Task-Success-Gewinne von bis zu 20 Prozentpunkten. Diese Ergebnisse beziehen sich auf die jeweiligen Tasks und Harnesses und belegen keinen universellen Vorteil von Code Execution.

Ich vergleiche JSON Tool Calling, MCP, CLI Tools und Code Execution und zeige anschließend, wo Skills in dieses Bild passen. Ein späterer Abschnitt wendet die Designprinzipien des Agent-Computer Interface (ACI) auf den Market Analyst Agent an, einen kleinen LangGraph Research Agent, den ich für Teil 1 entwickelt habe und der Marktdaten abruft sowie einen Analystenbericht schreibt.

Eine kurze Entscheidungshilfe für Interfaces findest du unter AI Agent Tool Interfaces.

Ausführungsoberflächen und prozedurale Anleitung

Die Reasoning Loop schlägt einen Call vor. Das Harness prüft dessen Argumente und ob der Call zulässig ist, sendet ihn anschließend an ein Tool oder eine Sandbox und gibt das Ergebnis zurück. JSON Schemas, MCP Transport, CLI Wrapper und Code Runner können Eingaben einschränken, entscheiden aber nicht, ob die angeforderte Aktion zulässig ist. Skills liefern Anweisungen für diesen Ablauf. Diese Ausführungsoberflächen unterscheiden sich bei Token-Kosten, Flexibilität und Enforcement.

1. JSON Tool Calling: die Baseline

Das ursprüngliche Muster: Du definierst Tool Schemas als JSON, das LLM gibt strukturierte Function Calls aus, und dein Code führt sie aus. Das Muster ist gut verstanden und funktioniert für kleine Toolsets problemlos.

# 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"]
        }
    }
]

Zähle die Tokens in deinen tatsächlichen Schemas. Die Kosten hängen von ihrer Länge und davon ab, wie viele das Host lädt; ein kompakter Price Lookup und ein tief verschachtelter API Contract sind keine gleich großen Einheiten. Deferred Discovery kann vermeiden, dass die gesamte Registry geladen wird.

2. MCP für gemeinsam genutzte Integrationen

MCP ist der Standard, auf den sich die meisten Anbieter zubewegt haben. Ein MCP Server ist ein Prozess, der eine Liste von Tools über ein definiertes Wire Protocol bekannt macht – stdio für einen lokalen Prozess, HTTP für einen entfernten. Dein Agent führt einen MCP Client aus, der sich verbindet, den Server nach seinen Tools fragt und die Calls des Models an ihn weiterleitet. Dadurch funktioniert derselbe Server mit jedem Client, der das Protocol spricht. Anthropic übertrug das Protocol im Dezember 2025 an die Linux Foundation, unter der Agentic AI Foundation, die das Unternehmen gemeinsam mit OpenAI und Block gegründet hatte. Google, Microsoft und AWS unterstützen die Foundation als Platinum Members. OpenAI fügte MCP Support in seiner Responses API hinzu. Zum Zeitpunkt von Anthropics Ankündigung der Übertragung im Dezember 2025 umfasste das Ökosystem mehr als 10.000 aktive öffentliche MCP Server und mehr als 97 Millionen monatliche SDK Downloads über die Python- und TypeScript-SDKs.

MCP eignet sich für SaaS-Integrationen über Anbietergrenzen hinweg (Figma, Notion, Salesforce), für Services ohne CLI-Äquivalent und für Umgebungen, die OAuth Orchestration benötigen. Sein Wert liegt in einer gemeinsamen Discovery- und Transport-Layer. Die Governance hängt weiterhin von Authentication, Authorization, Logging und Deployment Controls des Servers ab.

Die Protocol-Version ist inzwischen eine praktische Migrationsentscheidung. Die Revision vom 28.07.2026 ändert Verhaltensweisen, von denen ältere Tutorials ausgehen:

Dieselbe Revision deprecatiert Roots, Sampling, Logging und OAuth Dynamic Client Registration; eine Deprecation bedeutet keine sofortige Entfernung. Die aktuelle Client Registration bevorzugt Client ID Metadata Documents. Bestehende Integrationen können weiterhin eine ältere Revision verwenden. Prüfe deshalb das installierte SDK und den Server Contract, bevor du ein neues Feature einführst.

Die Production Story ist komplexer, als die Schlagzeilen vermuten lassen.

Das Vulnerable MCP Project sammelt Berichte zu Prompt Injection, Input Validation, Authentication und Network Controls. Eine solche Sammlung hilft bei der Identifizierung von Testfällen; ohne einen Exposure Denominator kann sie MCP jedoch nicht gegenüber Shell- oder direkten API Calls einordnen.

Tool Poisoning ist die Angriffsklasse, die mir am meisten Sorgen bereitet. Invariant Labs zeigte, dass manipulierte MCP Tools Daten exfiltrieren können, selbst wenn sie nie aufgerufen werden. Es reicht aus, dass das Model die Metadaten des Tools liest, um den Angriff auszulösen. Die MCPTox Benchmarks, die 20 LLM Agents gegen 45 MCP Server aus der Praxis testeten, meldeten unter ihrem Tool-Poisoning-Setup eine durchschnittliche Attack Success Rate von 72,8 % für o1-mini. Das ist das Benchmark-Ergebnis eines einzelnen Models und keine durchschnittliche Rate über die 20 Agents oder eine reale Incident Rate.

Der operative Problempunkt ist der Token-Overhead. Ein Team, das MCP Server für GitHub, Slack und Sentry betreibt (insgesamt etwa 40 Tools), fand 55.000 Tokens an Schema-Definitionen, die injiziert wurden, bevor ein User überhaupt eine Anfrage stellt. Ein anderer Bericht meldete, dass allein Tool-Definitionen 143.000 von 200.000 verfügbaren Tokens (72 %) verbrauchten.

Der Tool Search Tool Report von Anthropic meldete ungefähre Context-Endpunkte von 77.000 Tokens vor Beginn der Arbeit und 8.700 Tokens nach Deferred Discovery; im traditionellen Setup umfassten die Tool-Definitionen etwa 72.000 Tokens. Dabei werden nur die drei bis fünf Tools geladen, die ein Request benötigt. Allerdings kommt vor der Invocation ein Discovery-Schritt hinzu; für kleine, kompakte Toolsets, deren Tools in jeder Session häufig verwendet werden, ist dieser Ansatz weniger nützlich.

3. Skills bündeln Expertise, nicht Execution

Agent Skills sind ein offenes Format zum Bündeln von Instructions und unterstützenden Dateien. Tools liefern Capabilities (was Agents tun können), Skills liefern Expertise (was Agents darüber wissen, wie sie komplexe Tasks erledigen).

Das SKILL.md-Format definiert einen Skill als Markdown-Datei mit YAML Frontmatter. Der offene Standard erfordert lediglich name und description; das folgende Beispiel verwendet zusätzlich zwei Claude-Code-Extensions, argument-hint und user-invocable, sowie den positional-argument placeholder $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

Skills verwenden Progressive Disclosure. Beim Startup erhält der Agent etwa 100 Tokens an name und description. Erst wenn er den Skill benötigt, lädt er das vollständige SKILL.md und anschließend bei Bedarf referenzierte Scripts, Dokumente oder Assets. Diese Startup-Kosten sind deutlich geringer als die rund 55.000 Tokens, die etwa 40 MCP Tools verbrauchen können, bevor das Reasoning beginnt. Ein aktiver Skill fügt dem Context weiterhin seine Instructions und Resources hinzu.

Verwende Skills für Domain Knowledge, Multi-Step-Prozeduren und wiederkehrende Aufgaben wie Database Migrations oder Payment Integrations. Sie eignen sich für Tasks, bei denen der Agent Instructions dafür benötigt, wie eine bestehende Capability verwendet wird.

4. CLI- und Shell-Tools

CLI Interfaces können beim Context deutlich günstiger sein, wenn das Model den Befehl bereits kennt. Scalekit berichtete über einen Token-Unterschied um den Faktor 4 bis 32 zwischen seinen CLI- und MCP-Pfaden in 75 Runs. Diese Case Study misst die eigenen Tools und Tasks; sie ersetzt keinen Vergleich mit deinen eigenen Tool-Definitionen und Command Outputs.

Gut dokumentierte Befehle wie git, docker, kubectl, gh, curl und jq benötigen häufig nur wenig einführenden Schema-Text. Weniger verbreitete oder interne CLIs brauchen weiterhin auffindbare Hilfe, Beispiele und stabiles maschinenlesbares Output.

Ugo Enyiohas Leitfaden “Writing CLI Tools That AI Agents Actually Want to Use” formulierte acht Designregeln:

1. Structured Output ist verpflichtend — unterstütze --json
2. Exit Codes sind Control Flow — verwende unterschiedliche Codes für verschiedene Fehlertypen
3. Commands sollten idempotent sein
4. Self-documenting --help mit realistischen Beispielen
5. Auf Composability auslegen — --quiet für reine Werte, stdin-Unterstützung
6. Stelle --dry-run- und --yes-Flags bereit
7. Unterstütze Version Introspection
8. Behandle Auth über Environment Variables

CLI verfügt über keine Protocol-Level Discovery. JSON Tool Calling kann typisierte Schemas übertragen, während MCP Tool Discovery und bei HTTP Transports ein Authorization Model standardisiert. Keine der beiden Optionen liefert Governance automatisch: Host, Server oder Harness müssen Policy erzwingen und die für Audits erforderlichen Calls protokollieren. Ein praktischer Default ist CLI für Development und lokale Operations sowie MCP für die Integration gemeinsam genutzter externer Services, wenn Cross-Client Discovery oder OAuth Orchestration den Server-Overhead rechtfertigen.

5. Code Execution für Multi-Step-Workflows

Das ist die aus meiner Sicht folgenreichste Veränderung beim Agent Tooling. Statt strukturiertes JSON auszugeben und vordefinierte Functions einzeln aufzurufen, schreibt der Agent ein Python- oder Bash-Script. Das Script ruft mehrere Tools auf, verarbeitet Ergebnisse mit Loops und Conditionals und gibt nur die abschließende Zusammenfassung an den Model Context zurück.

Anthropic führte Programmatic Tool Calling (PTC) als Beta ein. Der aktuelle API Guide verwendet die reguläre Messages API mit code_execution_20260120 oder höher; der ursprüngliche Beta-Launch dient als historischer Kontext. Die akademische Grundlage ist das CodeAct-Paper (Wang et al., ICML 2024), das 17 LLMs testete und feststellte, dass Code Actions bis zu 20 Prozentpunkte höhere Task Success sowie 30 % weniger Actions als JSON-Alternativen erreichten.

Drei First-Party Case Studies zeigen, wo dieses Muster helfen kann: Vercel und Cloudflare im Folgenden sowie anschließend das Expense-Analysis-Beispiel von Anthropic. Betrachte sie als Vendor Evidence und wiederhole den Vergleich mit deinen eigenen Tasks.

• Vercel hat d0, seinen Natural-Language-to-SQL Data Agent, neu aufgebaut. Das alte Code-Beispiel nennt 17 Tools; das neue Code-Beispiel stellt ExecuteCommand und ExecuteSQL bereit. Vercel beschreibt das Redesign als Entfernung von 80 % seiner Tools. Diese Aussage ist jedoch Vercels Headline und kein Prozentsatz, der sich aus den genannten Tools der Beispiele ableiten lässt. Über fünf repräsentative Queries hinweg berichtet Vercel, dass der Task Success von 4/5 auf 5/5 stieg, die durchschnittliche Execution Time um den Faktor 3,5 sank (274,8 s auf 77,4 s) und der durchschnittliche Token-Verbrauch um 37 % zurückging (~102k auf ~61k). Die Formulierung lautet: „The best agents might be the ones with the fewest tools.“

• Cloudflare entwickelte „Code Mode“, mit dem Agents TypeScript schreiben können, um die API aufzurufen, anstatt Tool Schemas zu definieren. Dadurch sinkt der Context-Overhead. Die Begründung: „LLMs have an enormous amount of real-world TypeScript in their training set, but only a small set of contrived examples of tool calls.“

Hier ist das Muster aus Anthropics PTC-Dokumentation. In Anthropics sequenzieller Expense-Analysis-Illustration erfordert traditionelles Tool Calling mehr als 20 separate Inference Passes, wobei Zwischendaten durch den Context fließen. Nach dem Team Lookup kann ein Host, der parallele Tool Calls unterstützt, die unabhängigen Expense Requests batchen; die Zahl von mehr als 20 macht das nicht unmöglich. Anthropic berichtet, dass generierter Code, der dieselbe Frage beantwortet, den in den Context gelangenden Umfang von 200 KB roher Expense Rows – mehr als 2.000 Line Items – auf 1 KB Ergebnisse reduziert. Das folgende Script illustriert diesen Control Flow mit eigenen asynchronen Python-Adaptern: Sie akzeptieren positionale Argumente und geben decodierte Listen und Dictionaries zurück. Es handelt sich nicht um den nativen PTC Wrapper Contract.

# 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())

Um native Claude-PTC-Wrapper zu verwenden, übergib jedem Tool ein Argument-Dictionary, decodiere seinen zurückgegebenen JSON-String und verwende auf Top-Level await in der verwalteten Execution Environment, statt mit asyncio.run einen Event Loop zu starten. Das Beispiel mit den Custom Adapters oben setzt eine gewöhnliche Python-Script-Runtime voraus und ist ebenfalls kein direkt einsetzbares Beispiel für einen nativen MCP Connector. Die aktuellen PTC API Constraints schließen strict: true-Tools und native MCP Connector Tools vom Programmatic Calling aus und schränken rekursive Schemas ein. Eine eigene Code-to-MCP Bridge ist eine separate Integration. allowed_callers beschreibt, wie Claude ein Tool aufruft; es ist keine Authorization Boundary. Der Host muss jede zurückgegebene Invocation validieren, auch einen unerwarteten direkten Call.

Das LLM sieht nur die abschließende JSON-Zusammenfassung, nicht die Tausenden von Expense Line Items, die in der Sandbox verarbeitet wurden. Die Einsparung ist nicht spezifisch für Expense Reports: Anthropics separate Darstellung zu Code Execution nennt die deutlichste Zahl für dieses Muster – einen Google-Drive-to-Salesforce-Workflow, der von etwa 150.000 auf etwa 2.000 Tokens sank, eine Reduktion um 98,7 %.

Der aktuelle PTC Guide berichtet außerdem von einem Gegenbeispiel: Bei den Airline-, Retail- und Telecom-Tasks von tau2-bench änderte PTC die Scores nicht und kostete etwa 8 % mehr. In einem separaten Project-Management-Benchmark mit 75 Tools reduzierte PTC die abgerechneten Input Tokens um ungefähr 38 %, ohne die Accuracy zu verändern. Diese internen Evaluations nennen nur ein Production-Claude-Model, aber keine exakte ID. Kleine sequenzielle Workflows sparen möglicherweise nicht genug, um den Overhead für Container und Code Generation auszugleichen.

Token-Effizienz ist ein möglicher Vorteil. Loops und Conditionals sind praktisch kostenlos, und Code Execution kann Fehler mit expliziten Handlern behandeln, statt das Model dazu zu zwingen, Failures in natürlicher Sprache zu durchdenken. Ein Code-Execution-Pfad kann sensible Zwischendaten aus dem Model Context heraushalten, aber das ist keine Confidentiality-Garantie: Isolation, Egress Controls, Scoped Credentials und Logging müssen separat durchgesetzt werden.

Wann JSON Tool Calling weiterhin sinnvoll ist: bei einzelnen atomaren Operations, in Umgebungen ohne Sandbox-Infrastruktur, bei kleineren Models mit schwacher Code Generation oder bei Audit-Anforderungen, die jede einzelne Tool Invocation protokollieren müssen.

Vergleich der Tool Execution für AI Agents

JSON Tool Calling, MCP, CLI und Code Execution sind Ausführungsoberflächen. Skills sind Instructions, die eine dieser Oberflächen anleiten. Daher hängen ihre Latency, ihr Context-Bedarf und ihr Setup von der gewählten Mechanik ab. „Meta-Tools“ bezeichnet die wenigen generischen Entry Points, die ein code-executing Agent benötigt – beispielsweise Vercels ExecuteCommand und ExecuteSQL – statt eines Schemas für jede einzelne Operation. Die Zeilen zu Composability und Latency beschreiben Calls, deren spätere Argumente von früheren Ergebnissen abhängen. JSON Tool Calling und MCP können unabhängige Calls gemeinsam ausführen, abhängige Calls benötigen jedoch üblicherweise einen weiteren Model Turn. PTC verschiebt diesen abhängigen Control Flow und das Filtering in ein Script und gibt anschließend eine Zusammenfassung an das Model zurück. Die Token- und Task-Success-Zellen fassen zitierte Beispiele zusammen und sind kein kontrollierter Benchmark über alle fünf Spalten hinweg.

Das Agent-Computer Interface (ACI) für AI-Agent-Tools

Der Begriff „Agent-Computer Interface“ (ACI) wurde von John Yang, Carlos E. Jimenez und Kollegen an der Princeton University in ihrem SWE-agent-Paper (NeurIPS 2024) geprägt. Die Qualität menschlicher Interfaces hat mit Human-Computer Interaction, kurz HCI, eine eigene Disziplin. Das Paper argumentiert, dass Language-Model Agents genauso behandelt werden sollten: Sie seien „a new category of end users with their own needs and abilities, and would benefit from specially-built interfaces.“

Ihre Ablation Results quantifizieren diesen Effekt. Mit demselben GPT-4-Turbo-Basismodell erreichte die SWE-bench-Lite-Ablation des Papers mit dem vollständigen ACI von SWE-agent 18,0 % auf 300 Tasks, gegenüber 7,3 % für die Shell-only-Bedingung ohne Worked Demonstration und 11,0 % mit einer Demonstration. Der Vergleich zeigt, dass Interface- und Demonstrationsbedingungen die Performance in diesem Setup deutlich veränderten; er isoliert Interface Design nicht von allen anderen Unterschieden und zeigt nicht, dass das Model keine Arbeit geleistet hätte. Innerhalb derselben Interface-Ablation erhöhte aktiviertes Linting den Edit-Condition-Wert von 15,0 % auf 18,0 %; über den vollständigen SWE-bench-Testset hinweg trafen 51,7 % der SWE-agent-Runs mindestens auf ein Edit, das der Linter zurückwies, bevor es weitergegeben werden konnte.

Anthropic übernahm ACI als grundlegendes Konzept in seinem Guide “Building Effective Agents” und listet es als eines von drei Core Principles: „Carefully craft your agent-computer interface through thorough tool documentation and testing.“ Die praktische Empfehlung lautet: „One rule of thumb is to think about how much effort goes into human-computer interfaces, and plan to invest just as much effort in creating good agent-computer interfaces.“

Vier ACI-Prinzipien in der Praxis

1. Actions sollten einfach und verständlich sein. Der häufigste Fehler besteht darin, API Endpoints eins zu eins zu wrappen. Implementiere statt list_users, list_events und create_event ein schedule_event, das Availability und Scheduling in einem Call findet. Implementiere statt read_logs ein search_logs, das nur die relevanten Zeilen mit Context zurückgibt.

2. Actions sollten kompakt und effizient sein. Konsolidiere wichtige Operations in so wenigen Actions wie möglich. Im Market Analyst Agent kombiniere ich das Abrufen von Preisen mit grundlegenden Metriken in einem einzigen get_stock_snapshot Tool, statt separate Calls für Price, Volume, Market Cap und PE Ratio zu verlangen.

3. Environment Feedback sollte informativ, aber prägnant sein. Vermeide die Rückgabe von rohem HTML oder vollständigen API Payloads. Löse kryptische IDs in semantische Namen auf. Anthropics Testing fügte ein response_format Enum hinzu, damit der Agent eine kompakte Antwort (~72 Tokens) oder eine detaillierte Antwort (~206 Tokens) anfordern kann – ein Unterschied bei den Token-Kosten von ungefähr Faktor 3.

4. Validation sollte Error Propagation begrenzen. Automatische Error Detection hilft Agents, Fehler schnell zu erkennen und zu korrigieren. In SWE-agent weist ein Custom File Editor mit integriertem Linting Syntaxfehler automatisch zurück – der Validierungsschritt hinter den oben genannten 51,7 %. Dabei handelt es sich um Validation von Inputs und Outputs eines Tools, nicht um Content Filtering rund um einen Model Call, wie es die Guardrail-Produkte in Teil 4 tun; dasselbe Wort wird für beides verwendet. Ich wende dasselbe Prinzip im Market Analyst Agent an, indem ich Tool Arguments vor der Execution mit Pydantic Schemas validiere:

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

Der gemeinsame Normalizer entfernt Whitespace und wandelt den Wert in Großbuchstaben um. Anschließend akzeptiert er Ticker-Digits sowie punkt- oder bindestrichgetrennte Suffixe wie BRK.B und BF-B; StockHistoryQuery, nicht StockQuery, besitzt period.

AI-Agent-Tool-Design-Patterns, die funktionieren

Anthropics Guide “Writing effective tools for agents” beschreibt Tools als „a new kind of software which reflects a contract between deterministic systems and non-deterministic agents.“

Behandle Tool Descriptions als Prompt Engineering

Descriptions sollten mindestens drei oder vier Sätze umfassen und abdecken, wann das Tool verwendet werden sollte, welche Parameter erforderlich beziehungsweise optional sind, welches Output-Format gilt und welche Edge Cases existieren. Anthropic berichtet, dass die Wahl zwischen Prefix- und Suffix-based Namespacing (asana_search beziehungsweise search_asana) „non-trivial effects“ auf die eigenen Tool-Use-Evaluations hatte. Es wird nicht angegeben, welches Schema gewinnt. Teste daher beide Varianten mit deinem Toolset, statt Prefixes vorauszusetzen. Anthropic gab außerdem die Transcripts seiner Evaluation Agents zurück an Claude Code und ließ die Tools umschreiben. Auf zurückgehaltenen Testsets fand dieser Loop weitere Verbesserungen „even beyond what we achieved with ‘expert’ tool implementations“ – unabhängig davon, ob die Tools von den Researchern von Hand geschrieben oder von Claude generiert worden waren.

# 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"]
    }
}]

Anthropics interne Tests zeigten, dass ein hinzugefügtes input_examples-Feld die Accuracy bei komplexem Parameter Handling von 72 % auf 90 % erhöhte.

Liefere High-Signal-, maschinenlesbares Output

Verwende in der Default Response semantische Labels statt Low-Level Identifiers (uuid, mime_type). Behalte eine ID, wenn ein späteres Tool sie benötigt, oder biete eine detaillierte Response an, die sie enthält. Ein Search Result für Jane kann beispielsweise kompakt lesbar sein, während ein detailliertes Result die ID enthält, die send_message benötigt. Strukturiere die Response so, dass der Agent darüber Reasoning betreiben kann, ohne Boilerplate parsen zu müssen:

# 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}%)"
    }

Gib Errors zurück, mit denen die Loop arbeiten kann

Error Handling benötigt vier separate Mechanisms, da sie unterschiedliche Failure Classes behandeln:

1. Retry mit exponential Backoff für transiente Errors
2. Model Fallback Chains bei Provider Outages
3. Error-Classification Routing – transiente Errors werden wiederholt, für das LLM recoverable Errors gehen mit Context an den Agent zurück, und Human-required Errors werden eskaliert
4. Checkpoint Recovery zum Überleben von Crashes

Anthropics “Writing effective tools for agents” empfiehlt klare Tool Errors und Evaluation-driven Tool Design, nennt jedoch keine universelle Zahl dafür, wie viele dieser vier Mechanisms recovern. Miss Recovery Rate, Retries und Escalations in deiner eigenen 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()

Der Caller oder das Harness benötigt weiterhin den nächsten Schritt: Es muss diese Exception in ein stabiles Result umwandeln, das angibt, welche Operation fehlgeschlagen ist, ob ein Retry erfolgen soll und was als Nächstes zu tun ist. Ein nicht wiederholbarer 4xx-Fehler überspringt diesen Decorator und benötigt dieselbe Behandlung. Ein erneuter Request klassifiziert seinen Error nicht und stellt auch keinen Checkpoint wieder her.

Anwendung der Patterns auf den Market Analyst Agent

Der Market Analyst Agent aus Teil 1 macht den Effekt des Interfaces sichtbar.

Tool Consolidation

Die ursprünglichen Tool-Module definierten get_stock_price, get_company_metrics, get_price_history, zwei Search Tools und execute_trade. Für eine grundlegende Analyse musste der Agent sowohl den Price- als auch den Metrics-Call auswählen; Market Cap und P/E waren Felder von get_company_metrics und keine eigenständigen Tools. Der Source vor der Consolidation zeigt diese frühere Oberfläche.

Ich habe die Market-Data-Oberfläche gemäß dem ACI-Prinzip kompakter und effizienter Actions in fünf High-Level-Tools umgeformt. Die ReAct-Tool-Liste des Repositories enthält daneben vier weitere: einen Skill Loader, zwei CLI Wrapper und einen eingeschränkten In-Process-Python-Evaluator (eine AST-Allowlist, keine Sandbox; Teil 4 behandelt das Thema). Damit werden drei der fünf oben genannten Modalitäten abgedeckt. MCP erscheint als Sidecar und nicht als Tool in dieser Liste:

Damit werden Price und Valuation in einer auf den Task zugeschnittenen Definition zusammengeführt und Financial Statements als explizite Action hinzugefügt. Ob die Tool Selection dadurch besser wird, muss anhand repräsentativer Requests und Traces getestet werden.

Structured Outputs für Tool Results

Die Stock- und News-Tools liefern Pydantic-validierte Responses. Die CLI- und Code-Execution-Wrapper geben str zurück. Die folgenden Models beschreiben daher die strukturierten Tool Results und nicht jeden Wrapper im Repository:

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

Das Feld summary liefert dem Agent einen direkt verwendbaren String für einen Report. NewsItem.key_points ersparen dem Model das Parsen von Article Bodies. Wenn eine spätere Action eine ID benötigt, behalte sie in der detaillierten Response oder biete Concise- und Detailed-Modes an; entferne sie nicht überall.

Trade-offs und Überlegungen

Neben den spezifischen Einschränkungen der oben beschriebenen Patterns beeinflussen einige übergreifende Aspekte die Auswahl:

• Die Operational Costs variieren je nach Dimension. Code Execution spart Tokens, fügt aber Cold-Start-Latency der Sandbox hinzu. MCP spart Development Time bei SaaS-Integrationen, erzeugt aber zusätzlichen Server-Deployment-Overhead. CLI startet kostenlos, ist aber schwieriger im großen Maßstab zu govern. Optimiere für deinen tatsächlichen Bottleneck – unabhängig davon, ob es Token-Kosten, Latency oder operative Komplexität ist.

• Team Skills spielen eine Rolle. Code Execution setzt voraus, dass deine Agents (und die dahinterliegenden Models) zuverlässiges Python oder TypeScript generieren können. CLI setzt Vertrautheit mit Unix-Konventionen voraus. MCP erfordert Verständnis von Transport Protocols und OAuth Flows. Stimme die Modalität auf die Stärken deines Teams ab.

• Tool Consolidation kann zu weit gehen. Wenn ein Tool unzusammenhängende Modes und Arguments anhäuft, steht der Agent vor einem anderen Selection-Problem innerhalb des Schemas. Verwende Tool-Selection- und Task-Success-Evaluations, um die richtige Oberfläche für deinen Workload zu finden.

• Skills basieren auf Prompts und werden nicht enforced. Ein Skill enthält Instructions, die der Agent befolgen sollte, keine Guardrails, die er befolgen muss. Ein Skill Bundle kann beliebige Dateien und ausführbare Scripts enthalten. Vertraue daher auf die Quelle, prüfe das Bundle und lasse den Host die Permissions für jede Ressource erzwingen, die der Agent lesen, ändern oder ausführen kann. Kombiniere Skills bei kritischen Workflows mit deterministischer Validation.

• Audit-Anforderungen beeinflussen die Auswahl. Strukturierte MCP- und JSON Calls sind praktische Events für Logging, aber keines der beiden Protocols erzeugt standardmäßig einen vollständigen Audit Trail. Host, Server oder Harness müssen Invocations und Results protokollieren und anschließend Authorization, Policy, Retention und Review erzwingen. Code Execution benötigt dieselbe Instrumentierung rund um die Sandbox; Script und Output allein sind kein Compliance Record.

Drei Richtungen für AI-Agent-Tooling im großen Maßstab

Die erste Richtung ist Tool RAG für die Skalierung. Bevor das Model ein Tool auswählt, werden die wenigen Tool Descriptions abgerufen, die zum Request passen. Das Model wählt dann aus dieser Teilmenge statt aus der vollständigen Registry. In den Benchmark-Tasks und dem MCP-Stresstest von RAG-MCP lag die Baseline Tool-Selection Accuracy bei 13,62 %; Retrieval erhöhte sie auf 43,13 %, eine Verbesserung um den Faktor 3,2, während die Prompt Tokens von 2.133,84 auf 1.084 sanken (etwa 49,2 %). Das Abstract des Papers spricht von „over 50 %“, und die Beschreibungen von Generator und Evaluator unterscheiden sich zwischen den Abschnitten. Diese Inkonsistenzen begrenzen die Interpretation. Das Ergebnis ist Evidenz für dieses Evaluations-Setup und keine universelle Rate für naive Selection bei wachsenden Toolsets.

Die zweite Richtung sind Agents, die ihre eigenen Tools erstellen. Das LATM Framework („LLMs As Tool Makers“) etablierte ein Zwei-Phasen-Paradigma, bei dem ein leistungsfähiges LLM wiederverwendbare Python Functions erstellt und ein leichtgewichtiges LLM sie verwendet. Im ToolMaker-Benchmark mit 15 Tasks zu Papers mit öffentlichen Code-Repositories, die als GitHub-URLs und kurzen Task Descriptions bereitgestellt wurden, implementierte es 12 von 15 Tasks korrekt; der Benchmark enthält insgesamt mehr als 100 Tests. Dieser kleine Repository-Task-Benchmark belegt keine Production Reliability. Beide Ansätze weisen über Tool Use hinaus in Richtung Tool Creation und anschließend auf die Verwaltung einer Library generierter Tools.

Die dritte Richtung ist der Dual-Protocol-Stack aus A2A + MCP. Google übertrug A2A im Juni 2025 an die Linux Foundation. Die A2A-Protocol-Dokumentation trennt die Verantwortlichkeiten: MCP verbindet einen Agent mit Tools und Resources, während A2A es unabhängigen Agents ermöglicht, einander zu entdecken, Interactions auszuhandeln, gemeinsame Tasks zu verwalten und Arbeit zu delegieren.

Vergleiche Interfaces anhand identischer Tasks und zulässiger Operations. Erfasse Discovery Tokens, gecachte und nicht gecachte Eingaben, Execution Output, Retries, Latency und den Erfolg des finalen Zustands. Teste sowohl verpasste Discovery als auch Token-Einsparungen. Zähle bei generierten Programmen Syntax Errors, Runtime Errors und Partial Completion.

Wichtigste Erkenntnisse

1. Wähle die Ausführungsoberfläche anhand der Action: JSON Calls für kleine typisierte Operations, MCP für gemeinsam genutzte Services, CLI für etablierte Commands und sandboxed Code für lokale Composition. Verwende Skills, um zu dokumentieren, wie diese Oberfläche ausgewählt und verwendet wird.
2. Halte die Benchmark-Bedingungen am Ergebnis fest. CodeAct, Anthropic, Vercel, Cloudflare, Apideck und Scalekit haben unterschiedliche Models, Tasks, Tools und Harnesses gemessen.
3. ACI-Qualität bleibt auch bei Protocol-Änderungen relevant. Klare Actions, kompaktes Feedback, Validation und nützliche Errors helfen bei jeder Modalität.
4. Konsolidiere überlappende Tools nur dann, wenn Evaluations zeigen, dass die kleinere Oberfläche Selection oder Task Success verbessert.
5. Security folgt der Execution Power. Shell- und Code-Interfaces benötigen Sandboxing; MCP benötigt Scoped Identity und Server Policy; Skills bleiben Instructions und sind kein Enforcement.

Die nächste Schicht ist Policy

Teil 4, AI Agent Security, behandelt den Harness Check zwischen einem vorgeschlagenen Tool Call und der Execution. Teil 5 setzt das Tool und seine Sandbox in einen recoverable Runtime-Kontext. Teil 6 fügt einen Contract hinzu, den das Model nicht sieht: eine Effect Category, eine Retry Rule und ein Structured Result, das ein Acceptance Check ohne Parsen von Prosa lesen kann.

Referenzen

Papers

• Executable Code Actions Elicit Better LLM Agents (CodeAct) — Wang et al., ICML 2024 — Code-basierte Actions erzielten in den Tasks des Papers bis zu 20 Prozentpunkte höheren Task Success
• SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering — Yang, Jimenez et al., NeurIPS 2024 — ACI-Designprinzipien und SWE-bench-Evaluation (18,0 % für SWE-agent gegenüber 7,3 % für Shell-only ohne Demonstration in der 300-Task-SWE-bench-Lite-Ablation des Papers; Interface- und Demonstrationsbedingungen unterscheiden sich)
• RAG-MCP: Mitigating Prompt Bloat in LLM Tool Selection — Die Benchmark-Tasks und der MCP-Stresstest verbesserten die Selection Accuracy von 13,62 % auf 43,13 %
• LLMs As Tool Makers (LATM) — Cai et al., 2023 — Zwei-Phasen-Paradigma für die Erstellung von Agent Tools
• ToolMaker: LLM Agents Making Agent Tools — Wolflein et al., ACL 2025 — 80 % in seinem 15-Task-Benchmark zu Papers mit öffentlichen Code-Repositories
• MCPTox: A Benchmark for Tool Poisoning Attack on Real-World MCP Servers — 72,8 % durchschnittliche Attack Success für o1-mini in einem Benchmark mit 20 Agents und 45 Servern

Anthropic Engineering

• Advanced Tool Use / Programmatic Tool Calling — Tool Search (ungefähre Context-Endpunkte ~77K und ~8,7K), PTC und Beispiele für Tool Use
• Code Execution with MCP — 98,7 % Token-Reduktion (150K auf 2K Tokens) durch code-basierte Tool Orchestration
• Writing Effective Tools for Agents — Tool-Description Engineering; Input Examples verbessern die Accuracy; response_format Enum (72 gegenüber 206 Tokens)
• Building Effective Agents — ACI als grundlegendes Designprinzip

Protocol-Spezifikationen

• Google Cloud donates A2A to Linux Foundation — Ankündigung der Übertragung von Protocol, SDK und Tooling am 23. Juni 2025
• A2A and MCP: Detailed Comparison — A2A-Protocol-Dokumentation zu den komplementären Verantwortlichkeiten von Agent-to-Agent und Agent-to-Tool

Industry Case Studies

• Vercel: We Removed 80% of Our Agent’s Tools — Das alte Beispiel nennt 17 Tools; das neue Beispiel stellt ExecuteCommand und ExecuteSQL bereit; Vercel beschreibt das Redesign als Entfernung von 80 %; Success stieg über fünf repräsentative Queries von 4/5 auf 5/5, bei 3,5-facher Geschwindigkeit und 37 % weniger Tokens
• Cloudflare: Code Mode — TypeScript-gesteuerte API Calls ersetzen Tool Schemas
• Apideck: MCP Server Eating Your Context Window — 550–1.400 Tokens pro Tool, 55K Tokens für etwa 40 MCP Tools, 143K/200K des Contexts verbraucht
• Scalekit: MCP vs CLI Token Benchmark — 4- bis 32-facher Token-Overhead für MCP gegenüber CLI über 75 Benchmark-Runs

Security

• Vulnerable MCP Project — Vulnerability Reports zur Erstellung von Threat-Model-Tests
• AuthZed: Timeline of MCP Breaches — 9 größere MCP-Security-Incidents (April bis Oktober 2025)
• Invariant Labs: MCP Tool Poisoning Attacks — Tool Poisoning, Rug Pulls und Cross-Origin Escalation
• Pivot Point Security: MCP Security Analysis — 43 % Command Injection, 43 % OAuth Authentication Flaws

CLI Design

• Writing CLI Tools That AI Agents Actually Want to Use — Ugo Enyioha — Acht Designregeln für Agent-freundliche CLIs

Demo-Projekt

• Market Analyst Agent — Vollständige Implementierung mit Tool Consolidation und ACI Patterns

Der vollständige Code des Market Analyst Agent einschließlich der in diesem Beitrag beschriebenen Tool Designs ist auf GitHub verfügbar.