Skip to main content
Glama

List work cards

project_card_list
Read-onlyIdempotent

Filter and list project cards by status, area, type, priority, parent, or claim. Pinpoint specific work items before starting.

Instructions

List cards filtered by status, area, type, priority, parent or claim. Use before starting work; use project_search for full-text.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
areaNoKeep only these areas. Project-declared, so the accepted values vary; project_workspace reports them.
tagsNoKeep cards carrying any of these tags.
typeNoKeep only these card types. One of: epic, idea, feature, bug, task, audit, docs, chore.
limitNoMaximum cards to return.
offsetNoSkip this many matches before the page starts.
parentNoKeep only direct children of this card ID.
statusNoKeep only these statuses; any match passes. One of: backlog, next, doing, review, blocked, deferred, done, discarded.
priorityNoKeep only these priorities. One of: critical, high, medium, low.
claimedByNoKeep only cards claimed by this actor.
unclaimedNoKeep only cards nobody has claimed.
updatedSinceNoOnly records updated on or after this date. YYYY-MM-DD; an RFC 3339 timestamp is read as its date.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum this page could contain.
totalYesMatches before offset and limit were applied.
offsetNoOffset this page started at.
recordsYesCards matching the filters, in list projection.

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed16 schema fields changedv0.5.4
    • addedInput schema / properties / area / description
      Added value: +"Keep only these areas. Project-declared, so the accepted values vary; project_workspace reports them."
    • addedInput schema / properties / claimedBy / description
      Added value: +"Keep only cards claimed by this actor."
    • addedInput schema / properties / limit / default
      Added value: +50
    • addedInput schema / properties / limit / description
      Added value: +"Maximum cards to return."
    • addedInput schema / properties / offset / default
      Added value: +0
    • addedInput schema / properties / offset / description
      Added value: +"Skip this many matches before the page starts."
    • addedInput schema / properties / parent / description
      Added value: +"Keep only direct children of this card ID."
    • addedInput schema / properties / priority / description
      Added value: +"Keep only these priorities. One of: critical, high, medium, low."
    • addedInput schema / properties / priority / items / enum
      Added value: +[
      +  "critical",
      +  "high",
      +  "medium",
      +  "low"
      +]
    • addedInput schema / properties / status / description
      Added value: +"Keep only these statuses; any match passes. One of: backlog, next, doing, review, blocked, deferred, done, discarded."
    • addedInput schema / properties / status / items / enum
      Added value: +[
      +  "backlog",
      +  "next",
      +  "doing",
      +  "review",
      +  "blocked",
      +  "deferred",
      +  "done",
      +  "discarded"
      +]
    • addedInput schema / properties / tags / description
      Added value: +"Keep cards carrying any of these tags."
    • addedInput schema / properties / type / description
      Added value: +"Keep only these card types. One of: epic, idea, feature, bug, task, audit, docs, chore."
    • addedInput schema / properties / type / items / enum
      Added value: +[
      +  "epic",
      +  "idea",
      +  "feature",
      +  "bug",
      +  "task",
      +  "audit",
      +  "docs",
      +  "chore"
      +]
    • addedInput schema / properties / unclaimed / description
      Added value: +"Keep only cards nobody has claimed."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "limit": {
      +      "description": "Maximum this page could contain.",
      +      "type": "integer"
      +    },
      +    "offset": {
      +      "description": "Offset this page started at.",
      +      "type": "integer"
      +    },
      +    "records": {
      +      "description": "Cards matching the filters, in list projection.",
      +      "items": {
      +        "additionalProperties": true,
      +        "description": "A record in list projection: identity and frontmatter without the Markdown body.",
      +        "properties": {
      +          "bodyBytes": {
      +            "description": "Size in bytes of the body this projection left out.",
      +            "type": "integer"
      +          },
      +          "created": {
      +            "description": "Creation date, YYYY-MM-DD.",
      +            "type": "string"
      +          },
      +          "id": {
      +            "description": "Stable record ID: T-0042, DOC-0003, CHG-0101, ADR-0009.",
      +            "type": "string"
      +          },
      +          "incomingTotal": {
      +            "description": "How many other records link to this one.",
      +            "type": "integer"
      +          },
      +          "kind": {
      +            "description": "Record family: card, doc, change, release or memory.",
      +            "type": "string"
      +          },
      +          "path": {
      +            "description": "Repository-relative path to the Markdown file.",
      +            "type": "string"
      +          },
      +          "recordType": {
      +            "description": "Type within the family — a card's type, a document's kind, a memory record's collection.",
      +            "type": "string"
      +          },
      +          "status": {
      +            "description": "Lifecycle status, in the vocabulary of this record's family.",
      +            "type": "string"
      +          },
      +          "title": {
      +            "description": "Human-readable title.",
      +            "type": "string"
      +          },
      +          "updated": {
      +            "description": "Date of the last write, YYYY-MM-DD.",
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "total": {
      +      "description": "Matches before offset and limit were applied.",
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "records",
      +    "total"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered by structured data. The description adds the filtered-list semantics and the 'use before starting work' workflow context. The openWorldHint=false is slightly in tension with the description implying exhaustive results, but this is reasonable for a filter-based read tool.

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

Conciseness5/5

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

Two tight sentences: the first enumerates the filter dimensions in a compact list, the second states usage context and the alternative tool. Zero waste, all information earns its place.

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

Completeness4/5

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

For a 11-parameter read tool with an output schema and strong annotations, the description is complete enough. It explains the filter scope, provides usage timing, and names the alternative. No nested-object complexity or undocumented safety concerns. Could mention pagination behavior (limit/offset) but the schema documents those defaults clearly.

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

Parameters3/5

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

Schema description coverage is 100%, with each parameter having a detailed description including enums for type, status, and priority. The description names the filter dimensions but adds little beyond the schema. Baseline 3 is appropriate since the schema carries the full burden of parameter documentation and does so well.

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?

The description clearly states the verb (list) and resource (work cards) with explicit filter dimensions (status, area, type, priority, parent, claim). It distinguishes from sibling project_search by noting the full-text alternative, and name/title reinforce the same purpose without contradiction.

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?

'Use before starting work' provides clear contextual guidance for when to invoke this tool, and it explicitly names project_search as the alternative for full-text queries. It doesn't enumerate every sibling's differentiation, but the key alternative is called out, which is sufficient given the schema provides exhaustive filter options.

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

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/illodev/workfile'

If you have feedback or need assistance with the MCP directory API, please join our Discord server