Field Descriptions That Guide the Model
Document each field so the AI fills it correctly.
Field Descriptions That Guide the Model is a free MCP Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MCP Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
The Model Reads Your Fields
Each field's name and description are shown to the AI. A good description is your chance to tell the model exactly what to put there.
Add a Description
Pass description to Field to attach a human sentence that travels with the schema all the way to the client.
city: str = Field(description="City name, e.g. Paris")Show, Don't Just Tell
Concrete examples inside a description, like a sample date or format, guide the model far better than abstract wording.
date: str = Field(description="ISO date, e.g. 2026-01-31")State the Units
If a number has units, say so. Telling the model temperature is in Celsius prevents quietly wrong Fahrenheit values.
Clarify Ambiguous Names
A field called id is vague. A description like the order's unique ID removes guesswork about which id you mean.
Spell Out the Format
When a string follows a shape, describe it. Saying phone in E.164 like plus and digits keeps the format consistent.
Note What's Optional
For optional fields, mention when to skip them. Telling the model leave blank to use the default reduces needless values.
Keep It Tight
One clear sentence beats a paragraph. A focused description is easier for the model to follow and cheaper in tokens.
Describe the Model Too
A short docstring on the model class describes the whole input, giving the AI useful context above the individual fields.
class Weather(BaseModel):
"""Inputs for a weather lookup."""
city: strDescriptions Power the Schema
Every description lands in the JSON schema the client sends to the model, so writing them well directly shapes tool calls.
Iterate on Wording
If the model keeps filling a field wrong, the fix is usually the description: sharpen the words until calls come out right.
Quick Check
Where does a Field description end up, and why does it matter?
Recap
Write tight field descriptions with examples, units, and formats. They reach the model in the schema and steer it toward correct calls. ✅
Frequently asked questions
Is the “Field Descriptions That Guide the Model” lesson free?
Yes — the full text of “Field Descriptions That Guide the Model” is free to read here on the web, and the MCP Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MCP Academy course, upgrade to CoddyKit PRO.
What will I learn in “Field Descriptions That Guide the Model”?
Document each field so the AI fills it correctly. You practise MCP Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start MCP Academy?
No prior experience is required. MCP Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Field Descriptions That Guide the Model” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this MCP Academy lesson?
Yes. Every MCP Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Why Schemas Beat Loose Args
- Model Inputs with Pydantic
- Constraints, Defaults & Enums
- Field Descriptions That Guide the Model