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

Annotations already establish a safe read operation, and the description adds genuinely non-obvious behavior: the call is free, failed trainings are refunded, and training latency ranges from minutes to hours. The anti-polling warning is operational guidance the agent cannot get from any structured field.

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?

Three short sentences, front-loaded with the resource and states, then the optional-parameter behavior, then cost and timing constraints. No filler and no repetition of the title.

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 two-optional-parameter read tool with no output schema, the description covers states, cost, timing, and polling behavior well. The remaining gap is that 'the recent ones' is unquantified, so the agent does not know how many results to expect or whether any paging exists.

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 semantics for order_id: omitting it changes the call from a single-order lookup into a recent-list query. That meaning is not captured by the schema's 'order id from create_wake_word' note.

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?

Names a specific resource (the user's wake-word trainings) and a specific operation (report status), and enumerates the possible states (queued, training, ready, failed). This is clearly distinguishable from create_wake_word or download_wake_word without opening any 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?

Gives clear conditional guidance: pass order_id for a specific order, omit it to list recent trainings. It also gives negative guidance ('do not poll in a loop'), which is rare and useful. It stops short of naming a preferred alternative for waiting on completion, so it is not a full 5.

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