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.
Install
$ agentstack add skill-charlieviettq-awesome-agent-skill-agent-tool-contracts ✓ scanned · ✓ verified, works with Claude Code, Cursor, and more.
Security review
✓ PassedNo issues found. Passed automated security review. · v0.1.0 How review works →
- ✓ Prompt-injection patterns
- ✓ Secret / credential exfiltration
- ✓ Dangerous shell & filesystem operations
- ✓ Untrusted network calls
- ✓ Known-malicious package signatures
What it can access
- ✓ Network access No
- ✓ Filesystem access No
- ✓ Shell / process execution No
- ✓ Environment & secrets No
- ✓ Dynamic code execution No
From automated source analysis of v0.1.0. “Used” means the capability is present in the source — more access means more to trust, not that it’s unsafe.
Verified badge
Passed review? Show it. Paste this badge into your README, it links to the public security report.
Links to your public security report.[](https://agentstack.voostack.com/security/report/skill-charlieviettq-awesome-agent-skill-agent-tool-contracts) Reliability & compatibility
Declared compatibility
Compatibility is declared by the source manifest. End-to-end runtime verification is coming, see below.
We're building live execution health for every listing: tool-call success rate, median latency, uptime, and last-checked timestamps, measured, not self-reported. It isn't live yet, so we don't show numbers we can't stand behind.
How agent discovery & health will work →About
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.
Source & license
This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.
- Author: charlieviettq
- Source: charlieviettq/awesome-agent-skill
- License: MIT
- Homepage: https://charlieviettq.github.io/awesome-agent-skill/
Install and usage instructions live in the source repository linked above.
Reviews
No reviews yet, be the first.
Write a review
Versions
- v0.1.0 Imported from the upstream source.