ValidationError
pydantic.error_wrappers.ValidationError
Stack trace
pydantic.error_wrappers.ValidationError: 1 validation error for ToolCallArgs field_name field required (type=value_error.missing) During handling of the above exception, MCP raised a schema validation error for the tool call arguments.
Why it happens
MCP uses Pydantic models to validate the arguments passed to tools. If the arguments are missing required fields, have incorrect types, or extra unexpected fields, Pydantic raises a ValidationError. This usually happens when the input dictionary keys or types do not match the tool's argument schema exactly.
Detection
Catch pydantic.error_wrappers.ValidationError exceptions around tool call invocations and log the invalid argument payload to identify mismatches before the app crashes.
Causes & fixes
Missing required argument fields in the tool call dictionary
Ensure all required fields defined in the tool's Pydantic argument schema are present in the dictionary passed to the tool call.
Argument fields have incorrect data types (e.g., string instead of int)
Convert or cast argument values to the correct types as defined in the tool's Pydantic schema before calling the tool.
Extra unexpected fields included in the argument dictionary
Remove any fields not defined in the tool's argument schema to avoid validation errors.
Using outdated or mismatched tool argument schema versions
Update your MCP package and ensure your argument dictionaries match the latest schema definitions exactly.
Code: broken vs fixed
from mcp import MCP
mcp = MCP()
args = {'name': 'example'} # Missing required fields
result = mcp.call_tool('my_tool', args) # Raises ValidationError hereimport os
from mcp import MCP
os.environ['MCP_API_KEY'] = os.environ.get('MCP_API_KEY', 'your_api_key_here') # Use env var for keys
mcp = MCP()
args = {'name': 'example', 'count': 5} # All required fields present with correct types
result = mcp.call_tool('my_tool', args) # Fixed: no ValidationError
print(result)Workaround
Wrap the tool call in try/except ValidationError, catch the exception, log the invalid arguments, and attempt to fix or sanitize the input before retrying.
Prevention
Use typed data classes or Pydantic models to construct tool call arguments programmatically, ensuring schema compliance before calling MCP tools.