Return a Typed Result Object
Hand back a Pydantic model as structured output.
Return a Typed Result Object is a free MCP Academy lesson on CoddyKit — lesson 2 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.
Goal: A Typed Result
Now you will hand back real data, not just a string. The cleanest way in the Python SDK is to return a Pydantic model from your tool.
Why Pydantic
A Pydantic model defines named, typed fields. FastMCP reads that model to build the output shape and validates the data for you. 🧱
Define the Model
Subclass BaseModel and list your fields with type hints. This class becomes the contract for what your tool returns.
from pydantic import BaseModel
class Weather(BaseModel):
temp_c: float
condition: strAnnotate the Return Type
Set the tool function return annotation to your model. FastMCP uses that annotation to know the output is structured, not plain text.
@mcp.tool()
def get_weather(city: str) -> Weather:
...Return an Instance
Inside the tool, build and return an instance of the model with real values. The SDK serializes it to structured content.
def get_weather(city: str) -> Weather:
return Weather(temp_c=21.0, condition="sunny")Validation Comes Free
If you pass a wrong type, Pydantic raises an error before the result ships. Bad data is caught early, inside your server.
Fields Become the Schema
Each model field turns into a key in the output. The client sees temp_c and condition as a clean, named structure it can read.
Text Summary Still Included
FastMCP also ships a text version of the object so the model can read it. You get a summary and structured data without extra work.
Nested Models Work
A field can itself be another Pydantic model. This lets you return nested objects, like a location inside a weather report.
class Report(BaseModel):
place: Weather
updated: strLists of Objects
Return a list of models for many records at once, such as several forecasts. Each item keeps its typed shape in the result.
def forecast(city: str) -> list[Weather]:
return [Weather(temp_c=21, condition="sunny")]Keep Models Small
Only include fields the consumer truly needs. A lean model is easier to read, cheaper in tokens, and simpler to evolve later.
Quick Check
What turns a Pydantic model into a tool output?
Recap: Typed Results
You returned data as a Pydantic model: define fields, annotate the return type, return an instance. Validation and a text summary come included. ✅
Frequently asked questions
Is the “Return a Typed Result Object” lesson free?
Yes — the full text of “Return a Typed Result Object” 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 “Return a Typed Result Object”?
Hand back a Pydantic model as structured output. 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 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Return a Typed Result Object” 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
- Text vs Structured Content
- Return a Typed Result Object
- Output Schemas for Clients
- Return Images & Binary Blobs