Skip to main content
Glama
gchen19

AnkusDrive

by gchen19
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Harmonic Response

harmonic_response
Read-only

Calculate exact SDOF harmonic response from natural frequency and damping ratio, returning amplification, phase, and amplitude at a given drive frequency.

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}.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
frequency_hzNo
damping_ratioYes
natural_frequency_hzYes
static_deflection_mmNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.9/5.0
Behavior5/5

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

The annotations only say readOnlyHint=true, so the description carries the burden of explaining behavior. It adds substantial context: no solver, exact analytic formulas, the no-peak condition for ζ ≥ 1/√2, optional frequency scaling with `frequency_hz`, and absolute amplitude scaling via `static_deflection_mm`. No contradiction 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.

Conciseness4/5

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

The description is dense but structured: a one-line summary, formula block, condition, escalation note, and return field list. Every section earns its place for an exact-spec oracle, though the formula-heavy middle could be slightly trimmed without losing core meaning.

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?

Despite having no output schema, the description enumerates all return fields including validity flags and escalation hints. It also covers limits, the exact fidelity mode, the no-peak edge case, and the relationship to the meshed sibling tool, so an agent has what it needs to call and interpret the tool.

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

Parameters5/5

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 maps `frequency_hz` and `static_deflection_mm` to concrete behavior, uses `natural_frequency_hz` and `damping_ratio` in the formulas, and clarifies units through parameter names and output fields. This is far more than the bare schema provides.

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?

The description opens with a specific verb and resource: 'Exact SDOF harmonic frequency response (NO solver)'. It clearly distinguishes the tool from `harmonic_response_submit` by calling this one an analytic oracle rather than a meshed solver, so an agent can tell them apart immediately.

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?

It explicitly says to escalate to `harmonic_response_submit` for a real meshed, multi-mode FRF and explains how this tool bridges `beam_modal` and `random_vibration`. That gives clear when-to-use and when-not-to-use guidance with named alternatives.

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