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

Annotations already declare the mutation and idempotency profile, but the description goes further by explaining the mechanics of idempotency ('pass the same idempotency_key when retrying; a repeat returns the first answer') and the real side effect that a 'Not needed' reason feeds back to the Scanner that raised the suggestion. It does not cover permissions or what the card looks like afterwards.

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?

Three short sentences, front-loaded with the action, then the parameter nuance, then the retry rule. 'as the card's dismiss does' is slightly cryptic but compact and useful for UI parity; no filler.

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 small three-parameter mutation with no output schema, the definition covers action, the key parameter semantics, and retry/return behavior. Gaps are minor (permissions, post-dismiss state of the suggestion).

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 only 33% (only idempotency_key is documented in-schema), so the description carries real weight: it clarifies that reason is optional and gives the semantically loaded value 'Not needed', and it explains retry behavior for idempotency_key. suggestion_id is left implicit as the suggestion to dismiss.

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 resource ('Dismisses a Sergio suggestion card') and anchors it to the familiar UI action. The verb 'dismiss' implicitly contrasts with the sibling accept_suggestion, but the description never names that alternative explicitly.

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 'as the card's dismiss does' framing and the note about reason='Not needed' imply when this is appropriate, but there is no explicit guidance on when to dismiss versus accept_suggestion or run_suggestion_now, and no stated preconditions.

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