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

Annotations already declare this as a read-only, idempotent, non-destructive computation, so safety is covered. The description adds substantial behavioral context beyond that: richest O2 rounded down, helium chosen to satisfy END and gas density, CCR treated as a mathematical optimum rather than a full diluent check, and the rule that limits_check values at the limit count as compliant and margins must not be added. It does not discuss cost/rate limits, but none are implied here.

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?

The routing instruction is front-loaded in the first sentence and the dense middle covers result content and limit interpretation efficiently. It runs long, with the CCR caveat appearing twice and a block of quoted trigger phrases, but for a 10-parameter domain tool the length is largely justified.

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, yet the description spells out the answer shape (the one mix, depth, ppO2, END, gas density and the limits used), names response fields such as limits_check, all_within and assumed, and states that only one mix should be returned. Combined with 100% schema coverage and read-only annotations, an agent has everything needed to call and present 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 the baseline is 3 and the schema already explains every field and default. The description adds genuine operational meaning on top: omit the limit parameters unless the user gave them and let the In Da Mix settings supply them, and set dive_mode to CCR for any rebreather question. It also warns that a nitrox result may breach END/density and that trimix should then be requested.

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 description states a specific verb+resource: it returns the single best nitrox or trimix for a planned depth, as OC bottom gas or CCR diluent. It is immediately distinguishable from the sibling set (blend, decant, top_up, what_if, mod), which are about preparing, moving or evaluating gas rather than selecting one. The trigger phrasing ("which breathing gas to use for a planned depth") is unambiguous.

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?

It explicitly says to use this FIRST, covers paraphrases (select/recommend/optimise/compare) and even cases where the user never names the app, and gives concrete trigger examples in two languages. It also gives post-answer routing (ask whether to compare against another mix or other END/density limits) and instructions to leave limits unset unless the user supplies them.

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