Orifice flow / pump capacity

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

With no annotations, the description must carry the behavioral burden. It discloses that results come from a manual table, that only pure water is modeled, and that it returns a pump pressure-level table, which is helpful. But it does not state what happens for out-of-range pressures or orifice sizes, whether results are interpolated or exact table lookups, or whether it can fail.

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 three sentences and front-loads the core purpose: flow calculation and pump capacity check. The multi-orifice hint and the note about returning the pressure-level table are useful and not wasteful, though the sentence about the pump table could be slightly better connected to the main purpose.

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 simple three-parameter calculation tool with no annotations and no output schema, the description is largely complete: it states the inputs, the main output (flow and supply check), and an extra output (pressure-level table). It leaves some gaps around output units, edge-case behavior, and the exact form of the supply check, but the core is covered.

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 three parameters in detail, including ranges and units. The description adds some meaning by encouraging multiple orifice entries for multi-head scenarios, but it does not explain whether pressure_psi and pressure_bar are mutually exclusive, how they interact, or what default pressure is used when neither is supplied.

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 clearly states a specific calculation: water flow through a pure-water orifice and whether the JETS 3.8/60 pump can supply it, plus a pump pressure-level table. It is distinct from generic pump-info tools, but it does not explicitly contrast itself with the sibling get_pump_info, leaving slight ambiguity about which tool to use for pump data.

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 some usage context by suggesting 'Give several orifices to check a multi-head or orifice + leak scenario', which implies when multiple values are useful. However, it provides no explicit when-to-use vs alternatives, no exclusions, and does not say when not to use it versus get_pump_info.

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