Skip to main content
Glama

Harmonic Response

harmonic_response
Read-only

Computes exact SDOF harmonic frequency response (FRF) from natural frequency and damping ratio, returning amplification, phase, peak frequency, and bandwidth for vibration checks.

Instructions

Exact SDOF harmonic frequency response (NO solver) — the FRF screen and the oracle the Elmer harmonic_response_submit sweep is gated against. Bridges beam_modal (f_n) and random_vibration (Q = 1/(2ζ)): with r = f/f_n, |H| = 1/√((1−r²)²+(2ζr)²), phase = atan2(2ζr, 1−r²), peak amplification Q = 1/(2ζ√(1−ζ²)) at f_peak = f_n·√(1−2ζ²), half-power bandwidth ≈ 2ζ·f_n. With frequency_hz the response at that drive is returned; static_deflection_mm scales it to an absolute amplitude_mm. fidelity='exact'; ζ ≥ 1/√2 has no peak (flagged). Escalate to harmonic_response_submit for a real meshed FRF (multi-mode, geometry-true).

Returns {natural_frequency_hz, damping_ratio, q_factor, f_peak_hz, half_power_bandwidth_hz, frequency_ratio, amplification, phase_deg, amplitude_mm, fidelity, band_pct, valid_range_ok, warnings, escalate_to}.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "natural_frequency_hz": "<natural_frequency_hz>",
      "damping_ratio": "<damping_ratio>"
    },
    "name": "harmonic_response"
  }
}

Input Schema

NameRequiredDescriptionDefault
workspaceNoRun this call in this named workspace
frequency_hzNo
damping_ratioYes
natural_frequency_hzYes
static_deflection_mmNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.7
    • addedInput schema / properties / workspace
      Added value: +{
      +  "default": "",
      +  "description": "Run this call in this named workspace",
      +  "title": "Workspace",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description goes well beyond them: it discloses the analytic model used, the fidelity flag ('exact'), that ζ ≥ 1/√2 produces no peak and is flagged, and that warnings/valid_range_ok/escalate_to are returned. No behavior here contradicts the read-only annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core identity and escalation path, then the math, then parameter effects, then the return fields — a sensible ordering. The formula cluster is dense but each expression (|H|, phase, Q, f_peak, half-power bandwidth) tells the agent something it cannot get from the schema, so nothing is wasted, though the prose could be tightened slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description enumerates the returned keys, including `fidelity`, `band_pct`, `valid_range_ok`, `warnings`, and `escalate_to`, which is exactly what an agent needs to interpret results and decide on escalation. For an analytic read-only tool with two required params, nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 20%, so the description must carry the load, and it does: it defines r = f/f_n, explains that `frequency_hz` selects the drive point, that `static_deflection_mm` scales the result to an absolute amplitude_mm, and that ζ ≥ 1/√2 is invalid for peak computation. Only the `workspace` parameter is left unaddressed, which is a minor residual gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: exact SDOF harmonic frequency response with no solver, and immediately frames it as an FRF screen and oracle for the Elmer `harmonic_response_submit` sweep. It also names the two sibling tools it bridges (`beam_modal`, `random_vibration`), so an agent can place it in the tool family without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use it (exact SDOF screening, oracle for the gated sweep) and when to escalate (`harmonic_response_submit` for a real meshed, multi-mode FRF). It also gives the conditional behavior of `frequency_hz` and `static_deflection_mm`, so the agent knows which call shape produces which answer.

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

Deploy Server

Other Tools