tool-schema-design

Tool Schema Design

Make the safe, intended call easier for a model to choose than an ambiguous or destructive alternative.

Use when

• Add or revise a function-calling, MCP, plugin, or internal agent tool.
• Split an overloaded API operation into model-usable actions.
• Reduce wrong-tool selection, malformed arguments, or fabricated fields.
• Document authorization, confirmation, idempotency, and error behavior.

Inputs

Collect supported user intents, backend operation semantics, required credentials, actor and tenant scope, side effects, reversibility, latency, rate limits, failure modes, and provider-specific schema constraints. Obtain representative valid and invalid requests.

Output contract

Produce:

1. A tool-boundary decision and overlap analysis.
2. A model-facing name and description with explicit use and non-use conditions.
3. A valid parameter schema with constraints, examples, and unknown-field policy.
4. Side-effect, confirmation, authorization, idempotency, timeout, and error contracts.
5. Positive, boundary, adversarial, and tool-selection tests.
6. Validation results and any provider-specific limitations.

Workflow

1. Define one coherent user intent per tool. Split tools whose modes have different permissions, side effects, or required fields; avoid tiny tool sets with indistinguishable names.
2. Choose a stable verb-led name. Write the description to say what the tool does, when to call it, when not to call it, and what state it changes.
3. Design parameters from user intent rather than mirroring a backend SDK. Require only indispensable fields, use enums for closed choices, set numeric and length bounds, and describe formats and units. Read schema-patterns.md for composition and mutation patterns.
4. Reject unknown fields when the runtime supports it. Represent conditional shapes with separate tools or explicit schema branches instead of prose-only dependencies.
5. Keep actor identity, authorization scope, and trusted tenant context server-side. Do not ask the model to supply secrets or claims the runtime already knows.
6. Define execution semantics outside the JSON shape: read-only versus mutating, confirmation level, idempotency key, retry safety, timeout, partial success, and compensating action.
7. Return compact structured results and stable machine-readable error codes. Distinguish invalid input, denied authorization, confirmation required, conflict, rate limit, dependency failure, and unknown failure.
8. Test tool selection against neighboring tools and test execution with valid, omitted, extra, boundary, malicious, and stale inputs.