Hydrata MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

Create a draft scenario

create_scenario

Creates a draft flood simulation scenario without building or running it, returning a mesh-triangle estimate and cost so you can size the mesh before committing to a build.

Instructions

Create a DRAFT scenario (no build, no run) and report its mesh-triangle estimate.

POSTs /projects//scenarios/ with the write fields, then GETs the scenario detail — the create response carries NO estimate; the detail's mesh_triangle_count_estimate (+ _breakdown) does. Returns a compact record (the same fields get_scenario answers with): id, name, the FK ids as stored, resolution, duration, computed_status (created = no run yet), the estimate and its breakdown, the price (compute_cost_estimate in USD, vcpu_hours_estimate), inflow_anchor_mismatch, and http_status. Next step: build_scenario (which asks for confirm=true above 100,000 triangles). Nothing is meshed or queued here.

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.

The server does NOT validate that the FK ids belong to project_id — pass the row ids attach_input_layer / get_terrain returned for THIS project. Every FK is nullable at create time, and the build fails later on a scenario with no terrain, or with neither an inflow nor a rainfall. A boundary whose row has no features (the default 'Boundary 01' before attach_input_layer) is accepted here and refused by build_scenario. The estimate is None when resolution is 0; an estimate of 0 with a real boundary is a very coarse mesh, not an error.

Input Schema

Name	Required	Description
`name`	Yes	Scenario name
`inflow`	No	Inflow row id (optional; the build needs an inflow OR a rainfall)
`culvert`	No	Culvert row id (optional; attach_input_layer kind=culvert → row_id). The build refuses a culvert missing its shape, size or invert levels.
`terrain`	No	Terrain id (get_terrain → terrain.id); the build fails without one
`boundary`	No	Boundary row id (attach_input_layer kind=boundary → row_id)
`building`	No	Building row id (optional)
`duration`	Yes	Simulation duration in seconds (e.g. 43200 = 12 h)
`friction`	No	Friction row id (optional)
`rainfall`	No	Rainfall row id (optional; the build needs an inflow OR a rainfall)
`structure`	No	Deprecated alias of `building` (TASK-3586); ignored when `building` is given.
`project_id`	Yes	The project ID
`resolution`	Yes	Mesh resolution as a LENGTH in metres (ANUGA maximum_triangle_area = resolution²/2). Coarser (larger) = fewer triangles: on a ~13 km² boundary 36-40 m gives ~16-20k triangles, 10 m ~255k, 1 m ~25M (refused by the API).
`description`	No	Free-text description (optional)
`mesh_region`	No	MeshRegion row id (optional): finer meshing inside its polygons, each feature's `resolution` a LENGTH in metres (see the units note).

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false), it discloses substantial non-obvious behavior: the create response carries no estimate and a follow-up GET supplies it, the server does NOT validate FK ids belong to this project_id, FKs are nullable but the build fails later without terrain/inflow/rainfall, and an empty boundary row is accepted here but refused by build_scenario.

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?

Purpose and next-step routing are front-loaded, and each paragraph targets a distinct risk (return semantics, units, FK validation, failure modes). It is dense and long for a 14-parameter tool, but most sentences carry actionable information; minor consolidation of the units paragraph is possible.

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 14-parameter mutation tool with an output schema present, the description covers the full decision surface: what it does, what it deliberately does not do, what the response contains, downstream prerequisites, and the FK/units pitfalls. Nothing needed to call it correctly is missing.

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 already 100%, so the schema does the heavy lifting, but the description adds real meaning: resolution is a length in metres (ANUGA max_triangle_area = resolution²/2, applies to scenario and every MeshRegion feature), reset-to-0 yields a None estimate, and the FK ownership caveat. It largely reinforces rather than fully extends the schema, hence 4 rather than 5.

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+scope: 'Create a DRAFT scenario (no build, no run) and report its mesh-triangle estimate.' The parenthetical immediately separates it from build_scenario and start_simulation, which an agent can distinguish without 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?

Explicitly names the next step (build_scenario, with confirm=true above 100,000 triangles) and states what does not happen here ('Nothing is meshed or queued'). It also routes boundary/terrain/rainfall requirements to build-time behavior, giving clear when/when-not guidance against siblings.

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