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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety and repeat-safety are covered structurally. The description usefully adds that failure details and result IDs are surfaced, but says nothing about behavior when a job is still pending, what happens if neither identifier is supplied, or error semantics.

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 well-formed sentence with the action and return payload front-loaded. No filler, no restatement of the tool name.

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?

Annotations and a present output schema remove the need to explain return shape or safety, so the remaining burden is small. Still missing: which identifier to pass when, and expected polling behavior, which an agent needs in order to invoke this correctly rather than guess.

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, and it does partially: 'workflow job' maps to jobId and 'signal-processing handle' to signalId, which is genuine disambiguation. However it never states that both parameters are optional, whether they are mutually exclusive, or that at least one is required in practice — a significant gap for a zero-coverage 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 pairs a specific verb ('Poll') with a specific resource ('Discovery workflow job or signal-processing handle') and enumerates the payload (status, progress, result IDs, failure details). This cleanly separates it from write-path siblings such as signals_process or discovery_decide_what_to_build, though it never names an alternative tool directly.

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?

'Poll' implies a repeated-call pattern until completion, which is real usage context, but there is no explicit statement of when to call this versus kicking off or re-running work, and no guidance on how often to poll or when to stop. Usage is inferable rather than stated.

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