Input Validation with Pydantic

Reliable tool execution depends on strict adherence to defined interfaces. When a Large Language Model (LLM) invokes a tool, it generates a text string formatted as JSON. While LLMs are increasingly capable of producing valid syntax, they operate probabilistically. They may hallucinate arguments, provide data in the wrong format (such as sending a string when an integer is required), or omit mandatory parameters entirely.

To bridge the gap between the probabilistic nature of the model and the deterministic requirements of your code, we employ rigorous input validation. In the Python ecosystem, Pydantic is the standard for data parsing and validation. Within the Model Context Protocol (MCP), Pydantic serves two distinct functions: it enforces type safety on incoming tool requests and automatically generates the JSON Schema required for the tools/list capability definition.

Defining the Tool Interface

The foundation of a tool is the data model representing its arguments. By inheriting from pydantic.BaseModel, you define the expected structure of the input. This model acts as a contract between the MCP server and the client.

Consider a scenario where we are building a tool to query a product database. A naive implementation might accept a generic dictionary. However, using a Pydantic model provides immediate validation logic.

from pydantic import BaseModel, Field, PositiveInt
from typing import Optional

class InventoryQuery(BaseModel):
    category: str = Field(
        ..., 
        description="The product category to filter by, such as 'electronics' or 'apparel'."
    )
    limit: PositiveInt = Field(
        10, 
        description="The maximum number of results to return. Defaults to 10."
    )
    warehouse_id: Optional[str] = Field(
        None, 
        description="Optional specific warehouse ID to narrow the search."
    )

In this example, the InventoryQuery class performs several critical tasks. It enforces that category is a string and limit is a positive integer. It also marks warehouse_id as optional. If an LLM attempts to call this tool with limit=-5, Pydantic intercepts the request and raises a ValidationError before your logic ever executes.

The Role of Field Descriptions

You will notice the extensive use of the Field function in the code above. In standard Python development, these descriptions serve documentation purposes for developers. In the context of MCP, these descriptions serve a functional role: they are part of the prompt.

When the MCP server advertises its tools to the client (like Claude Desktop), it serializes the Pydantic model into a JSON Schema. The description parameters in your Field definitions are passed directly to the LLM. These descriptions guide the model on how to populate the arguments correctly.

If the validation logic is defined as a function $f(x) \to \{0, 1\}$, where $1$ is valid and $0$ is invalid, the description increases the probability $P(f(x_{LLM}) = 1)$. Clear, verbose descriptions in your Pydantic models reduce the rate of ValidationError events significantly.

The Validation Pipeline

When a request arrives at an MCP server, it undergoes a specific sequence of checks. Understanding this flow is important for debugging interactions between the client and your tool logic.

The diagram outlines the sequential processing of a tool request, highlighting the gatekeeping role of the validation step.

If the validation step fails, the MCP server catches the exception. Instead of crashing, the server formats the validation error as a text response and sends it back to the client. This feedback loop allows the LLM to observe its mistake ("Argument 'limit' must be positive") and attempt the tool call again with corrected values.

implementing Custom Validators

Standard type checking covers most use cases, but complex tools often require logic that goes further than simple types. For instance, if you are building a SQL query tool, you might want to restrict the types of operations allowed (e.g., allowing SELECT but forbidding DROP).

Pydantic allows for custom validators using the @field_validator decorator. This permits you to inject domain-specific logic into the validation layer.

from pydantic import BaseModel, Field, field_validator

class SQLQuery(BaseModel):
    query: str = Field(..., description="The SQL query to execute.")

    @field_validator('query')
    @classmethod
    def prevent_destructive_commands(cls, v: str) -> str:
        forbidden = ["DROP", "DELETE", "TRUNCATE", "ALTER"]
        upper_query = v.upper()
        for cmd in forbidden:
            if cmd in upper_query:
                raise ValueError(f"Destructive command '{cmd}' is not allowed.")
        return v

By placing this logic inside the Pydantic model, you decouple the security rules from the execution logic. The SQLQuery model ensures that your execution handler receives only sanitized strings. This separation of concerns makes the codebase easier to test and maintain.

Integration with the MCP Server

Once your Pydantic models are defined, they must be registered with the MCP server instance. The SDK uses type hints to inspect the function signature and map the arguments to the JSON Schema.

When using the standard MCP Python SDK (or wrappers like FastMCP), you pass the Pydantic model as the type hint for the first argument of your tool function.

# Assuming 'mcp' is an instantiated FastMCP or Server object

@mcp.tool()
def query_inventory(args: InventoryQuery) -> str:
    """
    Queries the warehouse inventory system based on category filters.
    """
    # At this point, 'args' is guaranteed to be a valid InventoryQuery object
    # with correct types and satisfied constraints.
    
    results = database.search(
        category=args.category, 
        limit=args.limit
    )
    
    return format_results(results)

In this implementation, the docstring of the function query_inventory becomes the top-level description of the tool, while the InventoryQuery model provides the schema for the arguments.

Handling Complex Nested Structures

Tools occasionally require complex, nested data structures. For example, a tool that configures a charting library might need a list of data points, where each point contains $x$ and $y$ coordinates. Pydantic handles this via model nesting.

class DataPoint(BaseModel):
    x: float
    y: float

class ChartConfig(BaseModel):
    title: str
    points: list[DataPoint]
    color: str = "blue"

When the LLM interacts with a tool using ChartConfig, the MCP server validates the entire tree. If the third point in a list of fifty has a string where a float is expected for the $y$ value, the validation fails precisely for that element. This granularity ensures that your tool logic never has to manually parse or cast types within deeply nested lists or dictionaries.

Impact on LLM Performance

The strictness of your validation directly influences the reliability of the agent. While it might be tempting to use loose types (like dict or Any) to avoid validation errors, this transfers the burden of error handling to your runtime logic, which is harder to communicate back to the LLM.

When an LLM receives a clear, structured schema derived from a Pydantic model, it performs better because the "action space" is well-defined. If it does make a mistake, the structured error message from Pydantic acts as a corrective prompt, guiding the model toward the correct usage in the subsequent turn. This self-healing behavior is a significant advantage of using formal schemas over unstructured string parsing.