cfd_mesh_independence_submit

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

With no annotations, the description carries the full burden and does so: it discloses async execution ('one job for the whole ladder', poll job_result), an OpenFOAM dependency with a documented degradation shape ({ok:false, reason, install}), and the cost model (cube-of-refinement_ratio, ~11x cells at 3 levels of 1.5). It also explains the non-obvious end_time semantics as a cap on the coarsest level only, which is exactly the kind of hidden behavior an agent needs to budget a fine-mesh study.

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 core purpose is front-loaded in the opening line, and the two-family bullet structure maps cleanly onto the schema's branches. It is long, but for a 19-parameter async job every section (degradation, cost, end_time, return shape) adds operational information rather than filler; formatting is heavy but not wasteful.

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 annotations and no output schema, the description still tells the agent everything needed to call and consume the tool: it spells out the per-family parameter requirements, the async job_id/status/cache_hit return, the tool to poll (job_result), and even the nested result fields (levels, grid_convergence.gci_pct, band_pct). Nothing critical for correct invocation or interpretation 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 0%, so the description must compensate, and it maps the key parameters to the two families: model/body + velocity_m_s for the tunnel, diameter_mm/length_mm/velocity_m_s or flow_rate_lpm with n_axial/n_radial scaling for the pipe, plus default metrics, levels, refinement_ratio, base_cell_mm (coarsest level) and end_time. Several params (fluid, mu_pa_s, rho_kg_m3, turbulence, flow_direction, surface_refine) are left to 'any cfd_external_flow_submit knob', which bets the agent has read the twin tool, leaving a real gap against a 19-param schema.

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 first sentence gives a specific verb+resource ('Solve the same CFD case at 2-3 refined meshes and report the Grid Convergence Index') and immediately flags it as asynchronous, distinguishing it from single-solve siblings like cfd_external_flow_submit. It further clarifies the intent ('is this number a property of the flow, or of the mesh?'), so an agent can distinguish this study tool from a plain solve without opening the 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 explicitly states the situation that justifies the cost ('Answers the question no single solve can... on geometry with no analytic twin'), and gives the two dispatch families with the exact parameter sets each requires, referencing cfd_external_flow_submit for the tunnel knobs. It stops short of naming the exact sibling to use instead for a cheap single solve, so it is clear but not fully prescriptive about alternatives.

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