Agent tool contracts
SkillMediaAdd this skill and your AI can help you design tools and command-line interfaces that AI callers use reliably. It covers the details that make tools work well for AI: clear schemas, sensible naming, consistent error handling, actions that are safe to repeat, and making tools easy for AI to discover. It is intended for defining tools for agents, SDKs, or AI-native command lines.
Available today. Use it from your connected AI after setup.
No other account needed.
After adding it, describe the tool, SDK, or command line you are building and ask your AI to draft its schemas, naming, and error handling.
Then ask your AI: use the Agent tool contracts skill
What your AI can do with it
- Design tool schemas that AI callers can follow reliably
- Choose clear names so AI callers can find and use tools
- Define consistent error responses for failed calls
- Make tool actions safe to repeat without unwanted side effects
- Structure commands for AI-native command-line interfaces
- Define tools for SDKs
What this skill tells your AI
The instructions your AI receives, as published by charlieviettq/awesome-agent-skill in .claude/skills/agent-tool-contracts/SKILL.md and read by ahel’s review.
Tool design rules
- Verb-noun names —
search_issues,create_draft_pr(notdoStuff). - Minimal parameters — fewer required fields; sensible defaults in description.
- Explicit side effects — "Creates...", "Deletes...", "Read-only" in description.
- Bounded output — paginate or truncate; return summary + pointer for large data.
- Stable errors —
{ "code": "NOT_FOUND", "message": "..." }.
Schema quality
- Types and enums for categorical fields.
- Examples in parameter descriptions.
- Reject unknown enums at validation layer.
Idempotency and safety
| Operation | Pattern |
|---|---|
| Read | Safe to retry |
| Create | Idempotency key or dedupe by natural key |
| Update | Version or ETag when concurrent edits possible |
| Delete | Soft delete or two-step confirm in description |
AI-native CLI (when applicable)
--jsonfor machine output; stable field names.- Exit codes: 0 success, non-zero with stderr message.
--dry-runfor mutating commands.
Review checklist
- Description tells the model when NOT to use the tool
- Errors actionable (what to fix, not internal codes only)
- No overlapping tools with ambiguous choice
- Integration test with representative agent prompts
Related
mcp-builder for MCP-specific packaging; agent-evaluation for measuring tool accuracy.
Signals
- GitHub stars
- 26
- Forks
- 9
- Last commit
- Jul 2026
Advanced
- Catalog kind
- skill
- Gateway key
agent-tool-contracts- Source
- github.com/charlieviettq/awesome-agent-skill