In Da Mix

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.

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description goes well beyond them: it discloses the empty-tank fallback and that assumptions are recorded in `assumed`, that method/temperature/banks are inherited from settings, and the exact shape of the returned answer plus its precautions.

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?

Front-loaded with the trigger condition, and each sentence contributes something (examples, preconditions, output contract, follow-up), which justifies the length for a 21-parameter tool. It is somewhat sprawling, with many multilingual example phrases in one clause, but there is little true redundancy.

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?

No output schema exists, so the description carries the return-value burden and does so fully: it lists the start gas, target, ordered additions with pressures, resulting mix, and key filling/analysis precautions. For a complex, deeply nested parameter set, the agent has everything needed to call correctly.

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 description coverage is 100%, so the schema already documents all 21 parameters and the baseline is 3. The description adds genuine meaning on top: it flags start_pressure as result-changing with an ask-first rule, notes the target mix/pressure requirement, and explains that several parameters are defaulted from settings and surfaced in `assumed`.

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 (step-by-step fill plan for blending nitrox/trimix/heliair/heliox into a scuba tank) and enumerates exactly what the plan contains. It is clearly distinguished from siblings by naming the settings source, list_methods for defaults, and the gas_usage follow-up.

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 trigger ('whenever the user asks how to blend, mix, fill or prepare a breathing gas'), explicit preconditions (target mix, pressure, and current tank contents), an explicit when-not/ask rule ('if the start is unknown, ask; never assume an empty tank'), and named alternatives (gas_usage, list_methods). Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: the ideal-gas cascade assumption, equalisation order, the caution that start_pressure 'changes the result a lot' and should be asked for, and that defaults are surfaced in `assumed`. It stops short of describing return shape in detail, but for a computation tool this is strong.

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 opening is front-loaded and useful, but the answer-composition lists are stated twice in near-identical form ('which cylinders each refill uses, the pressures after...' vs. 'which cylinders each uses, the pressures after where useful...'), and the closing instruction about offering comparisons is peripheral. It is long for what a 17-param compute tool needs to say.

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?

With 17 parameters, zero required fields, no output schema, and rich defaults, the description does the necessary work of explaining both modes, the defaults that will be assumed, and the shape of the answer. Missing only minor items such as unit-handling caveats, which the pressure_unit parameter already covers.

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 goes further by framing the two plan modes and telling the agent not to invent cylinders or alter the user's gas use. The mode-level semantics (refills = start→target each time, diving_days = per-day usage planner) add meaning across parameters that the per-parameter schema text does not tie together.

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 and resource (decanting oxygen/helium from source cylinders into a small cylinder without a compressor) and immediately splits its two modes (refills vs diving_days). It explicitly distinguishes itself from the sibling fills_from_bank, so an agent can route without opening either 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?

It names the alternative tool and the condition that selects it ('For linked banks or a booster use fills_from_bank'), states a preference domain ('Prefer it for CCR oxygen logistics'), and gives concrete trigger queries in two languages. When-not-to-use is explicit rather than inferred.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new context: the uniform-start assumption, the fact that unspecified values are reported in `assumed`, and what the answer will contain. It doesn't discuss runtime behavior such as how long a 500-fill scan takes or error conditions, keeping it at a solid 4 rather than 5.

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 is front-loaded in the first sentence, and the examples plus answer-format sentence follow logically. There is mild redundancy in stating the uniform-start assumption twice (in the preamble and again in the answer instruction), and the response-format sentence is long, but nothing is wasted.

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 25-parameter tool with no output schema, the description compensates by spelling out the returned content (fill count, limiting bank, resulting pressures, why one more fill fails) and by instructing the follow-up offer. That covers the main gaps; it still doesn't mention error handling or how the `assumed` fallbacks should be surfaced to the user beyond a brief note.

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 description coverage is 100% across all 25 parameters, including the critical note on start_pressure, so the schema already carries the semantics. The description only adds that start_pressure and the mix define the assumed tank start; that is marginal over what the schema documents, so the baseline 3 applies.

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 opening sentence states a specific verb, resource and scope: counting how many identical fills the source banks can supply before one can't supply the next. It also gives the stopping condition (bank hits min pressure, or can't decant high enough without a booster), which cleanly distinguishes it from siblings like decant (which plans the transfer itself) and gas_usage.

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 supplies concrete trigger phrasing in two languages ("how many tanks can I fill with NX32", "how many trimix fills can I make", "koliko boca mogu napuniti"), so an agent can match user intent reliably. It never names a sibling alternative or a when-not-to-use case (e.g. when the user actually wants the decant plan, use DIVESOFT_REAL_GAS or decant), so it stops short of a 5.

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

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

