fsi_interface_balance

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

No annotations, so this description carries the full load; it does so well by spelling out the physics (Newton's third law across the coupling surface), the residual definition, and the no-input fallback behavior. It stops short of stating auth/prereq requirements or whether the returned balanced/escalate_to fields gate downstream steps.

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?

Front-loaded with the core identity, then the physics, then the residual definition, then the no-input fallback, then the return shape. Necessary content, but dense prose and a symbol-heavy formula could be tightened; sentences are not wasteful but are not crisp either.

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 solver-less gate tool with no output schema and no annotations, the description supplies the missing contract: what the return fields mean (area, reference load, fluid force, solid reaction, residual, relative residual, balanced, fidelity, escalate_to) and the physics rationale. It leaves minor gaps (units for inputs, when balanced/escalate_to should trigger action) but is otherwise sufficient.

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 0%, so the description must compensate. It names each parameter's meaning: pressure_pa times length_mm×width_mm gives the reference load, fluid_force_n is ∮p·dA over the OpenFOAM wet patch, solid_reaction_n is Σ ccx reaction at the clamp. That covers all five parameters, though units/definitions for pressure/length/width are only implied.

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?

States a specific verb+resource: a partitioned wet-interface force balance with no solver. It names the solids coupling and the exact conservation quantity (F = pressure·area). It distinguishes itself from other fsi_* siblings only implicitly through the 'NO solver' framing and the return set.

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?

Explains how the tool is used: pass fluid_force_n and/or solid_reaction_n to close the balance; with neither supplied it returns the reference analytic load. That's clear context for the intended workflow, but it doesn't name an alternative (e.g., fsi_plate_deflection, fsi_channel_pressure) or explicitly state when to choose this gate over a full solve.

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