agent_listList durable jobs in a specified workspace, with optional state filtering and pagination to retrieve authorized job pages.
List one authorized page of durable jobs for an explicit workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| states | No | ||
| workspace | Yes | Reference to exactly one durable workspace identity. |
| Name | Required | Description | Default |
|---|---|---|---|
| items | No | ||
| next_cursor | No |
Changes observed during successful MCP inspections.
v1.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond those annotations by noting that only one page is returned and that jobs are durable. There is no contradiction between the description and the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence beginning with the verb 'List', and each phrase adds either scope, resource type, or a pagination constraint. It is concise and easily parsable, with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters, a nested workspace object, and many sibling agent_* tools, the definition is only minimally complete. It conveys pagination only through the word 'page', leaves the states filter to be inferred from the schema enum, and does not differentiate usage from agent_status or agent_result. The presence of an output schema reduces the need to describe return values, but key guidance is still missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, with only the workspace object receiving a description. The tool description alludes to pagination ('one page') and workspace scoping, but does not explain limit, cursor, or states, and therefore does not compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('List ... durable jobs') and adds a mandatory scope ('for an explicit workspace'), making the operation distinct from sibling tools such as agent_start, agent_status, and agent_result. The phrase 'authorized page' is slightly opaque, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: to enumerate durable jobs for an explicit workspace, with only one page returned at a time. It does not name alternatives or provide exclusions, so an agent must infer when agent_status or agent_result would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.