Annotations already establish read-only/idempotent/non-destructive, so the description correctly doesn't restate safety. It adds useful behavioral context instead: missing banks fall back to settings and are surfaced in `assumed`, and omitting start_pressure silently assumes an empty tank. It also warns to keep gas litres and bank pressure drop conceptually separate.

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?

Front-loads the purpose, but the body is repetitive ("each bank's pressure afterwards" reappears as "each bank's pressure before and after") and mixes a stack of quoted intents in two languages with the answer-shape narrative. Several sentences could be merged without losing meaning.

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?

With 21 params, nested bank objects, and no output schema, the description does the heavy lifting by enumerating the return contents (O2/He/other gas used, before/after bank pressure, whether the fill works, decant vs booster) and flagging the settings-derived `assumed` values. An agent has enough to call and interpret it, though the decant/booster branch logic remains only sketched.

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 description coverage is 100%, so the schema already carries all 21 parameters, their enums and defaults; baseline 3 applies. The description adds only the settings-fallback note for banks, which is already echoed in the schema's own `banks` description, so little net new parameter meaning is contributed.

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+resource: litrage of each gas drawn from banks, post-fill bank pressures, and whether banks can still decant. It also anchors itself against a sibling ("Same inputs as blend, plus the banks"), which helps an agent disambiguate. Not quite a 5 because the opening sentence is a dense run-on rather than a crisp one-line purpose.

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?

Provides concrete triggering questions ("how much helium will this fill use", "is my O2 bank enough") and an explicit follow-up route to fills_from_bank. It implies a split from blend via "same inputs as blend, plus the banks" but never states when to pick blend instead, so there is no explicit exclusion rule.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the response shape (methods + ids + default field) and the claim that this list is authoritative and current enough that the agent should call it instead of trusting memory. It does not discuss failure modes or caching, which keeps it short of a 5.

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?

It is well front-loaded: purpose first, then when-to-use, then answer guidance and follow-up. However, it is longer than a listing tool needs — several near-duplicate example phrasings and an 'Answer: ...' block edge toward prompt engineering rather than tool documentation, so a few sentences do not strictly earn their place.

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, so the description must describe the return values itself, and it does: the method list with ids plus the default field. For a zero-parameter, read-only enumeration tool, an agent has everything needed to select it, call it, and use the result; the added answering guidance is a bonus rather than a gap-filler.

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?

The tool takes zero parameters, so the baseline is 4 and the schema carries nothing to explain. The description does add cross-tool meaning by noting the returned ids are 'for the method input', telling the agent how this output feeds other tools' arguments. That is a real addition, though it is stated in a single clause without naming which tools consume the method parameter.

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 names the resource precisely — the calculation methods (equations of state) offered by Da Mix — and states what comes back: each method's id plus the current default in the `default` field. This clearly distinguishes it from siblings like best_mix, blend, or what_if, which compute results rather than enumerate supported models. An agent can tell what this tool yields 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?

