Tool schemas as API design for assistants

Assistants fail in predictable ways when tool schemas drift from the backend implementation. We require teams to generate tool definitions from the same OpenAPI source as their REST handlers, then add a compatibility test that calls the tool with golden payloads before prompts ship.

The second week introduces streaming budgets: partial JSON tokens arriving out of order stress frontends unless you define a rendering contract. We show two UX patterns—skeleton loaders keyed by tool name, and conservative fallbacks when parsing fails—and discuss when honesty beats spinner theater.

Finally, we document deprecation: when a tool is retired, prompts that reference it must carry version tags so rollback does not resurrect unsafe combinations. Students leave with a checklist their PM can scan without reading Python, which is how you keep assistants maintainable after the original author switches teams.