agent-tool-design-playbook

Instructions

Use this skill when you are designing or refining tools for an AI agent (e.g., a coding agent) and want to reduce confusion while increasing capability.

1) Start from the agent’s perspective (“see like an agent”)

• Assume the agent’s core loop is: read tool outputs → update its plan → choose the next tool call.
• Evaluate whether your tool outputs are legible and actionable for the model (not just for humans).

2) Keep a high bar for adding new tools

• Every new tool increases the set of options the agent must consider.
• Prefer improving an existing primitive or documentation before introducing a brand-new tool.

3) Match the tool interface to the model’s current capabilities

• Revisit earlier design assumptions as model capability changes.
• If a tool becomes a bottleneck because it is too restrictive, replace it with a more expressive primitive.