Skip to main content
Glama

tasks_list

Read-onlyIdempotent

Read tasks. view=board returns a board scan: 50 concise current-state rows by default, no descriptions/comments. Other reads default to a small task page (10, bounded response). The same filters with page.next_cursor as cursor continue; pages are not concatenated automatically. Task ordering is live keyset: edits to sort/filter fields may skip or repeat rows; a new read starts a fresh queue. Fields in omitted are partial; tasks_get view=field expands them. detail=full explicitly permits unbounded descriptions. task_id reads one current task; tasks_get covers history/field options. review_for_closure reports its source candidate limit. tasks_overview covers project direction and work; tasks_summary gives counts and memory_search durable guidance.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project_id": "<project_id>"
    },
    "name": "tasks_list"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoCase-insensitive text search over title and description.
areaNoFilter to tasks in this subsystem.
kindNoHistory kind; defaults to comments. revisions holds saved guidance text; reviews holds explicit account review records.
sortNoSort order. Default (omitted) is the smart order: open before done, by priority, newest first.
typeNoFilter by one type or a comma-separated list. Custom labels are supported. vision — why the organization exists. philosophy — a belief guiding trade-offs, including why it matters. directive — a rule or instruction, including what it supersedes. decision — a steer from the person who owns the project: their words, what it changes, what it replaces, the work it governs. sop — how to carry out a recurring job. spec — what to build and its acceptance criteria. roadmap — direction and outcomes for work ahead. epic — a larger outcome grouping related tasks. task — a concrete piece of current work. bug — behavior that needs correction. report — an observation, incident or customer finding. principle — a reusable rule for making decisions. learning — a lesson supported by experience or evidence. supplier — facts about an external service or supplier. content — a draft or plan for published material. policy — a standing rule governing operations. stance — a position on a subject and its reasoning. When the person who owns the project changes direction, parks or picks something, or overrules a plan, record it as a decision the same day, quoting them.
viewNoboard returns only current-state rows, default 50/max100, under 32,000 data characters; unfinished tasks by default, waiting/needs_review/blocked rows first. Recorded release tags flag closure review. Explicit status/sort override those defaults. current preserves detailed excerpts; full is unbounded.
fieldNoTop-level field to expand with view=field.
limitNoMax rows to return (default 10). Compact pages return at most 20 rows and detail=full up to 500; view=board defaults to 50, max 100. The payload budget may return fewer; page.limit is the effective cap.
staleNoOnly in_progress tasks untouched for more than stale_days.
activeNoShortcut for "what is on my plate" — status open + in_progress. Ignored if an explicit status is given.
cursorNoOpaque next_cursor from the previous page, valid only with the original filters and view. It cannot be combined with offset.
detailNoThe "full" value includes complete descriptions instead of compact excerpts.
offsetNoOptional fresh offset traversal. Cursor provides checked continuation; the two fields cannot be combined.
statusNoWork records only.
task_idNoOptional task ID beginning with tsk_ for a bounded current-state read instead of a list. Comments and activity are retrieved separately through tasks_get. A short prefix resolves when unique; an ambiguous prefix returns candidates.
assigneeNoFilter to tasks assigned to this person.
event_idNoHistory event ID for a field expansion; kind is repeated.
parent_idNoFilter to sub-tasks of this parent; the string "null" selects only top-level tasks without a parent.
project_idYesProject ID (UUID), subdomain, or slug, resolved server-side; 'default' is the organization's shared task board.
stale_daysNoStaleness threshold in days (default 7). Also controls the per-row `stale` flag.
waiting_onNoFilter explicit waiting signals; requires view=board. none selects tasks with no recorded wait.
include_archivedNoDefault false. Only affects results when a type filter is present: archived rows are hidden unless this is true.
include_supersededNoDefault true for task history/search; false excludes records replaced by a superseded_by pointer or supersedes relationship. Memory recall defaults to false.
review_for_closureNoSurface-only review queue returning report rows whose parent task carries a shipped_in version, annotated with resolved_by_version. It does not change status and ignores the other filters.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond readOnlyHint/idempotentHint: discloses default page sizes and payload budgets, that pages are not auto-concatenated, that keyset ordering can skip or repeat rows during live edits, that omitted fields are partial, that detail=full explicitly permits unbounded descriptions, and that review_for_closure ignores other filters. These are exactly the behaviors an agent would otherwise get wrong.

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?

No filler sentences; every clause carries information and behavioral caveats are front-loaded after the opening verb. The telegraphic, fragment-heavy style ("Fields in omitted are partial", "review_for_closure reports its source candidate limit") trades readability for density, which weakens structure slightly.

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?

For a 24-parameter, no-output-schema read tool this covers the high-risk areas: pagination mechanics, ordering instability, partial vs unbounded detail, view-specific defaults, and sibling routing. Remaining gaps (row shape, page object fields) are lower risk since the agent can observe them from the response.

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; the description earns more by adding cross-parameter semantics the schema states only thinly — cursor continuation requires the original filters and view, offset cannot be combined with cursor, and task_id switches the call from a list to a bounded single-record read. It still assumes familiarity with the page object (page.limit, page.next_cursor) rather than defining it.

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?

States a specific verb and resource ("Read tasks") and immediately enumerates the distinct read modes (board scan, default compact page, detail=full, task_id single-task read). It explicitly separates itself from siblings: tasks_get for history/field expansion, tasks_overview for direction, tasks_summary for counts.

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

Usage Guidelines4/5

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

Routing to alternatives is explicit and repeated ("tasks_get covers history/field options", "tasks_overview covers project direction and work", "tasks_summary gives counts", "memory_search durable guidance"). What it lacks is crisp conditional phrasing (do X when Y) for view selection; the reader must infer when board vs current vs history applies from the schema's view enum rather than the description.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources