Tool-calling contracts

Defines unambiguous AI tools with constrained inputs, validated execution and outputs that preserve useful context.

tool-calling-contracts

Team members using this skill

AgentEcho

See how it helps

When is it useful?

Use when model tool calls choose wrong actions or produce oversized results.

What does it help you do?

Uses clear domain actions and precise schema constraints.
Separates argument validation, authorization and business-rule checks.
Returns structured errors and bounded outputs for informed recovery.

Try asking this

Design a project-search tool with bounded results and an explicit error for inaccessible projects. Request too many results and include a foreign project identifier. Return a bounded, typed response whose denial reveals no inaccessible project details.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

Tool Calling & Execution Contracts

Tools are the API boundary between a probabilistic model and deterministic application state. Design every tool so its contract is unmistakable to the model, strictly validated at runtime, bounded in output size, and safe under retries.

Designing High-Signal Tool Schemas

Action-oriented, unambiguous names: Use snake_case verbs scoped by domain (orders_get_by_id, repo_search_code, calendar_propose_slot). Avoid overloaded swiss-army tools with modal action: "create" | "update" | "delete" | "search" parameters when separate tools have distinct schemas and permission levels.
Tight JSON Schema constraints:
- Set "additionalProperties": false on object schemas so hallucinated fields fail fast.
- Prefer enum, bounded numeric ranges (minimum, maximum), and pattern-constrained strings over free-form string.
- Write parameter description fields that state units, format, and preconditions (e.g., "ISO-8601 UTC timestamp (YYYY-MM-DDTHH:mm:ssZ). Must be >= start_time.").
Behavioral annotations: Attach explicit metadata to every tool registration:
- readOnlyHint: true if the tool never mutates state.
- destructiveHint: true if the tool deletes or overwrites data irreversibly.
- idempotentHint: true if repeated calls with identical arguments have no additional effect.
- timeoutMs and maxOutputBytes: Explicit execution bounds enforced by the dispatcher.

Three-Layer Validation & Error Recovery

Distinguish protocol errors from model-correctable tool failures:

Failure Class	Example	How the Dispatcher Must Respond
Schema / Argument Validation	Missing required field, invalid enum value, malformed date	Do not throw an unhandled exception. Return a tool result with `isError: true` listing the exact JSON path and expected constraint so the model can self-correct on the next turn.
Domain / Precondition Error	`Order #4821 not found`, `File modified since last read`, `Insufficient permissions`	Return `isError: true` with a concise, structured recovery hint (e.g., `"File changed on disk; call read_file before editing"`).
Transient Infrastructure Failure	`429`, `503`, connection reset on an idempotent backend	Retry inside the tool adapter with exponential backoff + jitter before surfacing a failure to the model.
Fatal Runtime / Bug	Null pointer in tool implementation, revoked service credentials	Log full stack trace to telemetry, redact internals, return `isError: true` with `"Tool temporarily unavailable (ref: <trace_id>); do not retry this tool"`, and trip the tool circuit breaker.

Output Shaping & Context Protection

Never dump raw database rows, full HTML pages, or multi-megabyte command outputs into tool_result:

Project and paginate: Return only the fields required for the task, plus pagination cursors (next_cursor, total_matching, truncated: true).
Deterministic truncation: If a tool output exceeds maxOutputBytes (e.g., 32 KB), store the full payload as an addressable artifact/resource and return a structured summary (head, tail, byte/line counts, and instructions on how to query specific ranges).
Idempotency & dry-run support: For mutating tools, accept an optional dry_run flag or return a preview diff when blast radius is high, and derive a deterministic idempotency key from (run_id, tool_call_id) before calling external APIs.

Included files 1

SKILL.md