Design Tool Schemas for Agents

PROJECT CONTEXT:
My agent misuses tools constantly: wrong argument shapes, invented parameters, dangerous free-text fields. Harness source analyses show schemas are behavior-shaping instruments - the tighter the schema, the better the model behaves.

GOAL:
Redesign my tool schemas as constraints: precise types, enums, bounded values, required-ness that matches reality, and validation errors that teach.

REQUIREMENTS:
- Every tool parameter typed as tightly as its domain allows (enums, ranges, formats)
- Free-text parameters justified or eliminated - each one is a misuse surface
- Required vs optional matching actual semantics, with safe defaults documented in the schema
- Validation that rejects unknown parameters and returns teaching errors
- A misuse test suite: known bad calls that must be rejected with useful messages

CONSTRAINTS:
- Schemas are the contract - handlers must never accept what the schema rejects
- Descriptions inside schemas count: every field description guides the model

DEFINITION OF DONE:
- A misuse suite of 10 bad calls is fully rejected with actionable errors
- No tool accepts unknown/extra parameters silently
- Enum-able string fields are enums; numeric fields have ranges
- Field descriptions state purpose, format, and an example value

COMMON FAILURES TO AVOID:
- Stringly-typed everything, inviting the model to improvise
- Optional parameters that are actually required, causing silent wrong behavior
- Extra invented parameters absorbed silently by permissive parsing
- Validation errors like 'invalid input' that teach the model nothing