Tool Schema Design
Use when creating or revising function-calling, MCP, plugin, or internal Agent tools and you need clear intent boundaries, bounded schemas, explicit effects, safe defaults, idempotency, errors, and realistic selection tests.
Install
npx skills add sandbaseai/workbuddy-skill --skill tool-schema-designgit clone --depth 1 https://github.com/sandbaseai/workbuddy-skill.git /tmp/workbuddy-skill
mkdir -p ~/.claude/skills
cp -r /tmp/workbuddy-skill/skills/tool-schema-design ~/.claude/skills/tool-schema-designPersonal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.
From the SKILL.md
# Tool Schema Design Make the safe intended call easier for an Agent to choose than an ambiguous or destructive alternative. A JSON Schema or description is not an authorization boundary; enforce identity, tenant, permission, and side effects in the tool implementation. ## Inputs and output contract Collect supported user intents, backend semantics, actor and tenant scope, required credentials (never the values), effects, reversibility, latency, limits, failure modes, provider constraints, and representative valid/invalid requests. Label assumptions. Return: 1. A tool-boundary decision and overlap analysis. 2. A stable model-facing name and description with call and non-call conditions. 3. A valid bounded parameter schema, examples, formats, units, and unknown- field policy. 4. Effect, authorization, confirmation, idempotency, timeout, retry, partial success, compensation, and error contracts. 5. Positive, boundary, adversarial, and contrastive tool-selection tests. 6. Validation results, implementation drift, and provider limitations. ## Design workflow 1. Define one coherent user intent per tool. Split modes with different permissions, effects, or required fields; avoid indistinguishable tiny tools. 2. Choose a stable verb-led name. Explain what it does, when to call it, when not to call it, and what state it changes. 3. Design parameters from user intent, not a backend SDK. Require only
Details
- Skill name
tool-schema-design- Repository
- sandbaseai/workbuddy-skill
- Path
skills/tool-schema-design/SKILL.md- License
- MIT
- Repo updated
- 8 September 2026
FAQ
What does the Tool Schema Design skill do?
Use when creating or revising function-calling, MCP, plugin, or internal Agent tools and you need clear intent boundaries, bounded schemas, explicit effects, safe defaults, idempotency, errors, and realistic selection tests.
How do I install the Tool Schema Design skill?
skills CLI (Claude Code, Cursor, Codex and more): npx skills add sandbaseai/workbuddy-skill --skill tool-schema-design. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.
Is Tool Schema Design popular?
It lives in sandbaseai/workbuddy-skill, which has 9 GitHub stars and 3 forks.
Related skills
Access Control Security Best Practices
9sandbaseai/workbuddy-skill
Design, review, implement, and verify least-privilege access controls across users, services, tenants, resources, and administrative workflows.
Accessibility Review
9sandbaseai/workbuddy-skill
Use when reviewing a web interface or interaction for semantic, keyboard, focus, screen-reader, ARIA, and contrast accessibility risks.
Acquire Codebase Knowledge
9sandbaseai/workbuddy-skill
Use when the user asks to map, document, or onboard into an existing codebase and needs evidence-backed architecture, structure, conventions, integrations, testing, and concerns documentation.
Type Design Analyzer
5euxx/claude-skills-for-copilot
Analyzes type design quality by rating encapsulation, invariant expression, usefulness, and enforcement. Helps design types that make invalid states unrepresentable. Use when reviewing new types or data models.
Threat Model Analyst
9sandbaseai/workbuddy-skill
Use when explicitly asked to threat-model a repository or update an existing threat model with evidence-backed STRIDE-A findings.
Verify Agent Action
9sandbaseai/workbuddy-skill
Use before a consequential agent action to verify its exact target, parameters, scope, approval binding, evidence, freshness, and replay safety without executing it.
Browse the most popular Claude skills, all ai, llms & agents skills, or write your own with the skills generator.