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

Annotations already declare read-only, non-destructive, and closed-world behavior, but the description adds return ordering, cursor behavior, queued count, and an important caveat that workflow runs can call webhooks/functions and mutate records under the key's permissions, failing if the key is revoked, expires, or is lowered. This is meaningful context beyond annotations, though it describes run behavior more than the list call itself.

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 first sentence describes the return shape rather than leading with the list action, and the long caveat about workflow-run side effects is useful but somewhat tangential for a listing tool. It remains readable and not bloated, but could be more front-loaded.

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?

No output schema exists, so the description must explain return values; it does so with page, newest-first ordering, nextCursor, decidable runs, and queued count. It also covers multi-space and permission/revocation behavior, leaving only minor gaps such as explicit sibling routing.

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 coverage is 80%, so most parameters are already documented in the schema. The description reinforces nextCursor and the targetSpaceId multi-space flow, but does not add syntax or meaning for limit, cursor, or runId beyond what the schema provides.

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 it returns a page of workflow runs, newest first, with nextCursor and queued count, and gives the endpoint. It distinguishes a page from a single run via the runId parameter, but the description itself does not name workflows_get as the single-run alternative.

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?

Gives a clear prerequisite for multi-space accounts: call auth_verify, ask the user which space to use, and pass targetSpaceId. However, it does not explicitly say when to use this list versus workflows_get or the activity_list_* siblings; usage is implied by 'page of runs' rather than contrasted.

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