Bulletproof tool-calling JSON schema for AI agents

You are a tool-schema architect who thinks in failure modes first. I need a tool called [TOOL NAME] that [WHAT IT DOES]. Context: [AGENT'S OVERALL JOB — what other tools exist, what triggers this one].

Design the schema by working backwards from misuse — ask yourself 'how will the model screw this up?' for every field, then constrain it.

Produce:

1. **JSON Schema** for the tool's parameters:
- Every property gets a `description` written FOR THE MODEL: what the field is, its exact format, a concrete example value, and when to use vs. omit it.
- Use `enum` for fixed value sets, `const` for single-valued fields, `pattern` for format constraints, and `format` for standard types (date-time, uri, email).
- For any field that can be one of several shapes, use the **discriminated union pattern**: a `type` enum field plus `oneOf`/`if-then` blocks keyed to it — never a loose `object` with optional fields that change meaning.
- Mark exactly the right fields `required`. Set `additionalProperties: false` on every object level.
- Include a `_confidence` field (number, 0–1) in the schema — the model must self-report how certain it is that this tool call is the right action. If confidence < 0.7, the orchestrator can route to human review.

2. **Tool definitions** in both OpenAI function-calling format and Anthropic tool format, side by side.

3. **System-prompt snippet** (one paragraph): tell the model exactly when to call this tool vs. answer directly, what confidence threshold justifies a call, and what to do when the tool's output feeds into a downstream tool call (the **tool-calling chain** contract: specify what fields from this tool's response become input to the next tool, and instruct the model to extract — not paraphrase — them).

4. **5 edge-case test inputs**, each with:
- The user message that triggers it
- The expected tool-call JSON
- Why this case is tricky (ambiguous entity, missing optional field, boundary value, type coercion trap, or chain-input extraction)
- Whether the model should call the tool at all (include 1–2 cases where the right answer is 'don't call it')

5. **Validation checklist**: 3 things to assert in your orchestrator code before executing the call (type-check, business-logic guard, chain-input presence).