Tool Specification for a Legal AI Agent

Design an agent tool definition. The tool will be called by a model that cannot see the implementation — the description and schema are all it has.

What the tool does: [description] Target system: [API / database / filesystem] Is the action reversible: [yes / no]

Produce:

1. Tool name — verb_noun, explicit. Avoid generic names like process or handle.
2. Description — two to four lines answering: what it does, when to use it, and explicitly when not to. Most agent failures are wrong tool selection, not wrong parameters.
3. Parameter schema — JSON Schema with type, description, and required for every field. Every parameter description must include an example. Use enum instead of free-form strings wherever possible.
4. Return schema — what comes back on success, including the fields the model needs to decide its next step.
5. Errors — every error state with a message the model can act on. "Error 500" is useless; "no client found with that id — verify the id or search by name" enables recovery.
6. Permissions and approval — if the action is irreversible, writes data, sends externally, or costs money: require explicit approval. Specify what is shown to the approver before execution.
7. Limits — rate limit, max size, timeout, and how many consecutive calls are permitted.
8. Three valid call examples and two invalid ones with the error each returns.