list_deliveriesRetrieve delivery state and failure records for a monitor, crawl, or batch by monitorId or jobId, with cursor and state filters to inspect delivery status.
Page through delivery state and failures, for a Monitor (monitorId) or a crawl or batch (jobId, the taskId). Defaults to 20 compact results.
| Name | Required | Description | Default |
|---|---|---|---|
| debug | No | ||
| jobId | No | ||
| limit | No | ||
| state | No | ||
| cursor | No | ||
| monitorId | No | ||
| destinationId | No |
Changes observed during successful MCP inspections.
v0.7.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds that results are paged and default to 20 'compact' results, which is useful context. It omits pagination semantics (cursor behavior), auth requirements, and what state/failure data actually looks like.
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?
A single front-loaded sentence with no filler that leads with the verb and the paging/default behavior. It is dense but readable; the parenthetical 'jobId, the taskId' phrasing is slightly awkward and mildly muddies an otherwise tight statement.
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?
For a 7-parameter list tool with no output schema and no required params, the description covers the primary selectors and the default result size, and output format need not be explained. It is missing guidance on cursor usage and the purpose of destinationId and debug, and the stray taskId reference is an incompleteness.
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 0%, so the description carries the burden for 7 params. It does add selector meaning for monitorId and jobId and implies the state filter and the limit default of 20. But it leaves debug, destinationId, and cursor unexplained, and confusingly references a 'taskId' that does not appear in the schema — a notable gap given zero 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?
States a specific verb (page through) and resource (deliveries) with scope (state and failures), and names the two selecting entities (monitorId for monitors, jobId for crawl/batch). This distinguishes it from get_delivery (single item) and retry_dead_letter in the sibling set. It stops short of explicitly contrasting with list_delivery_destinations, which is a different resource.
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 usage by explaining the two scoping modes (a monitor vs a crawl/batch), which tells the agent when each id applies. However, it gives no explicit when-to-use guidance against sibling tools like get_delivery or retry_dead_letter, and no exclusions. Usage is inferable but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.