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

Annotations declare destructiveHint=true, but the description carefully qualifies this: 'there is no destructive default, so nothing changes unless you name the change,' and each verb's effect is spelled out (complete captures a visibility snapshot, dismiss drops from queue, reopen reverses, assign requires membership). With annotations already covering the safety profile and idempotency=false, this adds real context but doesn't cover concurrency, rate limits, or partial-failure behavior. No contradiction with destructiveHint — it explains rather than denies it.

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?

Front-loaded with a one-sentence purpose, then a sibling contrast, then a bulleted verb dictionary, then access/error notes, then a compact Args block. Every sentence earns its place; the verb list is effectively documentation of the enum's meaning and saves the agent from guessing.

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 multi-verb mutation tool with no output schema and thin schema descriptions, the description supplies the missing pieces: every valid action and its effect, conditional parameter requirements, access bar, and the failure mode (clear error not silent no-op). An agent has enough to invoke any of the ten verbs correctly without additional context.

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 14%, so the description must carry the burden. It does: conditional requirements are stated precisely (snooze_until required for snooze, assignee for assign, note for note and optional on complete/dismiss/reopen/start/snooze), formats are given ('2026-07-01' or ISO datetime), assignee is scoped ('must be a member with access to this brand'), and action_id provenance is noted ('get it from get_actions'). It neglects user_intent and brand_id semantics, which keeps this off a 5.

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 (act on) and resource (one recommendation in the brand's action queue), enumerates all ten action values, and explicitly contrasts with the sibling get_actions ('get_actions reads the queue. This is how you move an item in it'). An agent can distinguish read vs write without opening either schema.

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?

Strong where-to-start guidance: names the sibling reader, explains the loop (list then act), and gives preconditions (Editor access, same bar as in-product Actions page) and an error contract for bad state moves. It never says when NOT to use it (e.g. bulk operations, other queue tools like get_portfolio_actions), so it stops just short of a 5.

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