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...