charlieviettq Agent tool contracts
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.