Agent Tool Description Writer (MCP / Function Calling)

Write the tool definition(s) for the capability described below, targeting {{target}} (e.g. MCP server, OpenAI function calling, Claude tool use). The audience is not a human reading docs — it is a model deciding, mid-conversation, whether and how to call this tool. Every ambiguity in your definition becomes a wrong call at runtime. For each tool: ## Name `verb_object` form, specific: `search_invoices`, not `invoices` or `handle_invoice_stuff`. If there are sibling tools, names must make the boundary obvious (`search_invoices` returns summaries and ids; `get_invoice` takes one id, returns full detail). ## Description — must answer four questions 1. **What it does** — one sentence, concrete, including what it returns. 2. **When to use it** — the trigger situations, phrased from the model's perspective ("when the user asks about a specific past payment..."). 3. **When NOT to use it** — the adjacent situations that belong to a different tool or no tool. This is the highest-value section and the one everyone omits; overlapping tools without NOT-clauses cause coin-flip tool choice. 4. **Cost/side-effect class** — read-only vs. mutating vs. irreversible; slow vs. fast; whether results can be stale. Mutating and irreversible tools should tell the model to confirm with the user first. ## Parameters For every parameter: type, required/optional, exact format with a valid example inline (`"date: string, ISO 8601 date, e.g. 2026-06-30"`), allowed values for enums, defaults, and units. If two parameters interact ("either query or customer_id, not both"), state it in BOTH parameter docs and the description. Design out the ambiguity: prefer enums over free strings, separate fields over composite formats the model must assemble. ## Returns & errors Describe the success shape briefly, then each distinct error the model can receive and what it should DO about it: "NOT_FOUND: the id does not exist — do not retry; re-check the id with the user." Distinguish retryable from non-retryable explicitly. State idempotency: safe to call twice, or not? ## Output Deliver: (1) the definition(s) as valid JSON schema for {{target}}, (2) a paragraph of design notes — what you deliberately constrained and any capability you split into two tools or merged, and why, (3) three example calls: a clearly-correct call, a clearly-wrong call the description now prevents, and an edge case with the expected model behavior. Capability to expose: {{capability_description}}