12 practices, live from D1

Practices

Prompt-engineering best practices specific to tool/function description writing, grouped by category unless filtered. For general prompting techniques (not tool-description-specific), see subagentprompts.com.

all categories clarity structure examples scoping naming

clarity

practice	description
Avoid unexplained jargon or abbreviations in descriptions	A tool description is read by the model with no additional context beyond what is written -- internal codenames, uncommon abbreviations, or jargon specific to one team should be spelled out or avoided, the same way a new team member would need it explained.
Keep descriptions concise, but not at the expense of completeness	Long descriptions cost context and can dilute the signal of what matters most; the goal is not the shortest possible description, but the shortest description that still unambiguously conveys behavior, required parameters, and edge cases. Cutting real information to save space is a false economy.
Describe what the tool returns, not just what it does	A tool description that only explains the action (e.g. "searches for X") without saying what shape the result takes leaves the model unable to reason correctly about how to use the output in a following step.
Document known edge cases and failure modes in the description	If a tool has a known gotcha -- a field that looks like one thing but means another, a case where it silently returns an empty result rather than erroring -- stating that gotcha directly in the description saves the model (and a human debugging its calls) from rediscovering it the hard way.
Write extremely detailed, unambiguous descriptions	A tool description should explain exactly what the tool does, what each parameter means, what the tool returns, and any important caveats -- err on the side of more detail rather than less, since the model has no other context about the tool beyond its name, description, and schema.
Be explicit about which parameters are required vs. optional, and what defaults apply	If a parameter is optional, the description (or schema) should say so and state what happens when it is omitted -- silently assumed defaults are a common source of wrong tool calls.

structure

practice	description
Use clear structure or delimiters inside a long description	When a tool description needs to cover several distinct concerns -- what it does, when to use it, when not to, an example -- breaking it into clearly labeled or delimited sections (short paragraphs, a labeled "Example:" sentence, explicit "Do NOT use this for..." sentence) is easier for the model to parse reliably than one dense paragraph.

examples

practice	description
Include example usage directly in the description	Concrete input/output examples embedded in a tool's description reduce ambiguity far more efficiently than more prose -- showing the model one or two realistic calls (and, where useful, one call that should NOT be made) often resolves edge cases prose alone leaves open.

scoping

practice	description
Avoid ambiguous, overlapping tool sets	If two tools could plausibly both apply to the same request, the model has to guess -- and guesses are where tool-use errors come from. Where possible, consolidate near-duplicate tools into one tool with a parameter, or make the boundary between them explicit in both descriptions.
Explain when to use the tool -- and when not to	Beyond describing what a tool does, a good description tells the model the situations that should trigger it, and explicitly calls out situations where a similar-looking tool should be used instead, to prevent the model from picking the wrong one of several overlapping tools.
Prefer one tool, one clear responsibility	A tool that tries to do many unrelated things behind a single description and a large branching parameter set is harder for the model to invoke correctly than several smaller, single-purpose tools with tight, specific descriptions.

naming

practice	description
Give parameters descriptive, self-explanatory names	Parameter names are part of the model's only signal for what a field means -- prefer a clear, specific name (and a short description on the parameter itself, not just the top-level tool description) over a short but ambiguous one.