List Tasks via MCP: Filters, Pagination, and Examples

Developer reference for the list_tasks MCP tool. Learn how to search and filter tasks by project, board, status, due date, assignee, or keyword. Includes example tool calls, natural language prompts, edge cases, and troubleshooting.

Tool Overview

Purpose

The list_tasks tool allows you to search and filter tasks in your Corcava workspace. It's the most commonly used tool for discovering tasks, generating reports, and planning workflows.

Read-only operation: This tool only reads data - it never modifies tasks.

Input Parameters

All parameters are optional. If no parameters are provided, returns all tasks you have access to (paginated).

Output Format

The tool returns a JSON object with tasks and pagination information:

{
  "tasks": [
    {
      "id": 123,
      "title": "Implement login feature",
      "description": "Add user authentication...",
      "status": "in_progress",
      "due_date": "2026-02-28",
      "project_id": 456,
      "board_id": 789,
      "assignee_id": 101,
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-02-20T14:22:00Z"
    },
    ...
  ],
  "total": 42,
  "limit": 25,
  "offset": 0,
  "has_more": true
}

Response Fields

• tasks: Array of task objects (empty array if no matches)
• total: Total number of tasks matching the filters (across all pages)
• limit: Maximum number of tasks returned in this response
• offset: Number of tasks skipped (for pagination)
• has_more: Boolean indicating if more tasks are available

Example Tool Calls

Example 1: List All Tasks

Tool Call (JSON):

{
  "tool": "list_tasks",
  "arguments": {
    "limit": 50
  }
}

Returns: First 50 tasks from your workspace

Example 2: Tasks Due This Week

Tool Call (JSON):

{
  "tool": "list_tasks",
  "arguments": {
    "due_date": "this_week",
    "limit": 25
  }
}

Returns: Tasks due in the current week

Example 3: Search by Keyword

Tool Call (JSON):

{
  "tool": "list_tasks",
  "arguments": {
    "search": "login",
    "limit": 10
  }
}

Returns: Tasks with "login" in title or description

Example 4: Filter by Project and Status

Tool Call (JSON):

{
  "tool": "list_tasks",
  "arguments": {
    "project_id": 456,
    "status": "in_progress",
    "limit": 20
  }
}

Returns: In-progress tasks in project 456

Example 5: Pagination

First Page:

{
  "tool": "list_tasks",
  "arguments": {
    "limit": 25,
    "offset": 0
  }
}

Second Page:

{
  "tool": "list_tasks",
  "arguments": {
    "limit": 25,
    "offset": 25
  }
}

Returns: Tasks 26-50 (second page of results)

Natural Language Prompt Examples

Here's how users typically interact with list_tasks through natural language:

Claude Desktop / General AI

User Prompt:

"What tasks are due this week?"

AI Behavior:

1. AI calls list_tasks with due_date: "this_week"
2. AI receives task list
3. AI formats and presents results to user

Cursor / IDE Context

User Prompt:

"Show me all in-progress tasks in the API project"

AI Behavior:

1. AI calls list_projects to find "API project"
2. AI calls list_tasks with project_id and status: "in_progress"
3. AI presents task list in IDE-friendly format

Weekly Planning

User Prompt:

"What tasks are due this week, and which ones are blocked?"

AI Behavior:

1. AI calls list_tasks with due_date: "this_week"
2. AI analyzes tasks and identifies blocked ones
3. AI presents organized weekly plan

Common Use Cases

• Weekly Planning - List tasks due this week, identify blockers, and set priorities
• Daily Focus - Find tasks due today or soon for daily planning
• Cross-Project Search - Search for tasks by keyword across all projects
• Status Reports - Generate reports by filtering tasks by project, status, or date

Edge Cases

Empty Results

Situation: No tasks match the filters

Response:

{
  "tasks": [],
  "total": 0,
  "limit": 25,
  "offset": 0,
  "has_more": false
}

Handling: Check if tasks array is empty before processing

Large Datasets

Situation: Thousands of tasks match filters

Best Practice:

• Always use limit to cap results (default: 50, max: 100)
• Use offset for pagination
• Check has_more to know if more pages exist
• Add more specific filters to narrow results

Pagination

Pattern: Fetching all tasks across multiple pages

1. Call with limit: 50, offset: 0
2. Check has_more
3. If true, call again with offset: 50
4. Repeat until has_more: false

Note: For large datasets, consider summarizing instead of fetching all tasks

Invalid Filters

Situation: Invalid project_id, board_id, or status value

Response: Returns empty results (no error thrown)

Best Practice: Validate IDs exist before filtering, or handle empty results gracefully

Troubleshooting

Timeout Errors

Symptom: Request times out when fetching many tasks

Causes:

• Too many tasks match filters
• Large limit value (approaching 100)
• Network latency

Fix:

• Reduce limit to 25-50
• Add more specific filters
• Use pagination instead of fetching all at once

Read timeout troubleshooting →

Rate Limiting (429)

Symptom: 429 error when making multiple calls

Causes:

• Too many rapid calls
• Looping through pagination too quickly

Fix:

• Add delays between pagination calls
• Batch operations when possible
• Cache results when appropriate

Read rate limiting guide →

Invalid Filter Values

Symptom: Empty results when filters should match

Causes:

• Invalid project_id or board_id
• Wrong status value (must be: open, in_progress, done, blocked)
• Invalid due_date format

Fix:

• Verify IDs exist using list_projects or list_boards
• Use correct status values
• Use predefined due_date values: today, this_week, this_month, overdue

Read validation troubleshooting →

Best Practices

Using list_tasks Effectively

• ✅ Always set a reasonable limit (25-50 is ideal)
• ✅ Use specific filters to narrow results (project_id, status, due_date)
• ✅ Use pagination for large datasets instead of increasing limit
• ✅ Check has_more before fetching next page
• ✅ Use search for keyword matching across titles/descriptions
• ✅ Combine filters for precise results (e.g., project + status + due_date)
• ✅ Handle empty results gracefully
• ✅ Cache results when appropriate to reduce API calls

Related Tools

Often used together with:

• get_task - Get detailed information about a specific task
• list_projects - Find project IDs for filtering tasks