Tool schema design

• You expose tools via function calling and see wrong or partial arguments.
• New tools are being added quickly and consistency is slipping.
• You need better validation and observability for compliance.

Schema quality drives reliability and debugging speed. PMs set required fields, enums, and defaults; this reduces retries and makes logs actionable. Overly strict schemas can block legitimate use cases; overly loose schemas create incidents and cost spikes.

Define concise descriptions, types, and enums; include examples. Add server-side validation and human-readable error surfaces. In 2026, maintain schema linting in CI and version schemas so agents can roll back gracefully.

After tightening the `create_meeting` schema with enum’d durations and required timezone, success rate jumped from 82% to 95% and average retries per task fell by half.

• Using free-form strings where enums or ranges are safer.
• Changing schemas without versioning, breaking older prompts.
• Missing validation, so malformed calls hit downstream APIs.