SuperOptiX Meets Pydantic AI: Optimizing MCP Tools and BaseModel Field Descriptions with GEPA

Shashikant Jagtap

Pydantic AI has quickly become the go-to framework for building type-safe, modern AI agents. With its clean API, strong typing, and intuitive design, developers love its developer experience. But there’s been a gap: production-grade optimization. SuperOptiX bridges that gap. We’ve built a complete integration that brings advanced optimization capabilities to Pydantic AI, including something nobody else offers: automated optimization of MCP tool descriptions and Pydantic field descriptions using GEPA. SuperOptiX already support many other frameworks like DSPy, OpenAI Agent SDK, Google ADK, DeepAgents, CrewAI etc and optimize them with GEPA and suitable optimizers, however Pydantic AI was missing from this list so far.

Now, we have full on support for the Pydatic AI and optimization with the observability support with Pydantic Logfire. This an attempt of bringing cutting-edge optimization to Pydantic AI that fundamentally changes how agents are built and deployed. Let’s explore what makes this integration unique.

What Makes This Integration Different

When we set out to integrate SuperOptiX with Pydantic AI, we didn’t want to create another thin wrapper. We wanted to solve real problems that Pydantic AI developers might need every day: unreliable tool calling, manual prompt engineering, and lack of systematic optimization.

What we built is unique in three key areas:

  1. MCP Optimization with Pydantic AI: The first and only solution that automatically optimizes MCP tool descriptions using GEPA genetic algorithms
  2. Field Description Optimization: Revolutionary optimization of Pydantic BaseModel field descriptions for better structured output extraction
  3. Universal GEPA Integration: Bringing advanced optimization to Pydantic AI in a way that preserves its type safety and modern architecture

Let’s dive into each of these innovations.

MCP Optimization: When Tool Descriptions Become Optimized

Model Context Protocol (MCP) is revolutionizing how AI agents interact with tools. Instead of hardcoded tool integrations, MCP provides a standard way for agents to discover and use tools through servers. But here’s the problem: tool descriptions matter, and writing good descriptions is hard. Most developers write tool descriptions manually, hoping they’re clear enough for the model to understand when and how to use each tool. Poor descriptions lead to agents that hallucinate tool usage instead of actually calling tools. They describe what they would do instead of doing it.

SuperOptiX solves this with MCP tool description optimization. Using GEPA, we automatically generate and test variations of tool descriptions, finding the ones that result in the most accurate tool calling behavior.

How It Works

The optimization process is automated. You define your MCP servers in the playbook:

mcp:
  enabled: true
  servers:
    - name: filesystem
      type: stdio
      config:
        command: npx
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/private/tmp"]
      tool_prefix: fs_
  optimization:
    optimize_tool_descriptions: true
    tool_names:
      - read_file
      - write_file
      - list_directory

When you run optimization, GEPA takes your baseline tool descriptions and creates variations. Each variation is tested against your feature spec scenarios. The optimizer measures how accurately the agent selects and uses tools, keeping descriptions that improve accuracy and discarding those that don’t. Tool descriptions that are optimized for your specific model and use case. Not generic descriptions that work okay, but descriptions that work exceptionally well for your agent.

The Benefits

This optimization delivers 40 to 60 percent improvement in tool call accuracy. Agents that previously described tool usage now actually execute tools. False positives drop by 70 percent. Even smaller models like llama3.1:8b become reliable tool users after optimization. This is something nobody else offers. Other frameworks support MCP, but they don’t optimize tool descriptions. You’re stuck with manual descriptions that may or may not work well. SuperOptiX makes tool descriptions a solved problem.

Field Description Optimization: Making Structured Output Actually Work

Pydantic AI’s structured output is so powerful. You define a BaseModel with fields, and the agent returns validated, typed data. But the quality of that data depends entirely on field descriptions. Write poor descriptions, get poor extraction. Write good descriptions, get good extraction. Writing good descriptions is an art form.

