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

No annotations are supplied, so the description carries the full behavioral burden. It does disclose the computational behavior well, including the two antiscalant scenarios, the mineral-by-mineral saturation judgment, the dosing recommendation, and the pH sweep, which tells the agent this is a pure analysis operation with no stated side effects. However, it never explicitly states that the tool is read-only and non-mutating, nor does it mention runtime cost or output format, which are meaningful gaps when annotations are absent.

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 description is dense but front-loaded: the core computation and outputs come first, followed by the source reference and the usage hint. Every clause carries information about what is computed or returned, with no filler. The single long sentence is harder to scan than short bullet-like clauses would be, which keeps it from a 5.

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?

This is a complex tool with a nested water-quality object and no output schema, so the description must explain the return values, and it does: maximum recovery, limiting minerals, saturation verdicts, antiscalant dose, optimal pH, and acid/base dose. Combined with 100% schema coverage on inputs, an agent has enough to call it correctly. Minor gaps remain around result structure and units, but 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 description coverage is 100%, so the baseline is 3. The description adds some meaning beyond the schema by explaining that target_recovery_pct drives the per-item saturation judgment and antiscalant recommendation, and by revealing that the pH scan spans 2–11. It does not clarify the nested water ion fields or include_ph_table beyond what the schema already says, so the added value is moderate rather than substantial.

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 analytical operation and its outputs: scaling-limited maximum recovery with and without antiscalant, the limiting minerals (LSI, CaSO4, BaSO4, SrSO4, CaF2, SiO2, calcium phosphate), per-item saturation checks at the design recovery, antiscalant dosing recommendation, and a pH 2–11 scan for optimal pH and acid/base dose. This is far more specific than the tool name alone, and it explicitly positions itself relative to run_design, so an agent can distinguish it from the sibling design tool.

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?

The final sentence gives clear when-to-use guidance: run this before run_design to establish the recovery upper limit and decide whether acidification is needed. That sequencing instruction is exactly what an agent needs to order its calls. It stops short of stating when not to use it (for example, when a full design already exists), 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.