tool-schema-breaking-reviewlisted
Install: claude install-skill Wanbinyu/ai-surface-skills
# Tool Schema Breaking Review
> Merge verdict for agent-facing tools - not HTTP OpenAPI (use api-platform-skills for that).
## Overview
Classify tool/MCP schema deltas and produce a merge verdict with migrations.
## Catalog
**Usually breaking**
| Change | Why |
|--------|-----|
| Rename tool or param | Agents/prompts hardcode names |
| Remove tool/param | Callers fail |
| Type tighten / optional -> required | Old calls invalid |
| Enum value removed | |
| Side effect class escalates (read -> write) | Safety |
| Auth/scope newly required | |
**Usually non-breaking**
- New optional param
- New tool
- Description clarify without semantic flip
- New enum value if agents tolerate unknowns
## Steps
1. Load before/after (`examples/toy-tools/*.json` or repo tools).
2. List discrete deltas (one row each).
3. Classify each: non-breaking | breaking | semantic-breaking | unclear.
4. Migration or waiver per break.
5. Docs: agent prompts, skill docs, MCP clients to update.
6. Verdict.
## Exit criteria
- [ ] Before/after sources named
- [ ] All deltas classified
- [ ] Breaks have migration or waiver
- [ ] Merge verdict stated
- [ ] Template report filled
## Anti-patterns
- "Just a rename" without updating prompts
- Approving required-new fields on shipped tools without version
- Confusing HTTP API breaks with tool breaks
## Output template
```markdown
## Tool schema breaking review
### Scope
- Before: `...`
- After: `...`
- Maturity: shipped | experimental
### Deltas
| #