In a function-calling tool definition, which parts does the model actually see?

## What a tool definition is When you let a model call tools, you send a list of tool definitions alongside the conversation. The runtime serializes those definitions into the model's context, usually near the front, before the messages. The model reads them like any other text, decides whether one applies, and if so emits a structured call naming the tool and supplying arguments. Your code executes the call and returns the result into the conversation. Each definition has three parts. Field names differ slightly across providers — the schema field is called `parameters` by some and `input_schema` by others — but the trio is universal, and it is what any interviewer means when they say "write me a tool schema". ## 1. The name A short machine identifier, conventionally `snake_case`, that the model reproduces verbatim when it calls the tool. It is also the first signal the model reads. `file_claim` tells a model far more than `handler_v2` or `doAction`. Names should be verb-plus-object and should not collide in meaning with another tool in the same list. A name is cheap in tokens and disproportionately influential in selection, so it earns real thought. ## 2. The description Free natural-language text. This is where the capability's purpose, its preconditions, and the situations in which it should *not* fire live. A one-liner such as "Files a claim" is technically a description and practically a bug: it says nothing about which kind of claim, what must be true before calling, or what the caller should do instead when the request is adjacent but different. The description is the single highest-leverage field in the definition, and it is prompt, not documentation. ## 3. The parameters schema A JSON Schema object, almost always `"type": "object"` at the root, with a `properties` map and a `required` array. Each property has a type (`string`, `number`, `boolean`, `array`, `object`), optionally an `enum` to pin it to a fixed value set, and optionally its own `description`. Properties may nest: an insurance first-notice-of-loss tool might carry an `incident` object containing `occurred_at` and a nested `location`. Per-field descriptions matter as much as the top-level one, because they are where you say what format a string takes and where an argument's value should come from. Under strict or structured-output modes the schema stops being advisory and becomes a hard constraint on decoding, so the emitted JSON is guaranteed to match its shape. Without such a mode the schema is strong guidance the model usually but not always honours, which is why your handler still validates. ## What the model never sees This is the part candidates get wrong. The model does not see: - your function body or its language-level types; - the docstring in your source (unless your framework explicitly copies it into the `description` field — many do, which is exactly why an unedited docstring often becomes a bad tool description); - the database the tool writes to, the permissions it holds, or the blast radius of calling it; - comments, tests, or the wiki page explaining the workflow. Everything the model needs in order to decide *whether* and *how* to call must be inside the three fields. A tool that is dangerous to call twice must say so in its description; the model has no other way to know. ## Why this framing matters in practice Because the definition is prompt, the standard debugging move for tool-use failures is to read the definition the way the model reads it — as text, with no surrounding knowledge. Print the serialized definitions and ask: from this text alone, is it unambiguous what this does, when it applies, and what every argument means? Most wrong-tool and wrong-argument failures resolve at that step, before anyone touches the agent loop. The corollary is cost. Because definitions are context, they are paid for on every request that carries them, and they compete for attention with the actual conversation. Definitions are therefore written with the economy of a prompt, not the completeness of API reference documentation: decision-relevant information in, encyclopaedic detail out.