Domain 2 · Tool Design & MCP

Anatomy of a tool

A tool definition is the contract between Claude and your code. The single biggest lever on whether the model uses a tool correctly isn't the code behind it — it's the description and the JSON schema. Toggle a definition from sloppy to sharp and watch the model's behaviour flip.

namedescription input_schemarequired vs nullable prompt-as-API

Explain like I'm 10

A tool is a button you give Claude to press. But Claude can't see the button — it can only read the label you wrote on it. If the label says "do stuff," Claude presses it at the wrong times. If it says "use this to look up a customer's order by their order number; returns status and ship date," Claude presses it perfectly. Writing great labels is the job.

The four fields

Every tool has the same skeleton. The model never sees your implementation — it sees only these fields and reasons entirely from them:

Field	What the model does with it
`name`	A short handle it emits when calling. Make it descriptive (`get_order_status`, not `tool3`).
`description`	The most important field. What it does, when to use it, when not to, side effects, units, and what it returns. Treat it like docs for a junior dev who can't ask questions.
`input_schema`	A JSON Schema of the parameters: types, which are `required`, allowed enums, formats, and per-field descriptions.
(your code)	Runs when the model emits `tool_use`. The model never sees it — only the `tool_result` you return.

Sloppy vs sharp — flip the switch

Required vs nullable — the field that trips people

A parameter the model must supply goes in required. But what about a field that's optional or sometimes genuinely unknown? Don't just leave it out — model it explicitly. A field that can be absent should be typed to allow null ("type": ["string", "null"]) and its description should say when null is correct. Otherwise the model invents a value to fill the gap — the root cause of hallucinated arguments in extraction tasks (Domain 4).

Exam trap: when a tool is misused, the fix is almost always "improve the description / schema," not "add more tools" or "switch models." Distractors love suggesting a heavier hammer. Also: marking everything required forces the model to fabricate values it doesn't have — make truly-optional fields nullable and say so.

Takeaways: a tool = name + description + input_schema (the model never sees your code). The description is the API — say what it does, when to use it, when not to, side effects, and return shape. In the schema, mark only genuinely-mandatory fields required, and make optional/unknown fields nullable with a description of when null applies. Bad tool behaviour → fix the words, not the model.

Curated companion: Anthropic — Tool use · Writing tools for agents.