Hydrata MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

Build a scenario's mesh and package

build_scenario

Build a scenario's mesh and inputs package after showing the triangle cost estimate, then poll until the build completes or errors. Use it to avoid spending on oversized builds.

Instructions

Build a scenario's package (mesh + inputs) after showing what it will cost, and poll until built.

Needs a launch-level agent key (a build can start AWS Batch); a read or draft key gets 403 AGENT_LEVEL_INSUFFICIENT — the user creates a launch key on the site's Agent keys page (/agents/).

Order of operations, so the number is shown before anything is spent:

GET the scenario detail. A record with no boundary/computed_status keys is a non-member's read of a public project → refused: a build needs the EDITOR role.
Re-call checks on latest_run (a re-POST is NOT deduplicated after built/complete — it would dispatch a duplicate build): no run → proceed; run created/building → resume polling, no POST; run built/queued/computing/processing/complete with latest_run_is_valid not false → return that state, no POST unless rebuild=true; run error/cancelled, or latest_run_is_valid false (the scenario was edited since the build) → proceed.
Spend gates, each a refusal with outcome: "refused" and no POST: the scenario has no boundary or its boundary row has no features (the server would admit the build and fail it in make_package); the estimate is None (resolution is 0/unset); the estimate is above 100,000 triangles and confirm is not true — the refusal states the number; re-call with confirm=true to proceed. An estimate of 0 over a boundary WITH features is buildable and is reported, not refused.
POST /projects//scenarios//build/. Every 4xx comes back verbatim as a normal result with http_status: 422 MESH_TOO_LARGE (error_code, estimate, ceiling, detail — the server's hard ceiling; coarsen resolution or shrink the boundary; no run was created), 409 COMPUTE_TARGET_UNAVAILABLE, 400/403/404. 409 UNREVIEWED_INPUTS (inputs you wrote that the user has not reviewed) answers outcome unreviewed_inputs with the unreviewed_inputs list and a ui_url to the scenario's review screen: give the user the link, poll get_scenario until its unreviewed_inputs is empty, then build again. A 409 WITHOUT an error_code is the dedup body ({status, run_id, detail}: a build is already in flight) — the tool resumes polling that run.
On 202 poll the detail's computed_status (created → building → built | error), bounded by timeout_seconds.

Returns a COMPACT state, never the whole detail: outcome (built, error, cancelled, complete/queued/computing/processing for a run past the build, timed_out, or refused), computed_status, mesh_triangle_count_estimate, posted, the POST's build body + http_status when one was made, and the latest run's run_id, run_status, error_message, user_message, mesh_triangle_count. timed_out is normal (make_package re-downloads the terrain from S3 every build; minutes): call again with the same arguments — step 2 resumes polling the same run, it never POSTs twice — or cancel_run(run_id) if the run is stuck in created with no worker. error is terminal: error_message says why (fix the inputs, then call again — an errored latest run is rebuilt).

Units: resolution — on the SCENARIO and on every MeshRegion FEATURE — is a LENGTH in metres; ANUGA maximum_triangle_area = resolution²/2 (FloatField default 100, not nullable; 0 makes the estimate None), and the estimate prices both the same way (TASK-3186). The smallest value becomes the raster cell size. A MeshRegion feature must carry resolution_units = m (features drawn in the map are marked automatically); an unmarked one makes the build answer 422 MESH_REGION_UNITS_UNMARKED, naming the conversion an operator runs.

Input Schema

Name	Required	Description
`confirm`	No	Required (true) when the estimate is above 100,000 triangles — the tool refuses first and tells you the number. Default false.
`rebuild`	No	true to dispatch a NEW build of a scenario whose latest run is already built/complete and still valid (default false: the tool returns that state instead of duplicating the build).
`project_id`	Yes	The project ID
`scenario_id`	Yes	The scenario ID from create_scenario
`timeout_seconds`	No	How long this call keeps polling before it returns `timed_out` (default 180, ceiling 200 — claude.ai cuts a tool call at 240 s). 0 = one status read, no waiting.
`poll_interval_seconds`	No	Seconds between polls (default 5)

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.2.0Oct 30, 2026

changedInput schema / properties / timeout_seconds / default
```
Previous value: -240New value: +180
```

changedInput schema / properties / timeout_seconds / description

Previous value: -"How long this call keeps polling before it returns `timed_out` (default 240, ceiling 280 — the prod /mcp/ proxy cuts a call at 300 s). 0 = one status read, no waiting."New value: +"How long this call keeps polling before it returns `timed_out` (default 180, ceiling 200 — claude.ai cuts a tool call at 240 s). 0 = one status read, no waiting."

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?

Annotations only say non-read-only, non-idempotent, non-destructive; the description goes far beyond by disclosing the launch-key requirement and the 403 AGENT_LEVEL_INSUFFICIENT path, that a re-POST after built/complete is not deduplicated and would dispatch a duplicate build, and that 4xx bodies come back verbatim with http_status. It also explains that timed_out is normal and recoverable and that the server re-downloads terrain from S3 each build, which an agent cannot get from the flags.

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?

It is long, but it is front-loaded with the one-sentence purpose and then organized as numbered steps that mirror the actual call sequence, so an agent can scan to the branch it is in. A few lines are denser than needed (the units paragraph, the repeated assurance that it never POSTs twice), which keeps it from a 5.

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, spend-incurring, long-polling build tool with an output schema, this covers everything an agent needs: auth level, the exact pre-flight checks, every refusal branch, the meaning of each 4xx code, timeout recovery, and what 'error' means for retries. The return shape is defined by the output schema, so the compact-state summary is a bonus rather than a gap.

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 all six parameters are already documented, and the description correctly avoids restating them. It still adds value beyond the schema by explaining the causal chain behind confirm (refusal states the number, above 100,000 triangles, re-call with confirm=true) and by tying resolution semantics to the estimate, though a few of those details sit closer to domain data than to parameter meaning.

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 opening sentence names the specific verb and resource (build a scenario's package = mesh + inputs) plus the two behavioral traits that define it: cost is shown first, and the call polls until built. That distinguishes it cleanly from siblings like create_scenario, start_simulation, and get_run_status without the reader opening any 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?

It spells out the ordering explicitly: check the scenario detail, re-check latest_run, pass three spend gates, only then POST. It names concrete alternatives in the moment they matter — resume polling instead of re-POSTing, cancel_run for a stuck 'created' run, rebuild=true to force a new build — rather than leaving the agent to infer.

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