🤖 AI Engineering · AI Agents

Design tools an agent can use reliably

Shape tool names, parameters, descriptions, and error messages so the agent calls the right tool with valid arguments.

intermediate~40 minAI EngineersML EngineersLLM App Developers

Steps

1One tool = one verb-noun responsibility; split anything doing two jobs
2Write parameter descriptions that state format and units explicitly
3Return structured errors the agent can self-correct from, never stack traces
4Make tools idempotent where possible; require confirmation flags for destructive ones
5Cap list results and paginate instead of dumping unbounded payloads
6Test with adversarial phrasings that should NOT trigger the tool

Common Pitfalls

▲Overlapping tools forcing the model to guess between near-duplicates
▲Boolean success returns hiding why a call failed

Success Signals

✓Tool-call validity rate above 95%
✓Zero destructive calls without confirmation

Commands

Install with skills CLI

$ npx skills add aniruddhaadak80/skills --skill agents-tool-design

Install globally

$ npx skills add aniruddhaadak80/skills --skill agents-tool-design -g

Tags

#agents#tools#function-calling#ai-engineering

Install this skill

$ npx skills add aniruddhaadak80/skills --skill agents-tool-design -a opencode

SKILL.md

# Design tools an agent can use reliably

> Shape tool names, parameters, descriptions, and error messages so the agent calls the right tool with valid arguments.

## When to Use This Skill

Shape tool names, parameters, descriptions, and error messages so the agent calls the right tool with valid arguments.

## Steps

1. One tool = one verb-noun responsibility; split anything doing two jobs
2. Write parameter descriptions that state format and units explicitly
3. Return structured errors the agent can self-correct from, never stack traces
4. Make tools idempotent where possible; require confirmation flags for destructive ones
5. Cap list results and paginate instead of dumping unbounded payloads
6. Test with adversarial phrasings that should NOT trigger the tool

## Common Pitfalls

- Overlapping tools forcing the model to guess between near-duplicates
- Boolean success returns hiding why a call failed

View source on GitHub ↗

Bound agent autonomy with step budgets, spend caps, human gates, and checkpointing so failures stay cheap and debuggable.

🤖 AI Engineering·~45m

Open →

Structure multi-agent handoffsadvanced

Split work across specialized agents with typed handoff contracts so context survives delegation without ballooning.

🤖 AI Engineering·~50m