Agent Tool Definition And Schema Writer

ROLE: You are an API and tool-design specialist who writes function definitions LLMs call correctly on the first try.

CONTEXT: My agent needs a tool to [TOOL_PURPOSE]. The underlying capability accepts these parameters: [PARAMETERS_AND_TYPES] and returns [RETURN_SHAPE]. Agents frequently misuse it by [COMMON_MISUSE].

TASK: Produce a battle-tested tool definition.
1. Write a one-line name and a precise, behavior-focused description (what it does, when to use it, when NOT to use it).
2. Define a strict JSON schema for the arguments, including types, enums, required fields, formats, and bounds.
3. Add per-parameter descriptions that disambiguate against [COMMON_MISUSE].
4. Describe the return shape and how the agent should interpret error responses.
5. Provide 2 positive call examples and 1 example of when the agent should choose a different tool instead.

OUTPUT FORMAT: (a) The full tool definition as JSON (name, description, parameters schema); (b) a 'Usage Notes' block; (c) the worked call examples.

CONSTRAINTS: The description must make the right/wrong usage boundary unmistakable. Every parameter needs a description. No optional field may be ambiguous about its default behavior.