Robust Tool Definitions: Pydantic, JSON Schema, and MCP

The difference between a demo and a product is how it handles failure.

The Garbage In Problem

When an LLM (Large Language Model) uses a tool—whether its a calculator, a SQL query, or an API call—it is essentially guessing the arguments. It predicts: I should call search_database with query=Q4 Revenue.

But what if it calls it with query=123? Or query=None?

In a Python script, you get a TypeError and the program crashes. In an Agentic System, a crash is unacceptable. The agent needs to catch the error, understand it, and try again.

Enter Pydantic

At Elegant Software Solutions, we enforce a strict rule: No Tool Left Behind (Without a Schema).

We use Pydantic, a data validation library for Python, to define the strict contract for every tool our agents use.

Bad Tool Definition:

def search(query):
    # What is query? A string? A dict?
    # What happens if its empty?
    return db.execute(query)

Good Tool Definition (The ESS Standard):

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(..., description=The search term. Must be at least 3 characters.)
    limit: int = Field(10, ge=1, le=100, description=Max results to return.)

def search(args: SearchInput):
    # If the LLM sends limit: 200, Pydantic raises a validation error automatically.
    # We catch that error and send it BACK to the LLM.
    pass

The Self-Healing Loop 🩹

When we use robust definitions, we enable a Self-Healing Loop:

Agent: Calls search(limit=200)
System (Pydantic): Error: limit must be = 100
System: Captures error, does NOT crash. Returns error message to Agent as an observation.
Agent: Oops, I set the limit too high. I will retry with limit=100.
Agent: Calls search(limit=100) - Success.

The Model Context Protocol (MCP)

This philosophy is core to Anthropics Model Context Protocol (MCP), which we champion. MCP standardizes how these tool definitions are shared between the server (your database) and the client (Claude/OpenAI).

By adopting MCP, we ensure that your agents arent just guessing at your APIs—they are reading a strict, type-safe manual on how to use them.

Conclusion

Reliability isnt magic. Its validation. By treating LLM inputs with the same suspicion we treat user inputs on a web form, we build agents that can survive in the wild.

Next in the series: How we use the [Reviewer Pattern](/blog/reviewer-pattern-automated-qa-agents) to double-check agent code.

How This Article Was Made

This article is a live example of the AI-enabled content workflow we build for clients.

Stage	Who	What
Research	Claude Opus 4.5	Analyzed current industry data, studies, and expert sources
Curation	Tom Hundley	Directed focus, validated relevance, ensured strategic alignment
Drafting	Claude Opus 4.5	Synthesized research into structured narrative
Fact-Check	Human + AI	All statistics linked to original sources below
Editorial	Tom Hundley	Final review for accuracy, tone, and value

The result: Research-backed content in a fraction of the time, with full transparency and human accountability.

Why We Work This Way

Were an AI enablement company. It would be strange if we didnt use AI to create content. But more importantly, we believe the future of professional content isnt AI vs. Human—its AI amplifying human expertise.

Every article we publish demonstrates the same workflow we help clients implement: AI handles the heavy lifting of research and drafting, humans provide direction, judgment, and accountability.

Want to build this capability for your team? Lets talk about AI enablement →