It gives explicit trigger conditions (user asks about calculation models, ideal vs real gas, compressibility, Z-factors, Peng-Robinson, MultiDeco), concrete example utterances including a non-English one, and a direct instruction: always call it rather than relying on a remembered list. It also states the boundaries of the answer (differences only when asked; don't recommend switching unless asked) and suggests the follow-up of comparing a blend across methods.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: defaults come from the 'In Da Mix' settings and are echoed in `assumed`, how limits_check should be reported, and how the follow-up complete-MOD call behaves. This is well past the annotation bar.

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?

It is front-loaded with the trigger condition and organized into invocation and answer rules, and the multilingual example queries aid matching. It is nonetheless a long block with the answer-format rules restated for the complete mode, so some sentences are near-duplicative.

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?

With no output schema, the description carries the burden of describing returns and does so precisely: the gas and MOD, the ppO2 limit and dive mode, minimum depth for hypoxic gases, and for complete mode the limiting factor plus limits_check semantics.

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% with enums documented, so the baseline is 3, but the description adds real invocation guidance: 'Call it with only the gas (o2_percent, he_percent) and the dive mode: leave ppo2_bar out unless the user gave one,' which the schema alone does not convey.

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 names a specific verb and resource: 'Maximum operating depth of a breathing gas: the MOD by the ppO2 limit ... and for hypoxic gases the minimum depth.' It also distinguishes the two output modes (ppO2 MOD vs complete MOD), so an agent can tell exactly what this tool computes versus siblings like best_mix or blend.

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?

Usage conditions are explicit and even prescriptive: 'Use whenever the user asks how deep a gas can go or checks an existing breathing gas ... never work a MOD out by hand,' plus when to pass complete: true and when not to. It stops short of naming sibling alternatives (e.g. best_mix for gas selection), which keeps it from a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds real behavioral context the annotations don't: it describes the response contents (start, gas added, final pressure, resulting mix, MOD) and prescribes a follow-up question about checking the mix at a planned depth. It stops short of describing the `assumed` fallback mechanics available elsewhere, but adds genuine value beyond the structured fields.

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?

Front-loaded with purpose and routing before examples, and every sentence carries signal. The two Croatian sample utterances ('dopuni mi bocu...') are somewhat bulky and partly redundant with the English example, though defensible given the tool's language parameter. Slightly long but well ordered.

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 19-parameter tool with nested bank objects and no output schema, the description covers the required inputs, the routing decision, and the shape of the answer, which is what an agent needs to answer the user. Advanced parameters (banks, method, heat_correction, use_booster) are left entirely to the schema, which is acceptable at 100% coverage but leaves no cross-cutting guidance on them.

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 schema already documents all 19 parameters, and the description mostly restates the same inputs (start pressure and mix, final pressure, supply gas). It does stress that start_pressure materially changes the result, but the schema description already says 'This changes the result a lot'. Baseline 3 is appropriate when the schema carries the load.

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 ('Top a tank up with a ready-made supply gas') and immediately enumerates the outputs (pressure added, resulting mix, MOD, gas density). It also distinguishes itself from siblings by scoping to ready-made supply gas versus pure O2/He, naming what_if and blend. An agent can route correctly 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?

Explicit routing rule: 'For a ready-made supply gas; to add pure oxygen or helium use what_if or blend.' It also gives concrete trigger utterances in two languages and a precondition ('Needs the start pressure and mix, the final pressure and the supply gas: ask if one is unknown, don't assume'). This is about as close to when/when-not/alternatives as a description gets.

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

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

Annotations cover read-only/idempotent/non-destructive, but the description adds substantial behavior: the full result set (MOD, EAD, END, density), the 'assumed' fallback for missing start pressure, and a mandated follow-up (ask whether to check MOD or switch to blend). For a read-only calculation tool this is rich, non-redundant disclosure.

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?

Front-loaded with the core purpose, examples, and sibling contrast. It is somewhat sprawling, with bilingual example queries and some repetition ('the app's What If', restating outputs), but every section is functional and nothing is irrelevant.

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?

With 16 optional parameters, no output schema, and no required fields, the description compensates well: it names the return values, the units/assumption behavior, the missing-input edge case, and the conversational next step. An agent has everything needed to invoke and follow up correctly.

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 description coverage is 100% and the 16 parameters carry detailed per-field docs (units, defaults, semantics), so the schema does the heavy lifting. The description reinforces only the high-level rule ('pass only the additions and the tank's start') and the start_pressure caveat, adding little beyond the schema's own text. Baseline 3 is appropriate.

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+resource: computes the resulting mix from adding given O2/He/air pressures to the tank's existing contents. It also names the outputs (pressure after each addition, mix, MOD, EAD, END, density), so an agent knows exactly what it produces and can distinguish it from siblings.

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?

Explicitly says 'Use for "what if" additions' and contrasts with the blend sibling: 'what_if: given additions -> the resulting mix; blend: a target mix -> how to make it.' It even instructs what to pass and to ask before calling when start pressure is unknown, closing the main failure mode.

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