list_executions

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds behavioral context beyond them: there is NO updatedAt on executions, startDate/endDate are human-typed planning dates usually null, assignedTo is a bare unresolved user UUID, and the progress.passRate denominator divides by total cases rather than executed ones. It openly discloses these semantic traps and other gotchas an agent must know before calling.

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?

Every sentence earns its place: no redundant filler, and the opening sentence identifies what the tool returns. However, it is a ~200-word wall of prose; a bulleted breakdown per field would be much more scannable, and the density requires careful parsing by the agent. Efficient but not optimized for scanning.

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?

There is no output schema, and the description compensates fully: it enumerates the returned fields and the shape of progress (five buckets that sum to total, pass`Completeness note: passRate/completenessRate). It also enumerates the confusing fields (updatedAt absence, planning dates, unresolved UUID). It omits straightforward context such as default ordering and whether the list is newest-first or how paging responds, but those are secondary for the tool(to-find-id) core use case.

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 60%: projectId and status are richly documented, with status getting substantial guidance (case-sensitive vocabulary, rejection, label-vs-content distinction), while limit and offset have no descriptions in the schema nor any in the tool description. The description itself adds little about parameters directly — most of its detail concerns output values and the status caveat is in the schema. Paging params remain underspecified for an unannotated numeric name.

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 and object: 'List Manual Test Executions for a project.' It names the exact return columns, scopes the tool to manual executions, and differentiates itself from get_execution and get_execution_case by explaining what it is not (no updatedAt, no per-execution extended details). An agent can distinguish this from all 50+ siblings without opening other schemas.

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?

Explicit routing is given: 'Use this to find an existing execution id before adding anything sources.' It also gives an explicit when-not and alternative: when you need to know the last time an execution was worked, 'read get_execution_cases and take the newest executedAt'; and it warns the passRate here must not be compared with get_case_execution_history's. This is unambiguous selection guidance.

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