acoustic_radiation_submit

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

With no annotations, the description carries the full burden and delivers: the solve runs out-of-process in a dedicated .venv-bempp because of a meshio version clash, it is asynchronous/off-channel, it degrades to {ok:false, reason, install} when no bempp venv resolves, and results come back as {job_id, status, cache_hit} to be polled via job_result. These are exactly the operational traits an agent must know before invoking.

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?

Long but densely packed with no filler; the environment/isolation caveat and the mode definitions are front-loaded before the return-format note. The heavy parenthetical nesting and backtick-heavy inline code make it slightly harder to scan, but every sentence carries information.

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?

No output schema exists, and the description fully compensates by enumerating the return shapes for each mode ({ok, ka, radiated_power_w, farfield_pressure_x_r, surface_pressure_abs_mean, n_elements, wall_s} and the scattering results array). For a 15-parameter async tool this is complete enough to invoke and to interpret results.

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 explains the meaning of most parameters (a_m, u_amp, freq_hz, rho, c, h as fraction of a, ka_list, theta_deg, h_per_wl in elements/wavelength, model handle, scale_to_m mm→m, linear_deflection mesh tolerance, problem). Only r_m and timeout are left unaddressed, so one documented gap remains in an otherwise strong compensation for the coverage deficit.

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 and resource ('Exterior-acoustics boundary-element solve on Bempp, asynchronous') and immediately positions it against named siblings: the analytic monopole_sphere / rigid_sphere_scattering oracles. The three problem modes ('radiation', 'scattering', 'mesh_solve') are each defined concretely, so an agent can tell exactly what the tool does and how it differs from acoustic_fem_submit and the analytic oracles.

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?

Gives clear context for each mode and explains that radiation/mesh_solve are gated against the monopole oracle and scattering against the Mie oracle, which effectively routes the agent between modes. It does not, however, state when to prefer this expensive BEM path over the cheap analytic oracles, nor any exclusions beyond the implicit venv-availability degradation.

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