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

Goes well past the annotations: discloses cost (20 credits), async job_id flow with ~1–2 min latency, owner-only rendering, transcription by default (skippable via notes), and unusually honest cancel semantics (no stop for a running training; it runs to completion and credits are spent, only plane-queued jobs are refunded). Annotations only say it mutates and is open-world, so this added context is substantial, though the 'queued at the plane' refund rule is slightly ambiguous in phrasing.

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 but front-loaded: the core action and requirements come first, then result shape, then async/cancel details. A couple of the semicolon-chained asides (refund nuance, transcription note) are compressed to the point of near-illegibility, and the cancel paragraph is lower value than the setup guidance.

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 12-parameter async job tool with no output schema, the description covers the full lifecycle an agent needs: how to supply audio, how to choose instrument, default transcription, cost, result fields (lora_id, name, trained windows, loss first→last, and the ready-made `use` render args), waiting, and failure/refund behavior. Nothing essential is missing.

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 adds real meaning the schema cannot: that instrument selects the model voice the adapter trains on (shamisen trains as acoustic_guitar, whistle as flute) and that notes are auto-transcribed unless supplied. This is genuine interpretive value, not restatement.

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 — training a private LoRA adapter on the serving instrument model from uploaded audio — and immediately links the result to doseedo_render_midi, which clearly separates it from the rendering sibling. No ambiguity about what is produced (a lora_id usable in that sound).

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?

Gives explicit input requirements (30 s–3 min, one solo dry instrument, up to 8 takes, first 3 min used, ≥8 s each), tells the agent how to pick the instrument (call doseedo_instruments, pick the nearest catalog voice, with concrete mappings), and routes to doseedo_list_jobs for prior runs and doseedo_wait_task for completion. This is when-to-use guidance with alternatives named.

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