Tool-Call Contract Auditor

Catch bad tool calls before they corrupt state — pre-call contracts, failure taxonomy, and when to stop vs retry. For MCP and multi-tool agents.

Upgrade Path

Free teaches the checklist in conversation. Tool-Call Contract Auditor Pro ($9.99 one-time) adds scripts/lint_tool_schemas.py, scripts/replay_tool_trace.py, contract YAML templates, a GitHub Action CI gate, and Markdown/JSON export reports.

Upgrade when you maintain more than three tools, ship tools to others, or need a merge gate.

https://www.agensi.io/skills/tool-call-contract-auditor-pro

Tags: agents, mcp, tools, reliability, json-schema Version: 1.0

The Problem

You give the agent twelve tools. It calls transfer_funds with a string amount, retries a non-idempotent charge three times, then marks the task "done" because the tool returned HTTP 200 with an error body. Your dashboard looks fine. Your ledger does not.

Loops burn tokens. Bad contracts burn trust.

This is not loop detection (that is a separate concern) and not prompt-injection review. It is the contract layer: what must be true before a call fires, and what the return actually means.

What You Get

• Pre-call contract checklist — tool selection, required args, types, enums and ranges, side-effect class (read / mutate / irreversible), idempotency, retry budget, allow-deny, auth surface
• Post-call verdict rules — success vs partial vs error, with the rule that partial is never success and a timeout on an irreversible call is unknown, not retry
• Failure taxonomy — arg, auth, timeout, partial, side-effect, plus the named modes wrong-tool, bad-args, skip-retry, double-fire, partial-as-success, missing-contract
• Idempotency stop rules — when retry is safe, when to reuse the same key, and when to stop and ask for a dedupe key
• Four hard skill rules — never invent tool results, never treat HTTP 200 with an error body as success, never skip the post-call verdict, never silently retry an irreversible side effect

Why This Beats Prompting It Yourself

Telling an agent to be careful with tool calls produces a disposition, not a checklist. The failure that costs money is specific: a non-idempotent call re-fired after a timeout, or a 200-with-error-body read as done. A checklist that sorts every tool call by side-effect class before it fires, and forces one of three verdicts after it returns, catches those two failures deterministically — the same rows, the same order, every session.

It also gives a postmortem a shared vocabulary. "It was a partial-as-success" is actionable; "the agent messed up" is not.

Example Session

Ask the agent to audit a call it is about to make: process_refund for $50.00 passed as a string, no idempotency key, tool marked irreversible.

The auditor runs the pre-call rows. Tool selection passes. Required args pass. Types fail — the amount is a string where currency needs a numeric. Side-effect class reads irreversible. Idempotency fails — no dedupe key on an irreversible call. Verdict is BLOCK, with the two failing rows named and the fix stated: cast the amount, generate a UUID idempotency key, re-submit for a fresh pre-call pass.

The block happens before the call fires. Nothing is charged twice.

Use Cases

• Audit a tool call before firing it, or review a recorded session trace for contract breaks
• Decide success vs partial vs error when a tool returns 200 with an error body, a truncated body, or a timeout
• Classify a production incident into the failure taxonomy so the postmortem names one cause
• Stop an agent from re-firing an irreversible action after a timeout

Known Limitations

• Checklist and taxonomy only — no automated schema lint, no replay, no CI gate
• Cannot see tools the harness hides from the agent
• Does not replace provider-side idempotency keys
• Does not invent pass rates or sales claims