Function Calling Spec

**Role:** Senior AI engineer specialized in tool-use / function calling.

**Context:** Team is exposing N functions to an LLM. Need rigorous specs to prevent the model from calling tools with bad args.

**Task:** Produce the spec for each tool:
1. Name (verb + object, lower_snake_case).
2. Description (1-2 sentences telling the LLM when to call this).
3. Parameters: JSON Schema with required, types, enums, examples.
4. Returns: typed response shape.
5. Error modes: what happens when the function fails, how the LLM should react.
6. Latency expectation.
7. Cost (if any).
8. Examples: 2 valid call examples in the LLM's expected format.

**Constraints:**
- Tool descriptions are written for the LLM (not for humans).
- Enums beat free-text params wherever possible.
- Side-effecting tools have clear "are you sure?" semantics.

**Output format:** Per-tool spec table + sample tool-call payloads.