MCP Tool Calls Fail: Debugging Inputs, Validation, and Error Payloads

MCP tools are listed but calls fail? This generic troubleshooting guide helps you debug tool call failures: invalid arguments, missing required fields, wrong IDs, and server-side validation errors. Learn how to narrow down issues by trying read-only calls first.

Understanding Tool Call Failures

When a tool call fails, it means 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 Forbidden)

Debugging Strategy: Read-Only First

Start with read-only operations to verify basic access before attempting writes:

Recommended Debugging Workflow

1. Test read operations: Try list_tasks, list_projects, get_task (read-only)
2. Verify IDs: Use IDs from read operations in subsequent calls
3. Test simple writes: Try add_task_comment (simpler than create_task)
4. 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

Error Type 1: Invalid Arguments

Arguments that don't match the expected type or format:

Common Argument Errors

Wrong Type

• Example: Passing string "123" instead of integer 123 for task_id
• ❌ { "task_id": "123" } // String
• ✅ { "task_id": 123 } // Integer

Invalid Enum Value

• Example: Using "active" instead of "in_progress" for status
• ❌ { "status": "active" }
• ✅ { "status": "in_progress" } // Valid: open, in_progress, done, blocked

Invalid Date Format

• Example: Wrong date format for due_date
• ❌ { "due_date": "2026/05/30" }
• ✅ { "due_date": "2026-05-30" } // ISO 8601 format

Error Type 2: Missing Required Fields

Some tool calls require specific fields that must be provided:

Required Fields by Tool

• get_task: Requires task_id
• create_task: Requires title (and often project_id)
• update_task: Requires task_id
• add_task_comment: Requires task_id and comment
• start_time_tracking: Requires task_id

Example: Missing Required Field

Invalid (Missing title)

Missing required "title" field

{
  "project_id": 123,
  "description": "Task description"
}

Valid (Has title)

Includes required "title" field

{
  "title": "Task title",
  "project_id": 123,
  "description": "Task description"
}

Error Type 3: Wrong IDs

Using IDs that don't exist or belong to different resources:

Common ID Mistakes

Non-Existent ID

• Example: Using task_id 99999 that doesn't exist
• Fix: Use list_tasks first to get valid task IDs

Wrong Resource Type

• Example: Using project_id where task_id is expected
• Fix: Verify the parameter name matches the resource type

ID from Different Workspace

• Example: Using task ID from workspace A in workspace B
• Fix: Ensure API key and resource IDs are from the same workspace

How to Get Correct IDs

Use read operations to get valid IDs:

1. Call list_tasks to see available task IDs
2. Call list_projects to see available project IDs
3. Call list_boards to see available board IDs
4. Use IDs from these lists in subsequent tool calls

Error Type 4: Server-Side Validation

Even with valid arguments, the server may reject the operation due to business logic:

Common Validation Errors

Business Rule Violations

• 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)

State Conflicts

• Cannot start time tracking if already tracking another task
• Cannot update task status to invalid transition
• Cannot add comment to deleted task

Interpreting Error Payloads

Error responses contain details about what went wrong:

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 exist

forbidden

Valid input but insufficient permissions (see 403 guide)

conflict

Operation conflicts with current state (e.g., duplicate task, state transition invalid)

Step-by-Step Debugging Process

Systematic Debugging Workflow

1. Read the error message: Check the error code and message for clues
2. Verify IDs exist: Use list operations to confirm resource IDs are valid
3. Check required fields: Review tool documentation for required parameters
4. Test with read-only: Try get_task or list_tasks to verify basic access
5. Simplify the call: Remove optional parameters and test with minimal required fields
6. Check field types: Ensure strings, integers, dates are correct format
7. Review error details: Look at the "field" and "details" in error response

Example: Debugging a Failed Tool Call

Here's how to debug a specific failure:

Failed Call

• Tool: update_task
• Arguments: { "task_id": "123", "status": "completed" }
• Error: "Task ID 123 not found"

Debugging Steps

1. First, verify task exists: get_task(task_id: 123)
2. If that fails, list tasks: list_tasks() to see available IDs
3. Check if task_id should be integer, not string: { "task_id": 123 }
4. 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
• Troubleshooting Index - Browse all troubleshooting guides