Agent tool contracts

Tool design rules

1. Verb-noun names — search_issues, create_draft_pr (not doStuff).
2. Minimal parameters — fewer required fields; sensible defaults in description.
3. Explicit side effects — "Creates...", "Deletes...", "Read-only" in description.
4. Bounded output — paginate or truncate; return summary + pointer for large data.
5. 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