pump_npsha

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that NPSH available is computed and that a margin check occurs when NPSHr is given. It does not explain the governing equation, assumptions, required system context, or what happens when inputs are missing. This is insufficient for a calculation tool.

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 a single, terse line with no wasted words. It conveys the core purpose efficiently, though it reads more like a fragment than a complete sentence. For a tool of this simplicity, the brevity is acceptable, but it sacrifices completeness for conciseness.

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 7-parameter engineering calculation tool with no annotations and only a vague description. It does not specify the NPSH formula, units, prerequisites, or any special cases. While an output schema exists, the description alone leaves the agent with too little information to correctly invoke the tool or interpret results. This falls well below the minimum viable threshold.

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 0%, and the description only references NPSHr (the optional margin-check input). It provides no explanation of vapor pressure, density, static suction head, suction loss, surface gauge pressure, or atmospheric pressure. Since the description must compensate for the lack of parameter documentation and it does not, this is a critical gap.

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 identifies the tool as calculating NPSH available at the pump, using domain-specific terminology. It distinguishes from sibling tools like pump_tdh and pump_power by focusing on NPSH, and also hints at a margin-check capability. However, it lacks an explicit verb like 'calculate' or 'compute', making it slightly less direct.

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 description implies usage context: NPSH available is calculated, and when NPSHr is supplied, a margin check is performed. It does not provide explicit guidance on when to use this tool versus alternatives, but there are no other NPSH tools among siblings, so the context is reasonably clear. No exclusions or prerequisites are mentioned.

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