CFD Pipe Flow

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

Annotations provide readOnlyHint=true, but the description goes far beyond that: it discloses that this is analytic (NO solver), explains the fidelity label ('±10 % Moody-band correlation'), mentions that 'the Colebrook value is always reported for turbulent flow', and details the exact return structure. It even describes when the output includes an 'escalate_to' field. This adds substantial behavioral context beyond the annotations, with no contradictions.

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 long but every sentence adds value: it front-loads the core purpose, covers regimes, formulas, escalation, and return fields. While it could be trimmed, the density of useful information justifies the length. It is structured logically, moving from purpose to execution details to escalation, and ends with the return JSON. Slight redundancy in explaining formula details could be condensed, but it's far from bloated.

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 physically-complex tool with eight parameters, no output schema, and no parameter descriptions, this description is remarkably complete. It covers the laminar and turbulent regimes, the exact formulas used, the conditions for Colebrook, the fidelity and band, and the full return object including escalate_to. The agent has everything needed to call the tool correctly and interpret results, even without an output schema.

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 input schema has 0% description coverage, so the description must fully compensate. It does: it explains the fluid parameter ('fluid μ,ρ from a name ... or explicit mu_pa_s+rho_kg_m3'), the flow input options ('flow_rate_lpm or velocity_m_s'), and the effect of roughness_mm ('Colebrook–White when `roughness_mm` is given'). It also clarifies the required diameter and length units. Every parameter's purpose is effectively communicated.

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 opens with 'Analytic straight-pipe pressure drop (NO solver)' and immediately identifies it as 'the fast internal-flow screen and the exact gate the OpenFOAM cfd_internal_flow solve is checked against'. This states both the verb (compute pressure drop), the resource (straight pipe), the nature (analytic, no solver), and explicitly distinguishes it from the sibling cfd_internal_flow_submit. The agent can immediately understand what the tool does and how it differs from related tools.

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 provides explicit when-to-use guidance: 'the fast internal-flow screen' for quick estimates, and 'the exact gate' for validation of the solver. It also gives an explicit escalation rule: 'Escalate turbulent cases to cfd_internal_flow_submit(turbulence='kOmegaSST')'. This tells the agent exactly when to use this tool instead of the alternative, meeting the highest bar for usage guidance.

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