SuperOptiX automates this art form with field description optimization. We use GEPA to optimize the descriptions in your Pydantic BaseModel fields, improving how the model extracts structured data.

The Innovation

Consider a typical output model:

class AgentOutput(BaseModel):
    implementation: str = Field(description="The code implementation")
    explanation: str = Field(description="Explanation of the code")

Before optimization, these generic descriptions might lead to incomplete or incorrect extraction. After optimization, GEPA finds descriptions like:

class AgentOutput(BaseModel):
    implementation: str = Field(
        description="Complete, runnable Python code implementation with error handling, comments, and proper structure"
    )
    explanation: str = Field(
        description="Detailed explanation of the code's functionality, design decisions, and usage instructions"
    )

These optimized descriptions guide the model more effectively, resulting in better structured data extraction.

The Process

Field description optimization happens in optimization workflow, before instruction optimization. This ensures your output schema is optimized first, then instructions can be optimized to work with the improved schema.

You enable it in your playbook:

output_mode: structured
output_fields:
  - name: implementation
    type: str
    description: The code implementation

optimization:
  optimizer:
    name: GEPA
  field_description_optimization:
    enabled: true

GEPA takes your baseline field descriptions and creates variations that are more specific, more detailed, and more effective at guiding extraction. Each variation is tested against your BDD scenarios, measuring extraction accuracy and data quality.

Real Impact

This optimization improves data extraction accuracy by 30 to 50 percent. Structured outputs become more reliable, validation passes more consistently, and the overall quality of extracted data improves significantly. More importantly, this optimization works seamlessly with Pydantic AI’s structured output mode. The optimized descriptions are automatically integrated into your generated Pydantic models, so you get the benefits without additional work.

Bringing Optimization to Pydantic AI with GEPA

GEPA is a genetic algorithm-based optimizer originally developed for DSPy but it can be used with any framework. It systematically explores the space of possible prompts, testing variations and evolving toward better solutions. But GEPA wasn’t designed for Pydantic AI’s architecture.

We’ve adapted GEPA to work with Pydantic AI through our Universal GEPA optimizer. This isn’t a simple port. We’ve built a framework-agnostic optimization system that understands Pydantic AI’s unique characteristics: type safety, structured outputs, MCP integration, and modern async architecture.

Universal GEPA Architecture

The Universal GEPA optimizer works with any framework through our BaseComponent interface. For Pydantic AI, we wrap agents in components that expose optimizable variables: instructions, tool descriptions, and field descriptions.

When you optimize, GEPA doesn’t just tweak prompts. It understands the structure of your agent:

  • It knows which instructions affect tool calling behavior
  • It understands how field descriptions influence structured output
  • It recognizes MCP tool descriptions as separate optimizable components
  • It respects Pydantic AI’s type safety throughout optimization

This means optimizations are aware of your agent’s architecture, not generic prompt tweaks that might break your carefully designed structure.

Multi-Phase Optimization

Our optimization runs in phases, each targeting different aspects:

Field Description Optimization
If enabled, this phase optimizes Pydantic field descriptions for better structured output extraction. It runs first because the output schema affects all downstream optimizations.

MCP Tool Description Optimization
If MCP is enabled, this phase optimizes tool descriptions. Better tool descriptions lead to more accurate tool selection and usage.

Instruction Optimization
Finally, instructions are optimized to work with the improved tool descriptions and field descriptions. This creates a cohesive, optimized agent.

Each phase builds on the previous one, ensuring optimizations work together rather than in isolation.

What Gets Optimized

For Pydantic AI agents, GEPA optimizes:

  1. Agent Instructions: The system prompt that guides agent behavior
  2. MCP Tool Descriptions: Descriptions of MCP tools that affect tool selection and usage
  3. Field Descriptions: Pydantic BaseModel field descriptions that guide structured output extraction

Each is optimized separately but tested together, ensuring the final agent is optimized holistically.

The Results

Optimized Pydantic AI agents show 30 to 60 percent improvement across key metrics:

  • Tool call accuracy improves dramatically with MCP optimization
  • Structured output quality improves with field description optimization
  • Overall agent reliability improves with instruction optimization

