Skip to main content
Glama

Analyse oscillatory ventilation (beta)

analyze_eov

Analyses exercise oscillatory ventilation and the ventilatory control loop behind it in an uploaded recording. Beta: developed on one heart failure cohort, transportability untested. Needs end-tidal CO2; without it the analysis is refused with that reason.

Returns cpet_id and one envelope in results: status ("ok" or "not_analysable"), findings, quality (good/acceptable/poor, of the INPUT, not of the answer), confidence ("low" or "normal" with the reasons, never a number), notes, provenance, and error/message when it could not run. Counts one unit of the key's monthly allowance, a repeated call included. Licensed separately (get_capabilities lists this key's analyses).

The findings answer three different questions:

  • GRADE and BURDEN: how MUCH oscillation there was.

  • MARGIN.LOOP_GAIN: how CLOSE the control loop is to oscillating on its own, 0 stable and 1 self-sustaining. Defined even when the grade is "none": a grade saturates and this does not.

  • LOOP: the factorisation, when an oscillation is clear enough to invert. g = plant_gain x controller_gain. delay_s comes from the phase and is NOT a factor of g.

And three limits:

  • margin.corroborated false: end-tidal CO2 did not oppose ventilation at that period, so what resonates is not the chemoreflex loop. It is ventilatory variability, not instability.

  • delay_s is the whole lag in the return path, not a circulation time. "Circulation" would be an interpretation, not a measurement.

  • co2_amplitude_suspect: the end-tidal CO2 waveform was distorted (a clipped sample) while ventilation stayed clean. Plant gain is then a LOWER bound and controller gain an UPPER one.

An absent note does not mean an absent finding.

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": {
      "cpet_id": "<cpet_id>"
    },
    "name": "analyze_eov"
  }
}

Input Schema

NameRequiredDescriptionDefault
cpet_idYesHandle from upload_cpet, create_upload or get_sample_cpet.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / cpet_id / description
      Added value: +"Handle from upload_cpet, create_upload or get_sample_cpet."
  2. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Annotations only say readOnly=false, idempotent=false, destructive=false; the description goes far beyond by disclosing credit consumption per call including repeats, separate licensing disclosed via get_capabilities, and the refusal behaviour when CO2 is absent. It also describes the return envelope in detail (status, findings, quality of the INPUT rather than of the answer, confidence as a word with reasons, provenance) and closes with a caution that an absent note does not mean an absent finding.

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?

Well front-loaded: capability, beta caveat, and the CO2 precondition come before returns, findings semantics, and limits. The findings and limits sections are dense but each bullet carries distinct meaning, since no output schema exists to hold that interpretation. Some output-semantics detail could be trimmed, but nothing is pure filler.

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?

For a specialized analysis with no output schema, the description carries the full burden and does so: prerequisites, billing, licensing, the return envelope, the three distinct questions the findings answer, and three interpretation limits (corroboration, delay vs circulation time, suspect CO2 amplitude). An agent has enough to decide whether to call it and how to read the result.

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

Parameters3/5

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

There is a single parameter, cpet_id, and the schema already documents it at 100% coverage, including the originating tools. The description adds no further syntax, format, or validity detail beyond what the schema provides, so this sits at the documented baseline rather than adding value.

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

Purpose4/5

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

Opens with a specific verb and resource: analyses exercise oscillatory ventilation and the ventilatory control loop in an uploaded recording, and states the beta scope (one heart failure cohort, transportability untested). An agent can tell what domain this covers, but the description never contrasts it with the sibling analyses (analyze_vt, analyze_substrate), so sibling differentiation is left implicit.

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?

Gives a hard precondition: it needs end-tidal CO2 and without it the analysis is refused with that reason, which is exactly the kind of gating an agent needs before calling. It also flags the cost model (one unit of the key's monthly allowance, repeats included) and separate licensing. It stops short of naming alternative tools to use when the CO2 channel is missing or when a non-oscillatory analysis is wanted.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources