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

Annotations are minimal (readOnlyHint=false, openWorldHint=true), so the description carries real weight and delivers: per-provider pricing with minimums, async polling contract (generate → generation-status until 'ready'/'failed'), refund behavior on failure, and the privacy rule that scenes stay with the author and do not enter the shared acervo. It also notes generated effects do enter the acervo as kind=sfx. Docked one point because the list/get return shape is only partly disclosed (count/items, title/url/durationSeconds) and pagination behavior is unaddressed.

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?

Dense and front-loaded: the bank definition and the free read actions come first, paid generation and scene follow. Every clause carries information — no filler. The weakness is structure: a single unbroken wall of prose across seven actions and 20 parameters that would scan far better as a short bulleted action map, which raises the risk of an agent skimming past the scene/status pairing.

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 7-action, 20-parameter tool with no output schema, the description covers everything an agent needs to call it correctly: which actions are free vs. paid, the async completion pattern for both long-running actions, failure/refund semantics, result usage, and the sibling handoff for music. The explicit privacy note on scenes is a detail an agent could not infer from any structured field.

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 baseline is 3, but the description adds coordination the schema cannot: the generate→generation-status(generationId)→ready(audioUrl) loop, the cost-escalation-by-second model, and the practical instruction to take the returned `url` straight into ffmpeg. It also disambiguates durationSeconds per action and confines promptInfluence to provider='elevenlabs'. Mostly additive, though several details (provider pricing, mood enum, pitch/speech rates) are duplicated from 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?

States a specific resource (banco de som da casa: trilha pronta + efeito sonoro) and enumerates each sub-action with its own verb and output (categories lists moods, list searches with filters, get returns 1 item by audioId). It also draws the boundary against siblings: new music/trilha goes to sapiens_musicator, and scene/generate are named as distinct write actions. An agent can pick the right action without opening the 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?

Explicit routing: read actions are declared 'públicas, sem auth', while generate and scene are flagged 'COBRA Sinapses, exige login'. It gives the escalation path verbatim — 'Não achou o efeito? generate' — and hands off music generation to sapiens_musicator. When-not-to-use is stated for the short-effect limit (1-15s) versus full tracks.

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