Improving MCP tool schemas
to increase agent reliability

This tool signature:

@mcp.tool
async def add_expense(
    expense_date: str,
    amount: float,
    category: str,
    description: str,
) -> str:
    """Add a new expense."""
    ...
            

becomes this schema:

{
  "name": "add_expense",
  "description": "Add a new expense.",
  "inputSchema": {
    "properties": {
      "expense_date": {"type": "string"},
      "amount": {"type": "number"},
      "category": {"type": "string"},
      "description": {"type": "string"}
    },
    "required": ["expense_date", "amount",
      "category", "description"],
    "type": "object"
  }
}
            

Python code:

    category: Annotated[
        str,
        Field(
            description="Must be one of: "
            "Food & drink, "
            "Transit and Fuel, "
            "Media & streaming, "
            "Apparel and Beauty, "
            "Electronics & tech, "
            "Home and office, ..."
        ),
    ],
            

Generated schema:

"category": {
    "type": "string",
    "description": "Must be one of:
      Food & drink,
      Transit and Fuel,
      Media & streaming,
      Apparel and Beauty,
      Electronics & tech,
      Home and office, ..."
}
            

Python code:

CATEGORY_LITERAL = Literal[
    "Food & drink", "Transit and Fuel",
    "Media & streaming", ...
]
    category: CATEGORY_LITERAL,
            

class Category(Enum):
    FOOD_AND_DRINK = "Food & drink"
    TRANSIT_AND_FUEL = "Transit and Fuel"
    ...

    category: Category,
            

Generated schema:

"category": {
    "type": "string",
    "enum": [
        "Food & drink",
        "Transit and Fuel",
        "Media & streaming", ...
    ]
}
            

Python code:

    category: Annotated[
        Category,
        Field(
            description=(
                "Choose the closest category. "
                "If truly unclear, use Misc.\n\n"
                "Heuristics: "
                "Food & drink=meals, coffee; "
                "Transit and Fuel=rideshare, "
                "gas, parking; ..."
            )
        ),
    ],
            

Generated schema:

"category": {
    "type": "string",
    "enum": [
        "Food & drink",
        "Transit and Fuel",
        "Media & streaming", ...
    ],
    "description": "Choose the closest
      category. If truly unclear, use
      Misc. Heuristics: Food & drink=
      meals, coffee; Transit and Fuel=
      rideshare, gas, parking; ..."
}
            

EXPENSE_CASES = [
    ExpenseCase(
        name="clear_food_yesterday",
        prompt="Yesterday I bought a sandwich for $12.50.",
        expected_category="Food & drink",
        expected_date=get_yesterday(),
        expected_amount=12.50,
    ),
    ...  # 17 cases ➡️
]

def evaluate_category_match(tool_calls, expected):
    """Does the category match what we expected?"""
    for tc in tool_calls:
        category = tc.arguments.get("category")
        if category == expected:
            return EvalResult(passed=True, score=1.0)
    return EvalResult(passed=False, score=0.0)

for variant in ["cat_b", "cat_c", "cat_d", "cat_e"]:
    toolset = server.filtered(
        tool_filter=lambda t: t.name == f"add_expense_{variant}")
    agent = Agent(model, toolsets=[toolset], ...)
    for case in EXPENSE_CASES:
        result = await agent.run(case.prompt)
        evals = run_all_evaluations(
            result.tool_calls, case)
            

Python code:

@mcp.tool
def get_expenses_a() -> str:
    """Get all expenses."""
    return "\n".join(
        f"Date: {e['date']}, Amount: ${e['amount']}, "
        f"Category: {e['category']}, ..."
        for e in expenses
    )
            

Example output:

Date: 2025-01-02, Amount: $4.50,
  Category: Food & drink,
  Description: Morning coffee
Date: 2025-01-02, Amount: $12.99,
  Category: Food & drink,
  Description: Lunch sandwich
Date: 2025-01-03, Amount: $45.00,
  Category: Transit and Fuel,
  Description: Gas station fill-up
...
            

Python code:

class Expense(BaseModel):
    """A single expense record."""
    expense_date: date = Field(
        alias="date",
        description="Date of the expense")
    amount: float = Field(
        description="Amount spent")
    category: str = Field(
        description="Category of expense")
    description: str = Field(
        description="Description of the expense")

@mcp.tool
def get_expenses_c() -> list[Expense]:
    """Get all expenses."""
    return [Expense(**e) for e in expenses]
            

Example output:

[
  {"date": "2025-01-02",
   "amount": 4.5,
   "category": "Food & drink",
   "description": "Morning coffee"},
  {"date": "2025-01-02",
   "amount": 12.99,
   ...},
  ...
]