agent-tool-design

name	agent-tool-design
description	Read before creating, reviewing, or refining a tool exposed to an agent.
last-changed	2026-08-22

For a Pi tool, also read references/pi.md.

Start from what the agent knows

• Prefer canonical tool names and argument shapes already present in the target model's training.
• Treat a familiar tool schema as a runtime binding, not a tutorial. State only this implementation's meaningful deviations.
• Give an unfamiliar capability an obvious action name and familiar inputs. The agent should predict the call from the name and schema.
• When unsure, present the bare contract to the target model first. Add only the fact it could not infer correctly.

Fix model choices at the model boundary

• When the implementation supports the right behaviour but the model selects the wrong action or argument, treat it as a model-facing contract failure first.
• Fix the name, default, argument description, or prompt guidance before adding runtime policy, heuristics, or extra state.
• Describe choices in terms of user intent, not only mechanics. “False returns immediately” explains execution. “Use false only while continuing other work” changes the model's decision.
• Test paired natural requests that differ only at the decision boundary. Confirm the model chooses correctly before changing implementation.

Keep the decision surface small

• Give one tool one coherent job.
• Expose only decisions the caller must make. Keep providers, models, prompts, commands, internal modes, formatting, and policy inside the implementation unless the agent genuinely chooses them.
• Require only the minimum valid input. Add an optional field only when omission has a useful deterministic meaning.