Skip to main content
Glama

List task lists

list_tsk

Browse task lists to retrieve IDs, titles, statuses, and refs before opening one by ID. Filter by glob pattern and page through results for targeted access.

Instructions

Ids, titles, statuses, and refs of task lists in the configured task list base directory, one page at a time, for context before addressing one by id. 'ref' is an opaque, extensionless identifier -- not a filename to read from disk -- for documents that have no assigned id; use it with the get_tsk tool instead. An optional glob pattern (e.g. 'dead*') filters the listing to the task lists whose id matches it, case-insensitively; glob=None (the default) lists everything, and an empty string matches nothing. max_results/offset control paging (default page size 25, capped at 100); out-of-range values are clamped, not errored.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
globNo
offsetNo
max_resultsNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
totalYes
offsetYes
resultsYes
truncatedYes
error_countNo
max_resultsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.36.0

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations the description carries the full burden and delivers: it warns that 'ref' is opaque and not a filename to read from disk, documents paging behavior with default and cap, and states that out-of-range values are clamped rather than errored. Missing only auth/permission requirements and any note on total-count or ordering behavior.

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?

One densely packed paragraph, front-loaded with what is returned, then the ref caveat, then the filtering and paging rules. Every sentence carries information, though the middle 'ref' clause is slightly long-winded and could be tightened.

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?

An output schema exists so return values need not be explained, and the description nonetheless covers filtering, paging, defaults, clamping, and the opaque-ref handoff to get_tsk. Nothing an agent needs in order to call this correctly is absent.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must fully compensate, and it does: glob semantics (case-insensitive, matched against id, None=all, empty=nothing, worked example 'dead*'), and max_results/offset (default page size 25, hard cap 100, clamping). Every parameter is documented beyond the schema's bare types.

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?

Specific verb+resource ('List task lists') plus the exact fields returned (ids, titles, statuses, refs) and the base directory they come from. It also implicitly distinguishes itself from get_tsk by framing itself as the tool for browsing 'before addressing one by id'.

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?

Explicitly states the use context ('for context before addressing one by id') and routes the agent to get_tsk for the 'ref' case, naming the alternative tool by name. It stops short of an explicit 'do not use this to fetch a single task list' exclusion, but the routing guidance is clear.

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