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

Beyond the annotations the description discloses routing and audience: it lands in 'Audora's support inbox' and shows in 'the artist's Settings › Support', it is read by a person, and it should be written as prose ('what you were trying to do, what got in the way and what would have helped'). That is real operational context. There is a mild tension with openWorldHint=false/readOnlyHint=true given the submission is delivered somewhere, but nothing destructive or irreversible is claimed, so this is context-adding rather than contradictory.

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 purpose, then the kind taxonomy, then the writing guidance and the sibling routing — a sensible order with almost no filler. It is one dense paragraph of roughly ten sentences, so it is a little longer and less scannable than it could be, but each sentence carries information.

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?

With no output schema, the description still tells the agent what happens after the call (support inbox, artist's Settings), who reads it, and the permission model. Enough to call the tool correctly without further 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 coverage is 100%, so the baseline is 3, but the description genuinely disambiguates the enum values — the schema only says 'What this is about' for kind, while the description differentiates missing_capability, connector_improvement, product_improvement, bug and other with concrete examples. It also reinforces artist_asked semantics already in 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 opening sentence gives a specific verb and resource ('Send Audora feedback it will read') and immediately enumerates the five kinds, so the agent knows exactly what is being created. It also names the sibling it is not: 'For a plain "there is no tool for that", report_gap is enough.'

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 trigger ('Use it when you notice something worth fixing'), an explicit exclusion that routes to the alternative sibling (report_gap), and a stated permission rule ('You do not need the artist's permission, but set artist_asked to true when the artist asked for it'). This is close to a full when/when-not/alternative specification.

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