agent-tool-design

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.
• Before changing a tool contract for external behaviour, exercise the actual route. Accepted fields and public docs do not prove the route honours them. Separate body controls from prompt-mediated behaviour.
• 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

Prefer a stable help-backed or deferred contract for unfamiliar multi-action tools or tools whose accepted arguments vary with state. Keep capability discovery visible. Disclose current arguments and tool-specific guidance on demand. Where supported, use a string input with a help operation. Preserve familiar native contracts and simple self-explanatory schemas instead of wrapping them for uniformity. If harness or API constraints require an upfront schema, keep it minimal. For prompt or tool-vector changes, load an applicable prompt-caching skill.