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.

9 stars 3 forksAI, LLMs & Agents

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add sandbaseai/workbuddy-skill --skill tool-schema-design
Manual install
git 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-design

Personal 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
Read the full skill on GitHub

Details

Skill name
tool-schema-design
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

Browse the most popular Claude skills, all ai, llms & agents skills, or write your own with the skills generator.