MCP Tool Calls Fail: Debug Invalid Arguments and Validation Errors
Fix MCP tool call failures caused by invalid arguments, wrong IDs, missing fields, or server validation errors. Learn the read-only first strategy and systematic debugging workflow.
Understanding Tool Call Failures
When a tool call fails, the request reached the server and was processed, but something about the input or operation was invalid. This is different from connection or authentication errors.
Error Categories
- Input errors: Invalid arguments, wrong types, missing required fields
- ID errors: Wrong task/project/board IDs, non-existent resources
- Validation errors: Server-side validation failures (business logic)
- Permission errors: Valid input but insufficient permissions (see 403 guide)
Debugging Strategy: Read-Only First
Start with read-only operations to verify basic access before attempting writes:
Recommended Debugging Workflow
- Test read operations: Try list_tasks, list_projects, get_task (read-only)
- Verify IDs: Use IDs from read operations in subsequent calls
- Test simple writes: Try add_task_comment (simpler than create_task)
- Test complex writes: Finally try create_task, update_task (more validation)
Why Read-Only First?
- Fewer validation rules - read operations have simpler requirements
- Verify access - confirms you can reach the resource
- Get correct IDs - read operations return valid IDs to use in writes
- Isolate issues - if reads work but writes fail, it's a write-specific problem
Common Error Types
1. Invalid Arguments
Arguments that don't match the expected type or format:
Wrong Type
❌ Incorrect:
{ "task_id": "123" } // String✅ Correct:
{ "task_id": 123 } // IntegerInvalid Enum Value
❌ Incorrect:
{ "status": "active" }✅ Correct:
{ "status": "in_progress" }
// Valid: open, in_progress, done, blockedInvalid Date Format
❌ Incorrect:
{ "due_date": "2026/05/30" }✅ Correct:
{ "due_date": "2026-05-30" }
// ISO 8601 format2. Missing Required Fields
Some tool calls require specific fields that must be provided:
Required Fields by Tool
get_task: Requirestask_idcreate_task: Requirestitle(and oftenproject_id)update_task: Requirestask_idadd_task_comment: Requirestask_idandcommentstart_time_tracking: Requirestask_id
Example: Missing Required Field
❌ Invalid (Missing title):
{
"project_id": 123,
"description": "Task description"
}✅ Valid (Has title):
{
"title": "Task title",
"project_id": 123,
"description": "Task description"
}3. Wrong IDs
Using IDs that don't exist or belong to different resources:
Common ID Mistakes
- Non-existent ID: Using task_id 99999 that doesn't exist
- Wrong resource type: Using project_id where task_id is expected
- ID from different workspace: Using task ID from workspace A in workspace B
How to Get Correct IDs
- Call
list_tasksto see available task IDs - Call
list_projectsto see available project IDs - Call
list_boardsto see available board IDs - Use IDs from these lists in subsequent tool calls
4. Server-Side Validation
Even with valid arguments, the server may reject the operation due to business logic:
Common Validation Errors
- Cannot delete a task that has dependencies
- Cannot update a task that's already completed
- Cannot create a task in a closed project
- Date constraints (due_date before start_date)
- Cannot start time tracking if already tracking another task
Interpreting Error Payloads
Error Response Structure
Typical error response format:
{
"error": {
"code": "validation_error",
"message": "Task ID 99999 not found",
"field": "task_id",
"details": "The specified task does not exist"
}
}Common Error Codes
validation_error: Input validation failed (wrong type, missing field, invalid value)not_found: Resource with specified ID doesn't existforbidden: Valid input but insufficient permissionsconflict: Operation conflicts with current state
Step-by-Step Debugging Process
Systematic Debugging Workflow
- Read the error message: Check the error code and message for clues
- Verify IDs exist: Use list operations to confirm resource IDs are valid
- Check required fields: Review tool documentation for required parameters
- Test with read-only: Try get_task or list_tasks to verify basic access
- Simplify the call: Remove optional parameters and test with minimal required fields
- Check field types: Ensure strings, integers, dates are correct format
- Review error details: Look at the "field" and "details" in error response
Example: Debugging a Failed Tool Call
Failed Call
- Tool: update_task
- Arguments:
{ "task_id": "123", "status": "completed" } - Error: "Task ID 123 not found"
Debugging Steps
- First, verify task exists:
get_task(task_id: 123) - If that fails, list tasks:
list_tasks()to see available IDs - Check if task_id should be integer, not string:
{ "task_id": 123 } - Verify task is in accessible workspace
Resolution
- Issue: task_id was passed as string "123" instead of integer 123
- Fix: Changed to
{ "task_id": 123 }(integer) - Result: Tool call succeeded
Quick Fix Checklist
Before Asking for Help
- ✅ Read the error message carefully - what does it say?
- ✅ Verified IDs exist using list operations
- ✅ Checked all required fields are present
- ✅ Tested with read-only operations first
- ✅ Verified field types (string vs integer, date format)
- ✅ Simplified the call to minimal required fields
- ✅ Reviewed tool documentation for parameter requirements
Related Troubleshooting
403 Forbidden
Fix permission issues when tool calls are denied.
Tools Not Listed
Fix issues when tools don't appear at all.
Tool References
Review tool documentation for parameter requirements.
All Troubleshooting
Browse all MCP troubleshooting guides.
Building with MCP? Run the business on Corcava too.
MCP connects your AI tools to tasks and time. Corcava is where agencies manage clients, projects, billing, and profitability — the same workspace your API key already talks to.