6 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.
| 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. |
Machine-readable version: GET /api/practices?category=clarity