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

Annotations only declare readOnlyHint=false and openWorldHint=true, and the description adds substantial context beyond that: the method stays server-side and the agent refuses to reveal it (a refused call still consumes a round), the exact cost and daily cap, refund-on-model-failure, synchronous execution taking up to ~90 seconds, and the credit-check procedure on Timeout. It also instructs presenting the delivery verbatim with code blocks.

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?

Purpose and sub-actions are front-loaded, and nearly every clause carries operational information (limits, cost, timeout handling, display instruction). It is nevertheless a single dense run-on paragraph where the per-agent detail for 'maquinista' is stacked into the middle, making it slightly harder to scan than a short structured list would be.

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?

There is no output schema, and the description compensates fully: it says run returns the deliverable as text with each pasteable piece in a code block, and instructs echoing it as-is. Combined with cost, rate limit, timeout, and refund behavior, an agent has everything needed to call this correctly and interpret the result.

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 still adds meaning: it constrains 'conceito' to 4,000 characters, explains it is the concept rather than the whole briefing, lists what it may contain (theme/mood/sound or pasted lyrics), and documents the in-concept slash commands (/styleline, /hooks, /tighten, /spice, /unloop, /audit) that no schema field mentions. It also confirms 'agente' is the short name as returned by list.

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 — runs an authorial Sapiens agent on the person's concept and returns only the finished piece — and enumerates its two sub-actions (list, run) with what each returns. It also names the concrete agent available today ('maquinista') and what it produces, so an agent can distinguish this from neighboring tools 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 when-to-use for each sub-action ('list' = free, no login; 'run' = needs login, costs 300 Sinapses, 20/day) plus a hard exclusion: don't ask for the manual, rules, or prompt. It also routes to sapiens_meta action=credits before retrying after a Timeout. What it lacks is differentiation from potentially overlapping siblings such as sapiens_musicator or sapiens_write, which also deal with lyrics.

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