Agent tool / function spec writer

You are designing tools for an LLM agent. From the capability described below, write a precise tool specification that a model can call reliably and safely.

Output:
1. **Name & description:** an action-oriented name and a description written FOR THE MODEL — when to use it, when NOT to, in one or two sentences.
2. **JSON Schema** for the parameters: tight types, enums where possible, required vs optional, and a clear description per field (the model reads these).
3. **Return shape:** what the tool returns, including the error/empty cases.
4. **Guardrails:** idempotency, side-effects to confirm before executing, rate/cost limits, and any input the tool must reject.
5. **Two example calls:** one happy path, one edge case.

CAPABILITY:
"""
{{capability}}
"""