Claude tool schema design: small actions, loud errors

A tool schema is the JSON contract Claude sees for a side effect: name, description, required fields, types. It is not documentation for humans. It is the API of your agent. Weak schemas produce retries, invented ids and writes you cannot explain.

Good schemas look boring. That is the point.

Design rules we use on audits

1. One job per tool. Split "search" from "update."
2. Required fields for anything the system of record requires.
3. Enums for statuses you actually allow.
4. Error strings a model can recover from: what was wrong, what to try.
5. No catch-all metadata blob that bypasses validation.

These rules apply whether you speak MCP or in-process tools.

Test the schema, not the vibe

Golden cases should include malformed input, missing records and permission denials. If the only cases are happy paths, you will ship a demo. Wire those cases into eval gates.

Writes need a second lock

Even a perfect schema should not auto-commit a high-impact mutation. Combine with human-in-the-loop on the tools that move money, messages or medical data.

If traces show Claude calling the same tool five times with slightly different JSON, stop tuning the prompt and fix the contract. That is one of the first things a Claude Expert Audit will rank.