After this topic
You will treat the tool description and Zod fields as the entire interface the model has. You will write names, when-to-use sentences, and .describe() examples as if you were documenting an API for a very fast intern who cannot see your TypeScript.
The model cannot see your code
Name, description, and inputSchema are public to the model. execute is invisible until after it picks a tool.
The model does not read your TypeScript. It reads a name, a description, and a JSON schema derived from Zod. That is the entire interface. If the description is “search” and the field is q, the model will guess — and guessing is how you get { q: "weather" } instead of { city: "Berlin" }.
Name the action (getWeather, searchDocs, createTicket). Say when to use it in description. Put an example in the field .describe(). The system prompt can mention tools; it should not be the only place the contract lives.
This is structured output, aimed at a function call instead of a profile object. Same idea: a schema is a constraint. A vague name is a suggestion.
What works
Compare this to a tool named search with no field descriptions. The model has to invent argument names. You then either reject the call or run execute with the wrong shape. Both are worse than a sentence of description.
execute is invisible to the model. It runs on your server after validation. Side effects (charges, emails, deletes) are your responsibility. If the action cannot be undone, pause for a human — the next topic.
- Name tools after the action: getWeather, searchDocs, createTicket
- Describe when to use the tool in description, not only in the system prompt
- Use .describe() on every Zod field the model must fill — with an example
- Keep the tool list short. Ten overlapping tools is how you get the wrong one.
Files
- 01
description is the routing hint
The model chooses this tool because the description matches “weather in Berlin”, not because you named the file weather.ts.
- 02
.describe() on every field
city vs location vs q — the model only knows what you write here. Examples in the description reduce invalid args.
- 03
execute is invisible to the model
It runs on your server after the call is validated. Keep side effects (charges, emails) behind extra approval if needed.
Trade-offs
A long description costs tokens on every step — the tool list is part of the prompt. Be specific, not encyclopedic.
Overlapping tools (“search” and “lookup” and “find”) make the model dither. Prefer fewer, sharper tools over a kitchen sink.
If a tool keeps being called with garbage, log the raw arguments. Then fix the schema, not the system prompt first.
Related patterns
Docs
Official API reference for this chapter.
Common questions
- What is “Tool schemas that models follow”?
- The model reads tool descriptions and Zod schemas to decide when and how to call your functions.
- What will I be able to do after this lesson?
- You will treat the tool description and Zod fields as the entire interface the model has. You will write names, when-to-use sentences, and .describe() examples as if you were documenting an API for a very fast intern who cannot see your TypeScript.
- How long does this lesson take?
- About 16 minutes of reading. It is a free chapter in the AI SDK Patterns TypeScript course.
- When should I not use this?
- A long description costs tokens on every step — the tool list is part of the prompt. Be specific, not encyclopedic.
Written by Akash Panchal·Updated August 29, 2026