# Agent Tool Contracts

> Design agent tools and CLI surfaces—schemas, naming, errors, idempotency, and discoverability for LLM callers. Use when defining tools for agents, SDKs, or AI-native CLIs.

- Skill: `charlieviettq/agent-tool-contracts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add charlieviettq/agent-tool-contracts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/charlieviettq/agent-tool-contracts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: charlieviettq (https://skillmd.com/u/charlieviettq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/charlieviettq/agent-tool-contracts

---


# 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

| 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)

- `--json` for machine output; stable field names.
- Exit codes: 0 success, non-zero with stderr message.
- `--dry-run` for 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.