Predictive Maintenance MCP Server

assess_severity

Assess vibration severity using ISO 20816-3 zones A-D and derive alert levels from machine vibration data. Enter a signal ID or RMS velocity to get zone, severity, and threshold exceedance.

Instructions

Assess vibration severity (ISO 20816-3 zones A-D) and alert level.

THE unified severity tool: ISO zone assessment and alert
classification in one call. Zone boundary values are those of
ISO 10816-3:2009 (ISO 20816-3:2022 merges zones A/B — provenance is
noted in the result). Scope: machines rated above 15 kW; a declared
machine_power_kw below 15 kW is refused.

Input routes (exactly ONE required):
- signal_id: a stored signal (load_signal first). Sampling rate AND
  declared unit come from the stored metadata; an undeclared unit is
  refused, never guessed from amplitude.
- rms_velocity_mm_s: a direct broadband RMS velocity reading in mm/s
  (e.g. from a portable instrument) — no unit declaration needed.

Args:
    ctx: MCP context. Unused — see this module's docstring on logging.
    signal_id: ID of the stored signal (mutually exclusive with
        rms_velocity_mm_s).
    rms_velocity_mm_s: Direct broadband RMS velocity in mm/s
        (mutually exclusive with signal_id).
    machine_group: 1 (large, >300 kW) or 2 (medium, 15-300 kW).
        Ignored when custom thresholds are given. Default 2.
    support_type: 'rigid' or 'flexible'. Ignored when custom
        thresholds are given. Default 'rigid'.
    thresholds: Optional custom zone boundaries {'warning': A/B,
        'alarm': B/C, 'danger': C/D} in mm/s, strictly increasing —
        replaces the ISO table for this call.
    machine_power_kw: Rated machine power, if known. Declared values
        below 15 kW are refused (out of ISO scope); None means
        unknown and is not refused.
    rpm: Operating speed in RPM (signal route only: selects the 2 Hz
        band lower edge below 600 RPM).

Returns:
    VibrationSeverityResult (status='assessed') with zone, severity,
    boundaries, derived alert_level/exceeded_threshold, and threshold
    provenance.

Raises:
    ValueError: On route misuse (both/neither inputs), undeclared
        signal unit, missing sampling rate, Nyquist below the ISO
        band, declared power below 15 kW, negative RMS, or invalid
        custom thresholds.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "assess_severity"
  }
}

Input Schema

Name	Required	Default
`rpm`	No
`signal_id`	No
`thresholds`	No
`support_type`	No	rigid
`machine_group`	No
`machine_power_kw`	No
`rms_velocity_mm_s`	No

Output Schema

Name	Required	Description	Default
`axis`	No	Measurement axis (informational)	vertical
`zone`	Yes	ISO zone: A, B, C, or D
`status`	No	Always 'assessed' — discriminates from a refused result	assessed
`signal_id`	No	Signal identifier used (None for a direct rms_velocity_mm_s reading)
`boundaries`	Yes	Zone boundaries {AB, BC, CD} in mm/s (ISO or custom)
`color_code`	Yes	green, yellow, orange, or red
`alert_level`	No	Alert level derived from the zone: A=none, B=warning, C=alarm, D=danger (filled automatically)
`support_type`	Yes	Support type: 'rigid' or 'flexible'
`machine_group`	Yes	ISO 20816-3 machine group: 1 (large, >300 kW) or 2 (medium, 15-300 kW)
`original_unit`	No	Original signal unit before conversion
`severity_level`	Yes	Good, Acceptable, Unsatisfactory, or Unacceptable
`frequency_range`	Yes	Actual evaluation band used (may be narrower than the ISO nominal 10-1000 Hz when fs limits it); 'not applicable' for direct RMS readings
`machine_power_kw`	No	Declared rated machine power in kW, when provided. Values below 15 kW are refused as out of ISO 20816-3 scope.
`zone_description`	Yes	Zone description
`rms_velocity_mm_s`	Yes	RMS velocity in mm/s
`exceeded_threshold`	No	The boundary (mm/s) exceeded by the reading (None in zone A; filled automatically from zone + boundaries)
`operating_speed_rpm`	No	Operating speed in RPM, when provided (selects the band's lower edge)
`threshold_provenance`	Yes	Provenance of the zone boundary values (ISO edition note, or custom-threshold note)
`unit_conversion_performed`	Yes	Whether acceleration-to-velocity conversion was done

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.9.1Jul 15, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations, the description carries full transparency burden and excels: it covers unit handling (never guessed), standard provenance, mutual exclusivity, custom threshold behavior, rpm band selection, refusal conditions, and detailed ValueError cases. It even notes that ctx is unused and references logging. This is exemplary behavioral disclosure.

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 well-structured with clear sections (purpose, input routes, args, returns, raises) and front-loaded. It is long but justified given complexity. Minor redundancy exists: signal_id and rms_velocity_mm_s are described both in 'Input routes' and 'Args,' but this aids readability rather than wasting space.

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?

Given 7 parameters, two usage routes, custom thresholds, and many error conditions, the description covers everything needed: prerequisites, metadata requirements, return structure (VibrationSeverityResult fields), and error cases. The presence of an output schema further reduces the need to explain return values, and the description still lists key output fields. Complete for a complex 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 description coverage is 0%, so the description must explain all 7 parameters. It does so thoroughly: mutual exclusion, defaults, units, custom threshold structure, power refusal, and conditional behavior (e.g., 'Ignored when custom thresholds are given'). Every parameter's meaning is expanded well beyond the bare schema.

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 states a specific verb+resource: 'Assess vibration severity (ISO 20816-3 zones A-D) and alert level.' It clearly defines the tool's purpose and standard, and positions itself as 'THE unified severity tool,' distinguishing it from other analysis and reporting tools in the sibling list.

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

Usage Guidelines4/5

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

The description provides clear usage context: it explains the two mutually exclusive input routes (signal_id vs. rms_velocity_mm_s), requires 'exactly ONE,' and notes prerequisites like 'load_signal first.' It also defines scope with the >15 kW refusal. However, it does not explicitly name alternative tools to avoid using, so it misses the 'versus alternatives' clause.

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