Why examples belong inside the description
Prose alone often leaves edge cases ambiguous -- what exactly counts as a valid input, what format is expected, what a borderline case should do. A concrete example call embedded directly in the tool description resolves that ambiguity far more efficiently than more explanatory prose, because it shows rather than describes.
What to include
- At least one realistic example call with representative argument values.
- What that example call would return, in the actual shape the tool returns (not a paraphrase).
- Where useful, one example of a call that should NOT be made -- the boundary case that most often gets confused with a different tool.
This pairs directly with subagentprompts.com's own general guidance on providing examples in prompts (see its catalog for the broader, non-tool-specific version of this technique) -- the version on this site is scoped specifically to what goes inside a tool's own description field, not a user-facing prompt.
General tool-use prompt-engineering guidance; cross-referenced against subagentprompts.com rather than duplicated. See the examples category in the live catalog.