The optimization process takes 10 to 30 minutes depending on your budget, but the improvements last. Once optimized, your agent performs consistently better.

 

Output Modes: Plain and Structured Output

In SuperOptiX, Pydantic AI agents support two output modes that let you balance reliability and structure. By default, agents use plain text output, which maps directly to your defined output fields and works very reliably even with smaller local models like llama3.1:8b, avoiding JSON formatting issues while still producing natural, readable responses that are great for code generation and documentation. You can enable the mode using

# Default mode - no configuration needed
# Output is plain text mapped to output fields
spec:
  output_fields:
    - name: implementation
      type: str
      description: Code implementation

For more advanced use cases, you can opt into structured output mode, where responses are validated against a Pydantic BaseModel, giving you type-safe, schema-enforced outputs that take advantage of GEPA optimized field descriptions. This structured mode is ideal when you need high quality structured data and can afford larger models, while the default plain text mode remains the recommended choice for most day to day Pydantic AI workflows.

# Enable structured output
spec:
  output_mode: structured # Opt-in
  output_fields:
      - name: implementation
        type: str
        description: Code implementation
        required: true

optimization:
  optimize_field_descriptions: true # Optimize field descriptions

 

In this way you can get benefit from the plain output as well as the structured output using the Pydantic AI.

 

LogFire Observability: Complete Visibility

Pydantic AI works great, but once you deploy agents to production, you need visibility. What tools are being called? How long do operations take? Where are failures occurring? Without observability, debugging is guesswork.

SuperOptiX already supports some observability tools like MLFlow, LangSmith, Weights&Biases, LangFuse etc but it was lacking amazing observability tools that comes up with the Pydantic AI which is Logfire. We’ve integrated LogFire, Pydantic’s observability platform, directly into SuperOptiX. When you enable LogFire in your playbook, every agent execution is automatically traced. You see tool calls, their inputs and outputs, execution times, and results. You can read more about the Logfire integration in SuperOptiX here.

What You Get

With LogFire integration, you can:

  • Trace Agent Executions: See the complete flow from input to output
  • Monitor Tool Calls: Track MCP tool usage, success rates, and performance
  • Track Optimization Results: Compare before and after metrics
  • Debug Issues: Identify where and why failures occur
  • Measure Performance: Understand latency, throughput, and resource usage

The integration is automatic once you have authorised Logfire. Configure LogFire in your playbook:

logfire:
  enabled: true

SuperOptiX handles the instrumentation. Traces appear in your LogFire dashboard, showing complete execution flows.

Observability Matters

Observability transforms optimization from guesswork to data-driven improvement. You can see which tool descriptions work best, how different prompts affect behavior, and where improvements are needed. For production deployments, observability enables proactive monitoring. Set up alerts for failures, track performance metrics, and ensure your agents meet service level objectives.

The Complete Workflow

SuperOptiX provides a complete workflow that takes Pydantic AI agents from prototype to production. It’s a systematic process that ensures quality, reliability, and performance. You should start referencing the docs to get complete workflow but here is a summary.

Define Agent: Define Your Agent Specifications with SuperSpec YAML

Start with a YAML playbook defining your agent. SuperOptiX generates a production-ready Pydantic AI pipeline that integrates MCP tools, structured output, observability, and all configured features. You can pull pre-built templates from the SuperOptiX agents marketplace.

super agent pull pydantic-mcp

This will create the YAML Playbook with SuperSpec,  with basic configuration for your agent. You can configure it as per the need but for demo you can use it as it is.

Compile: Generate Production-Ready Pipelines

Start with a YAML playbook defining your agent. SuperOptiX generates a production-ready Pydantic AI pipeline that integrates MCP tools, structured output, observability, and all configured features.

super agent compile pydantic-mcp --framework pydantic-ai

The generated code is clean, maintainable, and follows best practices. It’s not a template you modify, it’s a complete, working implementation. Make sure you mention the --framework as SuperOptiX supports multiple frameworks.

