harmonic_response_submit

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

No annotations are provided, so the description carries the full behavioral burden, and it does substantial work: it discloses the ElmerSolver dependency with an explicit degradation contract ({ok:false, reason, install} rather than raising), async job semantics (poll job_result), cache_hit behavior, and the three-gate pass criteria with tolerances. Auth, mutation, and idempotency semantics remain unstated.

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?

Dense and structured but not front-loaded: the operational summary, gate semantics, cross-links, and return shape are all packed into three long paragraphs. Each clause carries information, but the agent must parse a lot of physics parentheticals before reaching the async contract and return fields.

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 high-complexity async solver submission with no output schema and no annotations, the description is unusually complete: it covers the degradation path, the async poll target, the full result field list, and the validation gates. It stops short on parameter documentation and on routing versus sibling FEM tools, so it is strong but not exhaustive.

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% for 13 parameters, so the description must compensate, and it only names a few (span_pct, damping_ratio, n_sweep, case_dir) in prose without units or ranges. Critical parameters such as nx/ny, length_m, height_m, youngs_pa, density_kg_m3, and traction_pa go unexplained in both schema and description.

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: 'Harmonic forced response (FRF) via Elmer StressSolve Harmonic Analysis', and the physics is spelled out (plane-stress cantilever, harmonic tip traction, resonance sweep). It distinguishes itself from nearby siblings like harmonic_response (called out as the SDOF oracle) and random_vibration, but it does not cleanly separate itself from the broader FEM submission family or explain why a user would pick this over fem_run/fem_modal.

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?

Mentions it is asynchronous and 'Also accepts a prepared case_dir', which hints at context, but there is no explicit when-to-use versus fem_modal, fem_run, beam_modal, or harmonic_response. The cross-link mentions are inferential rather than directive, so usage is implied rather than stated.

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