Agent Tool Description Writer

Write a tool description for an AI agent's function-calling schema. The description is what the model reads to decide *when* to call this tool, so it needs to be precise about triggering conditions, not just what the function does technically.

FUNCTION NAME: [e.g. "get_order_status"]
WHAT IT DOES (technically): [e.g. "queries the orders table by order ID and returns shipping status, carrier, and estimated delivery date"]
PARAMETERS: [LIST EACH PARAMETER AND ITS TYPE]

WHEN IT SHOULD BE CALLED: [describe the user intent that should trigger this, e.g. "when the user asks about the status, location, or delivery date of an existing order"]
WHEN IT SHOULD NOT BE CALLED: [common near-miss cases, e.g. "don't call this for a question about placing a new order, or about return/refund policy"]

Other tools available to this agent, for disambiguation: [LIST OTHER TOOL NAMES AND ONE-LINE PURPOSES, if any]

Write:
1. The `description` field text (2-3 sentences, written for the model to read, not for a human reading documentation)
2. A short note on any parameter that's easy to get wrong (ambiguous format, easy to confuse with a similar parameter on another tool)
3. One example user message that SHOULD trigger this tool, and one similar-sounding message that SHOULD NOT

How to use

Use this whenever you're adding or debugging a tool in an agent's toolset, especially when the agent has several tools that could plausibly overlap (a "get order status" and a "get shipment tracking" tool, for instance). Most tool-calling reliability problems trace back to a vague or overlapping description, not a model limitation. See function calling for the underlying concept if you're new to this.

Variables

• [e.g. "get_order_status"] — the exact function name as it appears in your schema
• [WHAT IT DOES (technically)] — the implementation-level description
• [LIST EACH PARAMETER...] — every parameter, including ones that seem obvious
• [WHEN IT SHOULD BE CALLED] / [WHEN IT SHOULD NOT BE CALLED] — this is the part most people skip, and it's the part that actually fixes misfires
• [LIST OTHER TOOL NAMES...] — critical if you have tools with any conceptual overlap

Tips

• The "should not be called" case is doing most of the work here. A model rarely fails to call an obviously-relevant tool; it fails by calling the wrong tool among several plausible ones, or calling a tool when it should have asked a clarifying question instead.
• If you have two tools that are genuinely hard to disambiguate even for a human reading the descriptions, that's a sign to merge them into one tool with a parameter, rather than write an ever more elaborate description trying to separate them.
• Re-run this prompt whenever you add a new tool to an existing agent — a description that worked fine alone can become ambiguous once a new, similar tool exists alongside it.