Skip to main content
Glama

list_changes

Read-only

Lists active change IDs with sorting and pagination so you can select one to check its status or read its details.

Instructions

List active change IDs, sorted and paginated. Select an ID, then change_status/read_change. Stale or cross-project cursors fail.

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_changes"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNo
cursorNo
workspacePathNoTrusted absolute project path from this chat; pass on every call. null selects personal storage. Omission uses only the environment default.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.5.1

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds real behavior beyond that: results are sorted and paginated, and stale or cross-project cursors cause failures. It does not say how the next cursor is surfaced or what a page looks like, which matters since there is no output schema.

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?

Three short, front-loaded sentences with no filler: capability first, then follow-up routing, then the failure condition. The cursor warning is telegraphic and would benefit from stating the remedy (re-list from scratch) in the same breath.

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

Completeness3/5

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

With no output schema, the description should carry the return shape, but 'List active change IDs' only implies bare identifiers without confirming pagination metadata. Nor does it state the default page size or how to restart after a cursor failure, so gaps remain for a paginated listing tool.

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 coverage is only 33% – limit and cursor have no schema descriptions – and the description only partially compensates by implying cursor semantics ('stale or cross-project cursors fail'). It says nothing about the limit bounds or default, leaving half the parameters to be inferred from the raw schema constraints.

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 with scope qualifiers: 'List active change IDs, sorted and paginated.' The scope word 'active' and the ordering/pagination traits let an agent distinguish this discovery call from change_status and read_change, which the description explicitly names as follow-ups.

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?

'Select an ID, then change_status/read_change' clearly frames this as the entry/discovery step in a workflow and points to the next tools. It stops short of explicit exclusions (e.g., when to use list_board_proposals or list_project_documents instead), so it is strong but not complete routing guidance.

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