Hydrata MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

Start a simulation run (spends compute)

start_simulation

Start a flood simulation run for a built scenario, then poll get_run_status to track progress. Requires a launch-level agent key and user-reviewed inputs.

Instructions

Start a flood simulation run for a built scenario.

Needs a launch-level agent key (a run spends compute); a read or draft key gets 403 AGENT_LEVEL_INSUFFICIENT — the user creates a launch key on the site's Agent keys page (/agents/).

The scenario must be in 'built' status. Returns 202 with the new run. The run transitions through: built → queued → computing → processing → complete.

After starting, poll get_run_status to track progress. Returns 409 if the scenario is not in the correct state. The returned run record has its presigned s3_*_url links elided (6-hour capabilities).

INPUT REVIEW (Hydrata enforces it): while an input you wrote is not reviewed by the user, the run is not started - outcome unreviewed_inputs, error_code UNREVIEWED_INPUTS, a ui_url to the scenario's review screen. A run built from inputs other than the ones reviewed now answers outcome run_invalidated (RUN_INVALIDATED): build_scenario with rebuild=true, then start it again.

SPEND CONSENT (Hydrata enforces it; you cannot): a run whose quote does not fit your agent key's monthly spend limit (default $0), or that Hydrata cannot price, is NOT started. The result is then a normal (non-error) answer with outcome consent_required, error_code CONSENT_REQUIRED, quoted_cost_usd and consent_url: give the user the link and the price (say_to_user). Only they can approve, in their browser. Then do NOT call start_simulation again for this run: poll get_run_status(run_id) — the run leaves built once they press the button. (With consent_timeout_seconds > 0 this call polls the run itself and answers outcome consented, with the run, if they approve within that time.)

Input Schema

Name	Required	Description
`scenario_id`	Yes	The scenario ID to run
`poll_interval_seconds`	No	Seconds between consent polls (default 5)
`consent_timeout_seconds`	No	When the run needs the person's consent (CONSENT_REQUIRED), how long this call keeps polling the run for their click before it returns (ceiling 200). Default 0: return the consent link at once, so you can give it to them — they cannot press a button they have not been shown.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.2.0Oct 30, 2026

removedInput schema / properties / compute_backend

Removed value: -{
-  "default": "local",
-  "description": "Compute backend: 'local' (Celery), 'ec2' (dedicated instance), or 'batch' (AWS Batch spot, cheapest). Default: 'local'",
-  "type": "string"
-}

changedInput schema / properties / consent_timeout_seconds / description

Previous value: -"When the run needs the person's consent (CONSENT_REQUIRED), how long this call keeps polling the run for their click before it returns (ceiling 280). Default 0: return the consent link at once, so you can give it to them — they cannot press a button they have not been shown."New value: +"When the run needs the person's consent (CONSENT_REQUIRED), how long this call keeps polling the run for their click before it returns (ceiling 200). Default 0: return the consent link at once, so you can give it to them — they cannot press a button they have not been shown."

First observedv0.2.1Oct 29, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes far beyond the annotations: names the required key level and the 403 AGENT_LEVEL_INSUFFICIENT failure, the 202 response, the built→queued→computing→processing→complete lifecycle, the 409 state error, and that presigned s3_*_url links are elided (6-hour capabilities). It also discloses two enforced gates (input review, spend consent) with their outcome/error codes and the fact that the 2023 non-idempotent call must not be repeated — consistent with idempotentHint=false.

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 purpose, prerequisite and the post-start polling instruction; the two enforcement sections are labelled in caps so they are scannable. It is long (~350 words) and a few clauses about error codes could be tightened, but nearly every sentence carries operational information an agent would otherwise get wrong.

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 non-idempotent, compute-spending, gated mutation, the description covers auth, preconditions, response timing, lifecycle, all meaningful failure outcomes and the required recovery path. With an output schema present it correctly avoids re-documenting the run record while still flagging the elided presigned links.

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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: with consent_timeout_seconds > 0 the call polls internally and answers outcome 'consented', tying the parameter to a distinct response shape. scenario_id itself is only echoed ('must be in built status'), which the schema already covers.

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 and resource ('Start a flood simulation run for a built scenario') with the exact prerequisite state, and the final sentences distinguish it from the siblings an agent might confuse it with (build_scenario for rebuilds, get_run_status for polling). An agent can identify the operation and its boundary conditions without opening the 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 routes the agent: poll get_run_status after starting, rebuild with build_scenario(rebuild=true) when a run is invalidated, and — critically — do NOT call start_simulation again after a CONSENT_REQUIRED result, poll instead. That is a real when-not-to-call rule with a named alternative, not just implied usage.

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