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.
• 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.
• Prefer conventional names such as cmd, path, query, cwd, and message. Use a small enum when the choice is genuinely closed.
• If a field needs a paragraph to make sense, remove it, rename it, or reconsider the tool boundary.

Let the schema speak

• Do not narrate types, requiredness, optionality, enums, defaults, or limits already encoded by the schema.
• Omit a field description when its name is sufficient.
• Write necessary descriptions as compact payload fragments: Cwd, Wait ms, Recent days, Truncate.
• Omit cosmetic terminal full stops, backticks, Markdown, examples, and grammatical padding. Preserve punctuation and formatting only when they carry literal syntax or prevent ambiguity.
• Keep safe compatibility aliases inside argument preparation rather than advertising them in the schema.