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

Annotations already declare a safe read-only, idempotent, non-destructive operation. The description adds useful behavior beyond that: includeActions defaults to true, pendingApprovalOnly and assignedToMeOnly scope the list, and latestOnly enables since-last-run scoping. It does not mention the projectApiKey requirement or rate/pagination behavior, but it adds meaningful context.

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 front-loaded with the purpose, then gives one compact sentence per invocation mode. Each clause maps directly to a parameter combination, with no wasted text.

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 12-parameter, multi-mode read tool with no output schema, the description covers the key invocation patterns and defaults needed to call it correctly. It still omits auth requirements and any indication of the response shape, so it is strong but not fully complete.

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 33%, but the description compensates for many parameters by explaining workflowId, limit, offset, pendingApprovalOnly, and assignedToMeOnly for listing; workflowExecutionId for single fetch; and latestOnly with branchName/userId for latest-run scoping. It omits semantics for botId and projectApiKey, which are left to the schema.

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 states a specific verb and resource: list or fetch workflow executions. It also enumerates three invocation modes, which makes the tool's purpose clear. It does not explicitly differentiate itself from nearby siblings such as list-workflow-catalog or get-execution-history.

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?

It gives explicit parameter combinations: omit identity args to list, pass workflowExecutionId for one execution, or pass workflowId plus latestOnly=true for the last run. This is strong internal guidance, though it does not name alternative sibling tools or state when not to use this tool.

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