Evaluate: Measure Baseline Performance (Optimal)

Evaluate your agent against RSpec Style BDD scenarios to establish a baseline:

super agent evaluate pydantic-mcp

You see your pass rate, identify failures, and understand current performance. This gives you a clear starting point before optimization.

Optimize: Let GEPA Do the Work (Optional)

Optimize with GEPA. This is where SuperOptiX shines use the very very lightweight to get started. Here is simple 3 call optimization but you can choose level as per budget and GPU.

super agent optimize pydantic-mcp --framework pydantic-ai --max-metric-calls 3 --reflection-lm ollama/llama3.1:8

Field descriptions are optimized first, then MCP tool descriptions if enabled, and finally instructions. The optimizer tests variations, selects winners, and generates an optimized pipeline. You see progress in real-time, with metrics showing improvement.

Deploy: Run Optimized Agents

Deploy and run your optimized agent:

super agent run pydantic-mcp --goal "List all files in /private/tmp"

Your optimized agent has better tool descriptions, optimized field descriptions, improved instructions, and full observability. It’s ready for production.

What This Means for Pydantic AI Agent Developers

If you’re building Pydantic AI agents, SuperOptiX gives you capabilities you can’t get anywhere else:

For Pydantic AI Users:

  • Automated optimization that actually works
  • MCP tool optimization for reliable tool calling
  • Field description optimization for better structured outputs
  • Complete observability with LogFire
  • Systematic evaluation and validation

For SuperOptiX Users:

  • Access to Pydantic AI’s modern, type-safe framework
  • Seamless integration with existing SuperOptiX workflows
  • Framework-specific optimizations that respect Pydantic AI’s architecture
  • Universal workflow that works across all frameworks

Real Results

MCP tool optimization delivers huge improvement in tool call accuracy. Field description optimization improves data extraction accuracy. Overall agent performance improves across key metrics. These improvements work with local Ollama models. You don’t need expensive cloud APIs for development and testing. Local 8b models perform well with optimization. When you’re ready for production, the same workflow supports cloud models seamlessly.

Getting Started

Getting started is straightforward:

# Install SuperOptiX with Pydantic AI support
pip install superoptix[frameworks-pydantic-ai]

# Optional but recommended : Add LogFire observability
pip install superoptix[logfire]
logfire auth

# Initialize a project
super init my_agent
cd my_agent

# Pull a pre-built agent or create your own
super agent pull pydantic-mcp

# Compile with Pydantic AI
super agent compile pydantic-mcp --framework pydantic-ai

# Evaluate baseline
super agent evaluate pydantic-mcp

# Optimize
super agent optimize pydantic-mcp --framework pydantic-ai --max-metric-calls 3 --reflection-lm ollama/llama3.1:8

# Run
super agent run pydantic-mcp --goal "List all files in /private/tmp"

The entire workflow takes minutes, not days. What used to require weeks of manual optimization now happens automatically.

Watch In Action

The Future of SuperOptiX Integrations with Pydantic AI

Pydantic AI is already so powerful but SuperOptiX transforms Pydantic AI development by enabling the Optimization. No more manual prompt engineering. No more guessing which tool descriptions work. No more wondering if your field descriptions are good enough. Optimization becomes systematic, observable, and reliable. SuperOptiX bringing advanced optimization capabilities to Pydantic AI that fundamentally change how agents are built. MCP optimization ensures reliable tool calling. Field description optimization ensures quality structured outputs. GEPA integration brings systematic optimization to a framework that deserves it. As we continue to integrate SuperOptiX with Pydantic AI, we’re exploring new optimization targets, better observability, and tighter integration with Pydantic AI’s evolving features. If you’re building Pydantic AI agents, try SuperOptiX integration. See the difference that systematic optimization makes. Experience reliable tool calling, better structured outputs, and complete observability. Build production-ready agents with combination of the Pydantic AI and SuperOptiX from day one.

Checkout SuperOptiX from Superagentic AI.

Resources: