Skip to main content
Glama

list_tasks

Read-onlyIdempotent

Lists and filters project or workspace tasks by status, priority, assignee, labels, and search, returning compact or full details for review and coordination.

Instructions

List tasks with strict filters. Provide project_id for a project listing or workspace_id plus search for cross-project search. Unknown parameters and invalid categories are errors. Compact items contain id, title, status slug, priority, assignee_name, labels, updated_at, runtime_state (working/waiting/queued/stopped with since/lane/ref/stale, when known) and routing parent_task_id/start_after when set; workspace results also contain project_id. full=true returns complete REST items; listing descriptions are subject to the API page budget, while get_task returns full details. For your own queue use get_my_tasks.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_tasks"
  }
}

Input Schema

NameRequiredDescriptionDefault
fullNoReturn complete items (full descriptions and non-capability envelope fields) instead of compact items.
pageNo1-based page number (default 1). The response reports total_pages; without this parameter every page beyond the first was unreachable while the envelope kept advertising them.
sortNoSort field: created_at, updated_at, priority, due_date.
limitNoMax results to return (default 20). The compact view caps limit at 50 — a larger value is clamped and the response says so via limit_clamped_to; pass full=true for up to 200 per page.
orderNoSort direction: asc (default) or desc. Without this, a project larger than `limit` returns its OLDEST tasks, so "what changed recently" walks come back empty and look clean. An invalid value is REFUSED by the API, not silently treated as asc.
labelsNoFilter by labels.
searchNoSearch in title and description.
assigneeNoFilter by exact case-insensitive assignee name, UUID, or me. Unknown or ambiguous names are errors.
priorityNoFilter by priority: urgent, high, medium, low, none.
project_idNoProject ID (required unless workspace_id is provided).
assignee_idNoUUID-only compatibility alias for assignee. Use assignee for names or me.
runtime_kindNoFilter by effective runtime state: working, waiting, queued, stopped. working also matches a card with a live checkout and no reported state, whatever its status.
workspace_idNoWorkspace ID for global cross-project search (requires search parameter).
assignee_typeNoFilter by assignee type: user, agent, unassigned.
list_revisionNoThe list_revision echoed back on a previous page of this same project-scoped walk (see the response's list_revision field). Pass it back to continue that walk. If the project's tasks changed since that page was issued, the call is REFUSED with list_revision_stale (HTTP 410) instead of silently returning an inconsistent page — restart pagination from page 1 (omit this field) on that error. Omit on the first page of a fresh walk. Ignored for workspace_id search.
status_categoryNoFilter by status category: backlog, todo, triage, in_progress, review, done, cancelled.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.7
    • changedInput schema / properties / status_category / description
      Previous value: -"Filter by status category: backlog, todo, in_progress, review, done, cancelled."New value: +"Filter by status category: backlog, todo, triage, in_progress, review, done, cancelled."
  2. First observedv0.1.1

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only/idempotent/non-destructive safety, and the description adds real behavioral context beyond them: compact items are subject to the API page budget, compact limit is clamped at 50 with full=true allowing 200, and a stale list_revision is REFUSED with HTTP 410 rather than silently returning an inconsistent page. It also discloses what the compact payload contains, including runtime_state subfields and routing fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The routing rule and the sibling exclusions are front-loaded, and the dense middle sentences each carry operational information. The compact-field enumeration is list-like and the page-budget sentence is terse, but no sentence is pure filler for a tool with 16 parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 16 parameters and no output schema, the description compensates by describing the compact result shape, the full-item mode, pagination continuation via list_revision, and the error surface. The one thing an agent must know before calling — which identifier combination is valid — is stated up front.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description still adds meaning the schema does not: full=true changes item shape, limit is clamped in compact mode, and list_revision continues a project-scoped walk or triggers a 410 restart. Parameters like sort, labels, and status_category are left entirely to the schema, so it is not a full 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

"List tasks with strict filters" gives a specific verb and resource, then immediately splits the two listing modes (project_id vs workspace_id plus search). It also names the siblings it is not — get_task for full details and get_my_tasks for your own queue — so an agent can route without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit selection rules are given: use project_id for a project listing, workspace_id plus search for cross-project search, get_my_tasks for your own queue, get_task for full details. It also warns that unknown parameters and invalid categories are errors, which prevents speculative arguments.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.