APIs Become Tools

In 30 seconds

Agents need more than technical endpoints: clearly described capabilities, boundaries, side effects and secure execution paths. An API only becomes a reliable tool once its contract is unambiguous even for a non-deterministic system.

Why it matters

An agent chooses for itself which tool it calls. If a side effect is not described in the contract, it may trigger it unintentionally.

Tool contracts with idempotency, dry run and compensation logic keep integrations manageable even when the caller acts non-deterministically.

Editorial assessmentA protocol like MCP standardises the connecting of tools — but it replaces neither authorisation nor functional tool boundaries. The contract of the individual function remains the actual work.

The core architecture questions

• Which capabilities, boundaries and side effects does each tool have — described explicitly?
• Which calls are idempotent, which change state irreversibly?
• Is there a dry-run mode for risky actions?
• How are failed multi-step processes compensated?
• How are tool calls logged auditably?

Typical patterns

• Tool Contracts: precise description of inputs, effect and boundaries.
• Idempotency: repeated calls without duplicate effect.
• Dry Run: verify effect before it occurs.
• Compensation Logic: defined rollback on partial failures.
• MCP / A2A behind a Gateway: protocols bundled and exposed in a controlled way.

Common misconceptions & anti-patterns

• Agents are given raw API endpoints without described boundaries.
• Writing tools without idempotency or dry run.
• Protocols like MCP exposed directly to the internet.
• Tool calls without a trace — errors cannot be reconstructed.

Practical review questions

1. Is it documented for each tool what it changes?
2. Can we simulate risky actions first?
3. Do all tool calls run through a controlled gateway?
4. Can every call be traced after the fact?

Link to the end-to-end worked example

Which systems does the agent call — and which calls are read-only, which are write operations?

• Read tools (retrieve case, search knowledge) are clearly separated from write tools (trigger action).
• Write actions have a dry run and are idempotent — a repeated call does no double damage.
• Errors, timeouts and retries are defined in the tool contract; multi-step flows have compensation logic.
• All calls run through a controlled gateway and are logged in an auditable way.

To the full worked example: service agent →

Link to the reference architecture

This mission forms the “Tools, APIs, Events & Workflows” layer. It is the bridge between agent and business systems — and cannot be operated securely without Identity (004) and Observability (005).

Primary sources

Change history

• 25.06.2026 — Editorial Structured according to the mission template.
• 24.06.2026 — Editorial (subject matter) Initial publication with primary sources.