Chapter 02

Tools and tool_use

Descriptions are the selection mechanism. Schemas buy syntax, never semantics.

D2D4guide part i

2.1

The model asks; your code acts

tool_use is a request, not an execution. Nothing runs on the model's side of the line.

Two crossings per call: a request out, a result back — paired by tool_use_id.

2.2

The description is the selection mechanism

The model picks a tool by reading its description. That text is production logic, not documentation.

what + returnsthe action, and the shape of what comes back

input formatswith example values — user@domain.com, a numeric customer_id

edge casesconstraints, limits, what it refuses to do

vs alternativeswhen to use this one instead of the tool next to it — and any ordering, e.g. "call this BEFORE lookup_order"

Four things every description owes the model. The last one is what stops two tools blurring together.

2.3

tool_choice

Three settings. Two of them exist to guarantee something.

value	behaviour	reach for it when
auto	model chooses: call a tool, or answer in text	default — conversation, agentic work
any	must call some tool	you need structured output guaranteed, and several extraction tools are valid
tool, name	must call that tool	a forced first step — `extract_metadata` before enrichment

any guarantees the shape of the reply; a named tool guarantees the step. Neither is a substitute for the other.

2.4

Schemas buy syntax, never semantics

A schema gets you valid JSON with the required keys present. Whether the values are true is a separate problem.

Forces invention

{
  "category": {"type": "string"},
  "vat_number": {"type": "string"},
  "required": ["category", "vat_number",
               "severity", "confidence"]
}

No null allowed and no escape category — absent data comes back as plausible fiction.

Lets it say "don't know"

{
  "category": {"type": "string",
    "enum": ["bug","feature","docs",
             "unclear","other"]},
  "category_detail": {"type": ["string","null"]},
  "vat_number": {"type": ["string","null"]},
  "confidence": {"type": "number",
    "minimum": 0, "maximum": 1},
  "required": ["category", "severity"]
}

Nullable for maybe-absent, other + detail for outside the taxonomy, unclear for low confidence.

Required-everything is how you commission a hallucination: the model must fill the field, so it invents one.

2.5

Syntax vs semantic errors

Schemas close one of these two categories completely and the other not at all.

error	looks like	what actually fixes it
syntax	broken JSON, wrong field type, missing key	`tool_use` + JSON Schema — eliminated
semantic	totals don't add up, right value in the wrong field, invented source	validation checks, retry with the specific error, self-correction

Recall in 60 seconds

tool_use is a request — your code executes, the model never does.
The description is how the model selects a tool. Overlapping descriptions = confused tools.
Include input formats with examples, edge cases, and when to use this tool over the similar one.
Weak MCP descriptions lose to built-in Read / Grep — state the unique advantage.
any = some tool; {type: 'tool', name} = that tool, for a forced first step.
Required fields make the model fabricate. Nullable is the default for maybe-absent data.
Enums need other + a detail field, and unclear for low confidence.
Schemas kill syntax errors only. Semantic errors need validation and retry with feedback.