Hydrata MCP Server

Official

by Hydrata

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Compare a run with flood observations

get_observation_comparison

Read-onlyIdempotent

Compare a flood simulation run with project observations to measure fit: returns residual statistics, bias, RMSE, tolerance counts, gauge errors, and datum warnings.

Instructions

Compare a run with the project's flood observations: how well does it match them?

Returns headline (the figures to tell the user, e.g. "47 observations · 31 within ±0.30 m (66%) · bias -0.12 m · RMSE 0.35 m · 1 excluded"), headline_numbers (the same as numbers), tolerance_m (used) and default_tolerance_m (the project's saved one), statistics (the API's summary: n, within, within_pct, bias_m, rmse_m, weighted_rmse_m, mae_m, max_abs_m, excluded, not_scored by reason, gauges), gauges (Gauge records: peak error, timing error, NSE), datum_checks (warn the user only when warning is true: both datums known and different; not_recorded = the terrain has no recorded datum, stated in note, not a warning) and one row per observation: observed_m / modelled_m / residual_m (modelled - observed, + = model high), within, scored / not_scored_reason, match (outside_run_window = not this flood), excluded + exclusion {reason, by, at}. sampling counts how the modelled values were read: centroid (the peak of the mesh triangle the observation sits in), nearest_node_fallback (an older run without that peak: the nearest mesh node's value, tell the user) and nearest_node (just outside the mesh); each row's sample.method says which. There is no pass or fail: report the figures. A run that is not historic has none (has_comparison false) — do not retry it.

Input Schema

Name	Required	Description
`fid`	No	With layer_id: the observation's fid (list_observations)
`run_id`	Yes	The run ID (a historic run; others are not compared with observations)
`layer_id`	No	With fid: narrow the rows to ONE flood observation and add its history
`tolerance`	No	Metres within which a residual counts as within (default: the project's saved tolerance, 0.3 unless an Editor changed it; presets 0.15, 0.3, 0.4; above 0 and at most 5). Not stored: it only changes this answer
`include_series`	No	Keep each Gauge record's modelled stage series (every saved frame); default false

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.1Oct 29, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds genuine behavioral context: the no-pass/fail reporting stance, the warning semantics of datum_checks, the meaning of sampling fallbacks, and the non-retry rule for non-historic runs. Much of the remainder enumerates return fields that the output schema already carries, so it is not maximally efficient, but the caveats are real value beyond annotations.

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

Conciseness3/5

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

Purpose is front-loaded well, but the bulk is a dense, backtick-heavy enumeration of every returned field (headline_numbers, statistics sub-fields, per-row columns), much of which overlaps the output schema. Every sentence is accurate, but the volume exceeds what the agent needs given a structured output schema exists.

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 complex comparison tool with an output schema present, the description covers the applicability constraint (historic runs), the scoring model, edge cases (excluded/not_scored, datum warnings, mesh fallbacks) and the reporting posture. An agent has enough to invoke it correctly and interpret 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?

Schema description coverage is 100%, so all five parameters are already documented in the schema (including tolerance presets and include_series). The description adds only marginal semantics (tolerance as 'used' vs saved default), leaving the baseline of 3 appropriate.

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 ('Compare a run with the project's flood observations') and even frames the user-facing question it answers ('how well does it match them?'). It is clearly distinguishable from siblings like list_observations or get_run, which merely list data rather than scoring a comparison.

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 real routing context: 'There is no pass or fail: report the figures' and 'A run that is not historic has none (has_comparison false) — do not retry it,' which tells the agent when the tool is applicable and how to behave on an inapplicable input. It stops short of naming an alternative tool or the set_comparison_tolerance sibling, so it is clear context without explicit alternatives.

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