Acoustic FEM Submit

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

Annotations only declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false. The description adds crucial behavioral context beyond that: the asynchronous nature ('job_id, status, cache_hit'), the dependency on ElmerSolver, the fact that it returns a degradation dict or job ID, and the exact return structure for both duct and cavity types. No contradictions with annotations.

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 relatively long, but it is well-structured with distinct sections for duct and cavity modes, and every sentence adds substantive information about physics, parameters, or returns. It is appropriately front-loaded with the purpose and the sibling relationship, and the length is justified by the tool's complexity. A 4 reflects that it is not overly concise but each part earns its place.

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 tool with 15 parameters, no output schema, and no required params, the description covers the two analysis modes, the physics, the return formats, the dependency on ElmerSolver, and the async behavior. It is fairly complete, though it omits explicit explanations for a few parameters (nx, ny, sif, n_elements, length_m) and the degradation dict is only mentioned without detail. Still, it provides enough context for an agent to understand the tool's purpose and likely usage.

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?

With 0% schema description coverage, the description carries the full burden of explaining the 15 parameters. It gives meaningful semantic context for many key ones (kl, mode_nx, mode_ny, span_pct, n_steps, case_dir, lx_m, ly_m) through physics descriptions and formulas. However, it does not explicitly explain every parameter (e.g., nx, ny, sif, length_m, n_elements), leaving minor gaps, so a 4 is appropriate rather than 5.

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 states a specific action (submit acoustic FEM) with two explicit modes (duct and cavity), and immediately distinguishes itself from the sibling acoustic_screen as 'the higher-order twin'. It clearly communicates the resource being acted upon and the physics being solved, making it distinguishable without opening any 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?

Explicitly names the alternative `acoustic_screen` and frames itself as the higher-order, more accurate FEM version, implying when each should be chosen. It also states the precondition `Requires ElmerSolver` and the graceful fallback when absent, which guides the agent about environment requirements and expected behavior.

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