Échec des appels d'outils MCP : déboguer arguments invalides et erreurs de validation
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