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

Annotations only declare readOnly=false, destructive=false, idempotent=false, openWorld=false. The description adds substantive behavior beyond that: MCP never uploads bytes, non-http inputs are refused, and there is a 10-photo-per-observation cap that this link consumes. That is exactly the context an agent needs before calling a mutation tool.

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

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

The binding constraint (link, never file) is front-loaded in the first clause. The remaining sentences earn their place by explaining refusals and the escape hatch, though the JPEG/PNG/HEIC and 25 MB details describe the UI alternative rather than this tool and are mildly tangential.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the description covers the mutation semantics, refusal cases, and quota interaction. The one gap is whether re-attaching the same link is deduplicated or duplicates the entry, which the false idempotentHint leaves ambiguous.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters including the http(s) constraint on reference_url. The description adds no per-parameter syntax or format detail beyond what is in the schema, so the baseline 3 applies.

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

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

States a specific verb (attach) and resource (photo link on a flood observation) and immediately scopes it: 'as a reference LINK (never a file).' An agent can distinguish this from any byte-upload path 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when-not: local paths, file:// URLs and data: URIs are refused. It also routes the agent to the correct alternative for actual uploads (open the observation in the map, use the photo strip), including accepted formats and size/count limits.

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

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

Annotations only cover the mutation/idempotency profile; the description goes well beyond by disclosing partial-failure semantics (400 rows land in `rejected` with `problems` while the rest still succeed), fatal-batch errors (403/404/409 stop the batch and populate `stopped` with `not_sent_count`), the 200-row cap, and sequential POST ordering.

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

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

Front-loads the purpose, then the endpoint/failure model, then the datum caveat and the photo alternative. Every sentence carries operational information; nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a batch mutation tool with a rich schema and an output schema, the description supplies the missing behavioral contract (failure classification, limits, ordering) needed to call it correctly. Nothing an agent needs is absent.

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

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 non-schema context such as stages being referenced to the layer's vertical datum and the must-identify-the-flood rule for flood_mark/dry_point. Most remaining parameter detail is already carried by the very rich schema descriptions.

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

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

States a specific verb (add) and resource (flood observations) and enumerates the exact subtypes accepted. It clearly distinguishes itself from add_observation_photo_link by scoping photos out of the operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operating context: photos must go through add_observation_photo_link, and a flood_mark/dry_point requires a date window or flood_name ('ask the user; never guess a date'). It stops short of routing the agent to update_observation or list_observations for other workflows.

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

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

Goes far beyond the annotations: it discloses the full upload→poll→PATCH sequence, the status transitions, the 400 refusal when the dataset isn't owned by the caller, the UNREVIEWED_INPUTS build gate, refused inputs (breakline, non-UUID execution_id) with no request made, and the one-GeoJSON-per-kind constraint. The annotations (destructive false, idempotent false) are consistent with a row-PATCH that is retryable only via retry_execution_id.

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

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

Front-loaded with the verb and the target kinds, and most paragraphs earn their place (alternatives, prerequisites, outcome codes). It is long, and one passage — the culvert engine's GPU/CPU lane behaviour — describes simulation behaviour rather than invocation of this tool, which is tangential for a 5-parameter call.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a multi-step tool with an output schema, an agent gets everything needed to call it correctly: upload endpoint with curl example, polling bounds, all outcome values, failure remediation, ownership constraint, and the review workflow afterwards. Nothing material is left implicit.

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

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

Schema coverage is 100%, so baseline is 3; the description earns more by clarifying that execution_id must be the exact UUID the upload returned, documenting the outcome/timed_out retry path via retry_execution_id, and stating the kind semantics including the deprecated 'structure' alias and the breakline refusal. Timeout ceiling rationale lives in the schema, not the description, so it isn't double-counted.

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

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

States a specific verb and resource — attach an uploaded GeoJSON as one of seven enumerated project input kinds — and immediately distinguishes itself from write_input_layer and request_input_upload by client capability. An agent can pick this tool without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use gate (client with a shell and agent key), explicit when-not (no-shell connector → write_input_layer or request_input_upload), and named prerequisites: the terrain import seeds the six default rows ~30 s after get_terrain is ready, otherwise run finalize_terrain_upload. The culvert case gets its own routing rule (write_input_layer, since no row is seeded).

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

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.

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.

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.

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.

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.

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.

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

Goes well beyond the annotations: it discloses the required key scope with the exact error code (launch-level agent key, else 403 AGENT_LEVEL_INSUFFICIENT), what side effects occur (compute teardown of EC2/Celery/Batch resources), and the terminal-state conflict behavior (409). Annotations only say destructive=true and idempotent=true; the description supplies the operational consequences and failure modes.

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

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

Four short lines, each front-loaded with a distinct fact: auth requirement, valid states, side effects, and failure code. No restatement of the title or name and nothing decorative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-param destructive mutation, it covers permissions, preconditions, side effects, and error responses, and an output schema already handles return values. Nothing an agent needs to invoke it safely and predict failure is missing.

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

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

Only one parameter (run_id) and the schema already documents it at 100% coverage. The description adds no format, sourcing, or lookup guidance for run_id beyond the schema, so it sits at the baseline for high-coverage schemas.

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

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

States a specific verb and resource ('Cancel an in-flight simulation run') and scopes it narrowly with 'in-flight', implicitly separating it from get_run, get_run_status, list_runs, and retry_run. An agent can tell immediately this is the termination path, not a status or retry path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit eligibility ('built, queued, or computing status') and an explicit when-not ('409 if the run is already in a terminal state'). It stops short of naming a sibling alternative (e.g., retry_run for failed runs or get_run_status to check state first), so it is clear context without full routing guidance.

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

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

The description carries substantial context the annotations do not: the underlying POST endpoint, the fact that the call blocks and polls until a GeoServer layer reaches `ready` (seconds), that add_observations is refused during that window, and that `timed_out` is a non-fatal outcome handled later via list_observations. This is exactly the async/readiness detail an agent needs before invoking.

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

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

Front-loaded with what the tool produces, then the domain meaning, then the operational behavior. Dense but purposeful. The `ready`/`timed_out` outcome names are compact and useful rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values need no prose. For a blocking create with a 200-second clamp, the description covers creation, readiness polling, refusal of dependent calls, and timeout recovery — everything needed to call it correctly and interpret the wait.

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

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

Schema description coverage is 100%, so the schema already explains vertical_datum, datum_offset_m, timeout_seconds and poll_interval_seconds. The description references waiting and timeouts implicitly but adds no parameter-level meaning beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb and resource ('Create a flood observation layer in a project') and immediately defines the domain object (real flood evidence: Flood marks, Timed levels, Gauge records, Dry points) plus its distinguishing property: project-level, never a scenario input. An agent can separate this from create_scenario or create_time_series without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The sequencing is explicit: creation must complete before add_observations will accept data, and a `timed_out` result should be followed by list_observations rather than a retry. It stops short of enumerating when an agent should NOT create a layer (e.g. reusing an existing one via list_observations), but the practical routing guidance is clear.

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

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

Beyond the annotations (which only say it's a non-destructive, non-idempotent write), the description discloses ownership semantics (caller's account becomes owner), visibility (unpublished, only owner/members can see), and a hard constraint the agent cannot work around ('you cannot publish it'). That is exactly the kind of non-obvious behavior the schema and annotations cannot convey.

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

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

It is front-loaded with purpose and return values, then layers in the projection rule, visibility constraint, and next step. Slightly dense, but each sentence carries distinct, actionable information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still summarizes the returned fields and their use (ui_url for the user), and it covers the unpublished-state caveat and the follow-up call. Nothing an agent needs to invoke this correctly is missing.

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

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 real meaning for `projection`: it is the CRS every scenario in the project is meshed and run in, and should be the UTM zone covering the site. `name` is left to the schema, which is acceptable.

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

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

The first sentence states a specific verb and resource (create an ANUGA project) and the second names exactly what comes back (id, base_map, ui_url). This is clearly distinguishable from siblings like create_scenario or list_projects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives strong operational context: pick the UTM zone covering the site, hand the ui_url to the user, and the explicit next step is presign_terrain_upload. It lacks an explicit 'do not use this when...' clause or a contrasting alternative, so it falls just short of the top band.

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

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.

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.

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.

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.

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.

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.

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing side effects: Hydrata fetches, reprojects, publishes the DEM and seeds the project's default input rows, with datum stamped by the source. It also explains that `timed_out` is normal for large areas and that a refusal creates nothing and puts the reason in `say_to_user`.

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

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

Front-loaded with the action, then the prerequisites, then the return shape and failure path — a sensible order with little filler. The return-envelope sentence partially restates what the existing output schema already provides, which costs some tightness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a write operation with an output schema, it covers the things an agent still needs: contributor/launch-level key rights, that the import can start AWS Batch, the timeout-as-polling contract, and the refused outcome path. Nothing material is missing for correct invocation or follow-up.

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

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

Schema coverage is 100%, so the schema already defines bbox, source, timeout_seconds and poll_interval_seconds. The description still adds meaning: the `key`-from-list_terrain_sources convention and the operational interpretation of timeout as 'returns timed_out, then poll get_terrain', which the schema alone does not convey.

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

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

States a specific verb and resource: 'Have Hydrata fetch a terrain from one of its own sources, then wait for the import'. It is clearly distinct from get_terrain (polling/reading an existing import) and from presign_terrain_upload/finalize_terrain_upload (user-supplied DEM), because it emphasizes the source catalog path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete routing: use a `key` from list_terrain_sources, and when the call returns `timed_out`, keep calling get_terrain(project_id, terrain_id). It also enumerates when the tool won't proceed (bbox over the source size cap, no source data, unknown source). It stops short of explicitly contrasting with the upload flow (presign/finalize), leaving one sibling choice to inference.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false) it discloses that validation happens client-side before any request, that the API answers 500 rather than 400 to a malformed row, and that the response is a compact record rather than the echoed rows. It also explains the TRAILING_VALUE_HELD refusal path, which is exactly the kind of failure mode an agent needs warned about.

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

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

Front-loaded with the purpose and then ordered by what an agent must know (validation, return shape, naming/units constraints). Dense but every paragraph carries actionable content; the only mild redundancy is describing the returned fields when an output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, nested-object mutation tool with no enum coverage on series_type, the description supplies the missing choice set, the units-per-type rules, the validation timing and the error behavior. Return values are described even though an output schema exists, leaving no operational gap.

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

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 cross-parameter semantics the schema alone does not: series_type is checked against four choices, units must be consistent with series_type, and `name` is bound verbatim because rainfall polygons reference gauges by name. The hold_last_value/trailing-zero interaction is also spelled out.

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

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

States a specific verb and resource ('Create a time series') and enumerates the concrete domain objects it covers (rain gauge, hydrograph, tide/stage), plus where it lives ('in a project'). It does not explicitly contrast with the sibling update_time_series or delete_time_series, so the create-vs-modify boundary is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real usage conditions: units must match series_type, hydrograph/hyetograph must end at 0 unless hold_last_value is true, and gauge names must match the rainfall GeoJSON feature names. It also routes the agent elsewhere for round-tripping ('fetch the full row with the REST API'). It stops short of stating when to use update_time_series instead.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds the non-obvious cascade that associated photos are also destroyed, plus the exact error semantics (404 on a missing fid rather than a silent success). It stops short of mentioning permission requirements or any partial-failure behavior.

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

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

Two tight sentences: the destructive effect and irreversibility are front-loaded, then the endpoint and error contract follow. No filler and nothing repeated from annotations or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description closes the remaining gaps (cascade, irreversibility, 404 behavior) for a 3-parameter destructive tool; only auth/permission context is absent.

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

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

Schema coverage is 100%, so all three parameters are documented and the baseline is 3. The description adds value by spelling out the resource path template, showing how project_id, layer_id, and fid map into the URL hierarchy and confirming fid identifies a single observation.

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

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

States a precise verb (delete) and resource (one flood observation), plus the cascading scope of deleting its photos. It is clearly distinguishable from siblings like update_observation, list_observations, and set_observation_exclusion 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage through the destructive verb and the 'cannot be undone' warning, but it never states when to choose deletion over an alternative such as hiding the observation via set_observation_exclusion. No prerequisites or exclusions are given, so the routing guidance is only implicit.

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

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

Annotations already flag destructiveHint and idempotentHint, and the description adds context the annotations cannot carry: the operation is irreversible, requires the Manager role, and returns a 409 whose message names the blocking layer and feature. That is exactly the authorization and failure-mode detail an agent needs before a destructive call.

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

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

Front-loaded with the destructive nature and the permission requirement, then the refusal workflow. The closing sentence 'A series that no feature uses is deleted' is largely redundant with the preceding 409 explanation, a small amount of waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive two-parameter tool with an output schema and full annotation coverage, the description covers the safety profile, permissions, error semantics and remediation. Nothing an agent needs to invoke it safely and correctly is missing.

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

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

Schema description coverage is 100% for both required parameters (series_id, project_id), so the schema already carries the parameter semantics. The description adds nothing about parameter meaning or format, which is acceptable at full coverage but leaves the baseline.

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

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

States a specific verb and resource ('Delete a time series'), immediately qualified with irreversibility. The resource (time series) is unambiguous against siblings such as delete_observation or update_time_series, so an agent can pick it 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition (Manager role) and a concrete failure path: if the series is used by an inflow/rainfall/boundary layer, detach or repoint it and retry. It does not name the specific sibling tools (attach_input_layer / write_input_layer / update_time_series) that accomplish the remediation, so routing still takes one inference step.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds genuine value by disclosing provenance ('generated by Hydrata from the same definitions the build reads, so it is never out of date') and the per-kind return contents. It does not add much beyond that provenance note, so a 3 is appropriate with annotations already carrying the operational traits.

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

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

Front-loaded: the one-line purpose comes first, then the usage directive, then the return detail. Mostly tight, though 'Per kind it returns' partially restates the opening sentence and the field list is dense; a small trim would make it ideal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still orients the agent on what comes back (geometry types, property types, required flags, allowed/min-max, required_one_of groups, notes, example). Combined with the provenance guarantee, nothing an agent needs 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.

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

Schema description coverage is 100% and the schema's `kind` description already enumerates the seven values and the empty-string behavior. The description reiterates the per-kind return shape but adds no new meaning about the parameter itself, so the baseline 3 applies.

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

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

States a specific verb ('Say what each input layer kind looks like') and enumerates the exact payload: geometry, properties, allowed values, minimal example. It is clearly a read-only reference/spec tool, distinguishable from the write siblings (write_input_layer, request_input_upload) it feeds.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Read this BEFORE you build GeoJSON for write_input_layer or an upload', naming the downstream tools, and adds a negative instruction ('do not read source code or guess column names'). Both the when and the alternative paths are stated.

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

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

Annotations already declare non-read-only, non-idempotent and non-destructive. The description does correctly reinforce the non-idempotent trait by warning against retrying finalize, but most of its length is spent on auth requirements, side effects and error codes rather than on behaviors the annotations leave undisclosed.

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

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

The step number and precondition are front-loaded, which is good, but the description runs long and stacks auth details, side effects, response codes and error remediation into dense paragraphs. The parenthetical about checking the PUT's status code and Content-Type is useful but sits inside a block of otherwise ancillary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter mutation that chains into a multi-stage import, it covers preconditions, side effects, auth, the 202 response and the one documented error branch, which is more than adequate alongside the existing output schema. It stops short of naming the alternative path (create_terrain_from_source) for importing terrain from a source rather than an upload.

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

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

With 100% schema coverage the schema already defines every parameter, yet the description adds real meaning: staging_key is tied to a concrete failure mode (UPLOAD_NOT_FOUND when no object exists at that key) and the sequencing constraint on when finalize is safe. This makes the schema fields actionable rather than merely documented.

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

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

The opening sentence names a specific verb and resource ('register the PUT GeoTIFF as a Terrain and start the import') and places it as 'Step 2 of a terrain import', which cleanly separates it from presign_terrain_upload (step 1) and create_terrain_from_source. An agent can identify this tool and its role in the pipeline 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit precondition ('Call this only after the presigned PUT returned 200') and an explicit prohibition ('do not retry finalize until it has [landed]'), plus the exact failure branch (400 UPLOAD_NOT_FOUND means the PUT did not land). The 'Step 2' framing routes the agent to the preceding sibling in the sequence.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral value beyond that: the exact return shape and the non-obvious edge case that ui_url is null while a new project's map is still being created.

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

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

Front-loaded with the one-sentence summary of what is returned, then structured detail on fields and the ui_url pattern. Slightly dense, and the field list partly restates what the output schema already exposes, but no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the description need not spell out return values, yet the added field list, ui_url URL pattern, and null-map edge case make it self-sufficient. Only the lack of sibling differentiation (list_projects) keeps it from being fully complete.

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

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

Schema description coverage is 100% and there is a single required project_id documented in the schema, so the schema carries the parameter burden. The description does not add syntax, format, or constraints for project_id, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource ('Get one ANUGA project') and enumerates exactly which fields belong to the project record versus what does not (scenarios). It clearly distinguishes itself from siblings like list_projects and get_scenario.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly excludes a scope ('Scenarios are NOT listed here — use get_scenario with a scenario id'), which is a genuine when-not plus named alternative. It does not, however, contrast against list_projects or state when fetching a single project is preferable, so it falls short of full routing guidance.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing that presigned s3_*_url links are elided because they are 6-hour capabilities no tool relays, and by explaining that results remain viewable via gn_layer_* WMS entries. The `sww` block adds state semantics (available/not_kept/archived/restoring), size, and the ui_url download/restore path — exactly the non-obvious behavior an agent needs.

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

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

Front-loaded with purpose and sibling routing, then structured paragraphs for downloads and `sww`. The `sww` passage is dense but earns its space by preventing a failed download attempt; slight over-length keeps it off a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite an output schema existing, the description supplies the interpretive context the schema cannot: why URLs are absent, what the alternative result-access path is, and what each `sww.state` value implies. Nothing an agent needs to call it correctly or interpret the response is missing.

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

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

Only one parameter (run_id) with 100% schema coverage, so the schema already fully documents it; the description adds no extra constraint or format detail on run_id. Baseline 3 applies.

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

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

First sentence names a specific verb and resource ('Get full details of a simulation run') and enumerates the payload: status, progress, timing, compute details, mesh info, errors, result log. It is immediately distinguishable from get_run_status, which is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'Use get_run_status for lightweight polling; use this for final results.' That is a clear when-to-use/when-to-use-the-alternative statement with the selecting condition (polling vs. final results).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description still adds real behavioral context beyond them: sub-50ms latency, the exact projected return fields, phase-vs-status divergence, and the misleading non-stall state. That is genuine disclosure an agent cannot derive from the annotations.

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

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

Front-loaded with the fast polling purpose, then the return payload, then the phase nuance, then the cadence. Every sentence carries distinct operational information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still names the fields an agent will see, and it supplies the polling cadence and terminal states needed to drive a poll loop. Nothing required to call this tool correctly is missing.

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

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

The single run_id parameter is already fully described in the schema (100% coverage), so the schema does the work. The description adds no syntax or constraint detail for run_id beyond implying it identifies the run. Baseline 3 is correct for a one-param tool with complete schema coverage.

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

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

Opens with a specific verb+resource and scope: 'Lightweight status check for a simulation run (fast, <50ms).' It also names the sibling it replaces ('instead of get_run'), so an agent can distinguish it from get_run without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing rule ('Use this for polling instead of get_run') plus operational cadence ('Poll every 5-10 seconds') and terminal-state list (complete, error, cancelled) that tells the agent when to stop. The 'preparing_inputs ... is NOT a stall' note preempts a specific misuse.

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

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

Far exceeds what readOnlyHint/idempotentHint convey: it enumerates computed_status values, explains latest_run_is_valid semantics, discloses the reduced record for non-members (fields ABSENT rather than null, run-state keys null), and states no read tool returns a presigned S3 URL. These are exactly the behaviors an agent cannot infer from annotations or schema.

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

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

Front-loaded with the compact-state framing, and every clause carried content (status enum, withholding, review gating, anchor mismatch). It is still a very long, clause-heavy block — several sentences run past 60 words, which costs some scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even though an output schema exists, the description supplies the interpretation the schema cannot: null vs absent under reduced access, what computed_status values imply, and how to relay hydrology_check and unbound_series to the user. Nothing needed to call or interpret it is missing.

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

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

Schema coverage is 100% and both parameters are simple ids documented in the schema; the description adds nothing about project_id/scenario_id. Baseline 3 applies when the schema already does the work.

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

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

Opens with a specific verb+resource+scope ("Get a scenario's COMPACT state") and immediately contrasts it with the raw ~50 KB detail, which together with the explicit pointer to get_run distinguishes it from the sibling tools get_run, list_runs and get_run_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete operating guidance: poll every 30–60 s after handing over the review link, build/run are refused while unreviewed_inputs is non-empty, and "use get_run for the full run record" names the alternative and the condition that selects it.

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

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

Far exceeds the readOnly/idempotent annotations: it enumerates the exact `outcome` values, distinguishes `not_found` (project has no terrain) from an unknown terrain_id (API 404), and discloses realistic durations (4.5–26 min) so the agent can calibrate polling behavior. It also warns that `ready` precedes default input-row seeding by ~30 s.

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

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

Front-loaded with purpose and outcome enum, then state-machine and failure semantics. Dense but well ordered; the 32 MB DEM timing anecdote and the enumerated default input rows are slightly verbose but serve a real calibration purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even though an output schema exists, the description covers the terminal states, the non-obvious `not_found` case, the seeding lag, and retry semantics — everything an agent needs to poll correctly without guessing. Nothing material is missing for a read-only polling tool.

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

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

Schema coverage is 100%, and the schemas already document project_id, terrain_id (omit → newest terrain), timeout_seconds ceiling and 0 = single read, and poll_interval. The description reinforces semantics (timeout bounding, same-arguments retry) but adds little the schema does not already say, so the baseline 3 applies.

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

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

Opens with a precise verb+resource+termination condition: 'Poll a terrain's import until it is `ready` (or `error`), bounded by timeout_seconds.' It is clearly distinct from finalize_terrain_upload (which it implicitly follows) and from generic status tools like get_run_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells the agent that `timed_out` is normal and NOT a failure, to keep calling with the same arguments while status is creating/styling, and that `error` is terminal requiring a re-upload. It also gives the follow-up ritual: poll the input-layer list until non-empty before attaching a layer.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's real value is the semantics it adds: null in has_features means unknown rather than empty, and a row without gn_layer means no layer yet. That is genuinely non-obvious behavior not recoverable from annotations or schema. It omits any statement about result size or pagination, keeping it below 5.

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

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

Front-loaded summary sentence followed by a structured per-field breakdown; the parenthetical glosses for gn_layer and dataset_alternate earn their space. Slightly dense, with the one-line-per-kind framing doing most of the work, but there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape needn't be spelled out — yet the description covers the interpretive edge cases (null vs. empty, missing gn_layer) and the intended downstream use with create_scenario. Nothing an agent needs to select and call this correctly is missing.

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

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

There is a single parameter with 100% schema coverage, so the schema already defines project_id. The description adds nothing about the parameter itself (e.g. what happens with an unknown or empty project), so the baseline 3 applies.

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

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

States a specific verb and resource ('List every input layer row of a project') plus the exact scope: per kind, with has_features. The enumeration of kinds (boundary, friction, inflow, rainfall, building, mesh_region, culvert) makes it clearly distinct from list_projects, describe_input_kinds and list_terrain_sources without needing the schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use the row ids with create_scenario; this is the listing primitive — no need to probe files', giving both a downstream consumer and a negative instruction that steers the agent away from an alternative approach. It stops short of naming a sibling tool (e.g. describe_input_kinds) as the alternative, so it is not a full 5.

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

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

Annotations already declare the safe read-only, idempotent profile. The description adds behavioral context the annotations cannot: an 'unknown' datum is not scored, and 'problems' are validation failures that are reported but never fixed. These are non-obvious semantic traits beyond the structured fields.

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

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

Two sentences, front-loaded with the mode split before the field inventory. The second sentence is dense with a nested parenthetical, but each listed field and clarification earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return fields need not be enumerated, yet the description's semantic annotations (datum scoring rule, never-fixed problems, fid as the mutation key) add genuinely useful context. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by tying each layer_id state to a distinct result shape and by flagging that the returned `fid` is the key required by update_observation/delete_observation, giving the parameter operational meaning beyond its schema text.

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

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

States a specific verb+resource and immediately splits the two modes (project's layers vs. one layer's observations) governed by layer_id. It also names the downstream siblings (update_observation / delete_observation) whose key is the returned fid, so an agent can distinguish this from those tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly explains the two invocation modes and which parameter selects each ('Without layer_id: ... With layer_id: ...'), giving an agent enough to choose correctly. It stops short of explicit when-not-to-use guidance or naming the create/add observation siblings as alternatives, so it lands just below the top.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, covering the safety profile. The description usefully adds that results are paginated and scoped to the authenticated user, but discloses nothing about ordering, total counts, or filtering behavior.

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

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

Two tightly written sentences with the scope front-loaded. The second sentence listing returned fields is largely redundant given the tool has an output schema, so it doesn't fully earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a simple paginated list: annotations carry the safety profile, the schema covers both parameters at 100%, and an output schema handles return values. The only gap is the absence of routing guidance versus get_project.

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

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

Schema description coverage is 100%, so both page and page_size are fully documented in the schema. The description adds no parameter-level meaning beyond that, making the baseline 3 correct.

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

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

Names a specific verb (List) and resource (ANUGA simulation projects) with an explicit scope: 'accessible to the authenticated user.' This cleanly distinguishes it from the singular get_project sibling without needing to name it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied by the plural 'List' versus the singular get_project. The description never states when to prefer this over get_project for a single lookup, nor any prerequisites or exclusions, so an agent must infer the routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral context beyond them: pagination behavior and the notable fact that presigned s3_*_url download links are elided with a 6-hour capability lifetime. That return-shape caveat is something the agent could not infer from the schema.

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

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

Front-loads the core action in the first sentence, then adds only three short supporting sentences; no filler. Minor cost is that pagination and status filtering are split across separate short sentences that could compress slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be enumerated, and annotations carry the safety profile, so the description is nearly sufficient. The one extra detail it does provide, elided presigned URLs, meaningfully closes the remaining gap between what the schema shows and what a caller actually receives.

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

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

Schema description coverage is 100%, with every parameter including the full status_filter value list documented inline, so the schema does the heavy lifting. The description only gestures at status filtering and pagination, adding no syntax or format detail beyond the schema, which is the correct baseline.

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

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

States a specific verb and resource with precise scope: 'List all simulation runs across all scenarios in a project.' An agent can immediately distinguish this bulk-list operation from the singular get_run, get_run_status, and the unrelated list_projects/list_inputs siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for use (list a project's runs, optionally narrowed by status) but names no alternative tool or exclusion condition, e.g. it never says to prefer get_run when a single run ID is already known.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds genuine behavior: results are ordered finest-first, only sources with non-zero coverage are returned, Copernicus GLO-30 always appears, and oversized requests are surfaced via cap.state and a plain message. The row-field enumeration overlaps with the output schema, which is the only reason this isn't a 5.

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

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

Front-loaded with purpose, then the ordering constraint, then the workflow instruction — good structure with no filler. The middle enumeration of row fields ('key', 'name', 'resolution_m', ...) is long and partly duplicates the output schema, costing a point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value detail is optional; the description still supplies what the agent needs to act (which field to pick, what 'coverage_pct' means, how to handle 'too_large'). The only loose end is the mention of `say_to_user`, which is not among the listed sibling tools.

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

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

Schema description coverage is 100% and both parameters are documented there, so the description adds little parameter detail. It only obliquely ties 'your box' to bbox via coverage_pct; no added semantics for project_id or the bbox format.

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

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

States a specific verb+resource ('List the terrain sources') plus an ordering guarantee ('finest resolution first'). It is clearly separable from sibling tools that upload terrain (presign_terrain_upload, finalize_terrain_upload) or consume a source key (create_terrain_from_source).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit sequencing guidance: 'Ask this BEFORE fetching or uploading your own DEM' names the alternative path (uploading a DEM) and its preconditions. It also names the downstream tool (create_terrain_from_source) and the selection rule ('Pick one whose cap.state is ok'), leaving no inference to the agent.

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

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

Annotations already declare read-only, idempotent, non-destructive; the description goes beyond them by disclosing that row data is dropped and the reason (a project's list is megabytes), which is exactly the behavioral context annotations can't express. It omits pagination/ordering behavior, so not a 5.

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

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

Front-loaded with the verb, scope, and the row exclusion before the field list; no filler sentences. The field enumeration partly duplicates the existing output schema, which costs it a point, though the semantic notes attached to fields keep it earning its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with an output schema, the definition is essentially complete — what it returns, what it omits, and where to go for values. Only missing element is ordering/pagination expectations for a potentially large list.

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

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

Schema coverage is 100% for the single project_id parameter, so baseline is 3. The description's 'a project's time series' reinforces scoping but adds no format, ID-source, or validation detail beyond the schema.

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

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

States a specific verb+resource ('List a project's time series') and immediately bounds scope with '— never their rows', heading off the most likely misuse. The parenthetical examples (rain gauges, hydrographs, tides) make the resource concrete, and it is clearly separable from create/update/delete_time_series siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when not to expect values and names an alternative path ('fetch one series with the REST API (GET /projects/<id>/time-series/<id>/)'). It does not distinguish itself from nearby siblings such as get_project or list_inputs, so the routing advice is clear but not exhaustive.

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

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

Annotations are thin (readOnlyHint=false, destructiveHint=false), so the description carries real weight and delivers: nothing exists in Hydrata until finalize, the URL expires after 3600s, the Content-Type is signed and a mismatch yields 403 SignatureDoesNotMatch, and draft keys get 403 AGENT_LEVEL_INSUFFICIENT on finalize. It also discloses size cap (5 GiB) and CRS/reprojection behavior.

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

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

Front-loads purpose and the routing decision, then sequences prerequisites, the curl example, and the fallback — a logical flow. It is long, and the platform extent guidance (5°/40,000 km²) and multipart fallback run past the immediate call, but each remains actionable context rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a multi-step upload handshake with an output schema already covering return values, the description supplies everything an agent needs to call correctly: prerequisites, exact PUT semantics, the follow-up call with staging_key and process_id, and the escalation path when the key is insufficient.

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

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 genuine meaning beyond the schema — that content_type is SIGNED into the URL and must be echoed verbatim on the PUT, and that size must be a byte count with a 5 GiB rejection threshold. It does not add much on project_id or filename that the schema lacks.

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

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

States a specific verb+resource ('get a presigned S3 PUT URL for a GeoTIFF DEM') and situates it as step 1 of a multi-step import that continues in finalize_terrain_upload. It explicitly names the sibling alternatives (list_terrain_sources, create_terrain_from_source) so an agent can distinguish it without opening sibling schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use ('a client that has a shell and an agent key AND a DEM no platform source covers') and when-not ('a connector agent with no shell (claude.ai) uses list_terrain_sources then create_terrain_from_source instead'). It also names a fallback path (multipart POST) for cases where presigned PUT is impossible, and states the key-level prerequisite.

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

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

Annotations declare readOnlyHint/idempotent/non-destructive, and the description explains why: nothing is created until the person drops a file. It adds behavior beyond the annotations — accepted formats, 100 MB cap, conversion into the project grid, replacement of existing layer content, 'uploaded by user' authored_method, no review step, and wrong-kind rejection at the page.

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

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

The core instruction (get the link, give the person ui_url) is front-loaded and followed by consequences and follow-up steps in a logical order. Slightly long, with the 'building footprints, land-use friction' examples and 'you cannot move file bytes' restating the size rationale, but every sentence carries usable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Two required parameters, an output schema, and full annotation coverage — and the description still supplies the operational picture (what the human does, size/format limits, permission requirement, post-call verification via list_inputs). Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the enum-free kind field is already documented, but the description adds meaning: kind selects which layer is replaced, and a file of the wrong kind (polygons on an inflow) is refused. project_id gains only the Editor-access context, which is marginal but useful.

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

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

States a specific verb and resource (get the browser upload link for a big input layer) and immediately scopes it against the sibling write_input_layer by size threshold. An agent can tell exactly what this returns and when it is the right tool 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: use this for layers too big to send with write_input_layer (over about 150 KB), because the agent cannot move file bytes. It also names the follow-up step (call list_inputs) and the prerequisite (Editor access), leaving nothing to inference.

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

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

Beyond annotations, the description discloses important side effects: a new package build is triggered, AWS Batch may be started, a new run becomes the scenario's latest run, and the old errored run is preserved as history. It also flags a non-obvious response quirk: the response describes the old run while the new run ID must be read from get_scenario's run_id. This is exactly the kind of context annotations cannot provide.

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

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

The description is front-loaded with the core action, then immediately covers authorization, side effects, response semantics, and state validation. Each sentence carries useful information, and the surprising response behavior is called out clearly without excess.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even though an output schema exists, the description adds necessary operational context: auth requirements, valid state, side effects on scenario history, and how to obtain the new run ID. Nothing an agent needs in order to invoke this tool correctly appears to be missing.

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

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

There is only one parameter, and schema coverage is 100%, so the schema already explains run_id as 'The run ID to retry.' The description reinforces that only errored runs are valid targets, but it adds little parameter-level syntax or format beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Retry a failed simulation run.' It goes further to distinguish the operation from a plain re-run by stating it starts a fresh package build as a NEW run while preserving the errored run as history. This clearly separates it from siblings like start_simulation and get_run.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states explicit preconditions: a launch-level agent key is required, and a read or draft key returns 403 AGENT_LEVEL_INSUFFICIENT. It also says the tool is only valid when status is 'error' and returns 409 otherwise, which is exactly the when-to-use guidance an agent needs.

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

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

Annotations already declare this is a non-destructive, idempotent write, but the description adds genuinely new behavioral context: the Editor-or-above permission requirement and the persistent downstream effect on every later get_observation_comparison call and the map's Compare with observations tab. It doesn't discuss overwrite semantics or validation failure behavior, keeping it short of a 5.

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

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

Three short sentences, front-loaded with the action, then prerequisites, then the routing rule. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the description covers purpose, permissions, persistence effect, and alternative routing. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, with both parameters (project_id, tolerance_m) fully documented including the metres range and presets, so the schema carries the load. The description adds no parameter-level detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb (save/set) and resource (project's default comparison tolerance for comparing runs with flood observations), and explicitly distinguishes it from get_observation_comparison, which reads figures rather than persisting a default. An agent can tell exactly what this does 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when ('only save it when the user asks to change the project's default') and when-not, plus the alternative ('to show the figures at another tolerance, pass `tolerance` to get_observation_comparison'). Nothing is left to inference.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and the description adds real substance beyond them: the exclusion is logged with user and reason, nothing is overwritten, it is keyed on (run, layer, fid) so it survives a recompute, and figures update immediately via headline_after. No contradiction with annotations.

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

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

Front-loaded with the core action, then permissions, durability, and the reason requirement in a logical order. Every sentence carries information, though the reason rule is restated in both description and schema, which is slightly redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a stateful toggle tool with an output schema, the description covers permissions, idempotency/durability semantics, and the immediate-figure-change behavior (headline_after). Nothing an agent needs 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.

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

Schema description coverage is 100%, so the schema already documents all five parameters including the reason-required-to-exclude rule. The description reinforces that rule but adds little syntax or format detail beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb+resource ('Exclude a flood observation from ONE run's comparison... or include it again'), clearly a toggle keyed to a single run. This distinguishes it from siblings like get_observation_comparison and set_comparison_tolerance without opening their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear operational context: Editor (or above) permission is required, and it must be keyed to one run. It also instructs the agent to ASK the user for a reason rather than invent one, which is strong guidance. It lacks explicit when-not-to-use vs siblings, so 4 rather than 5.

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

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.

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.

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.

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.

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.

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.

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

Beyond the annotations it discloses a concrete rate limit (20 per day per person), a data-handling constraint (no personal data, keys or file contents), and a follow-up contract (relay `say_to_user` verbatim). The statement that it changes none of the person's data is consistent with readOnlyHint=true and destructiveHint=false rather than a restatement of them.

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

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

Usage constraints are front-loaded and each sentence carries a distinct rule (precondition, exclusions, content rules, effect, reply handling, quota). Slightly dense with stacked parentheticals, and 'changes none of the person's data' partly overlaps the readOnly annotation, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, yet the description still tells the agent what to do with the reply (`say_to_user`). For a 2-parameter escalation tool, nothing needed to call it correctly or handle its result is missing.

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

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

Schema coverage is 100%, so both fields are already documented, but the description still adds guidance the schema lacks: describe the need rather than a workaround, and never include personal data, keys or file contents. The required `what` field gets one/two-plain-sentences style guidance from the schema rather than the description, which keeps this just under a 5.

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

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

The first sentence states a specific verb and resource — reporting a missing capability to the Hydrata team — and the 'NO existing tool can do' framing immediately separates it from every CRUD/simulation sibling in the list. An agent can identify this as the escalation/feedback channel without inspecting the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit precondition ('only when you have checked the other tools and none can do what the person asked') plus two explicit exclusions: never for bugs, and never as a substitute for a tool that already can do it. That is a complete when/when-not rule set with no inference required.

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

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

Annotations only carry the safety profile (readOnly=false, idempotent=true, destructive=false, openWorld=false); the description adds genuinely new behavior: PATCH merge semantics, atomic validation against the stored observation, the 400 failure mode with all bad fields named, and the explicit exclusion of photos. This tells an agent what happens on failure and why no half-valid state is stored.

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

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

Purpose and mutation mode are front-loaded in the first clause, followed by the two details an agent actually needs (validation failure behavior, photo routing). Slightly prose-heavy wrapping but every sentence carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a four-parameter mutation tool with an output schema and full annotation coverage, the description supplies the missing pieces: idempotent partial-update semantics, validation/refusal behavior, and where photo attachments belong. Nothing needed to call it correctly is absent.

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

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 reinforces the meaning of 'changes' as a merge patch (only supplied fields change, merged with the stored record) and explicitly scopes photos out of the field set, which is not stated in the schema.

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

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

States a specific verb and resource ('Edit one flood observation') and immediately qualifies it as PATCH-style partial mutation, which cleanly separates it from add_observations, delete_observation, and add_observation_photo_link in the sibling list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the operative rule (only fields given change) and routes photos to add_observation_photo_link, which is real alternative-selection guidance. It stops short of stating when a partial edit is preferred over delete+re-add, so it is clear context without explicit exclusions.

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

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

Goes well past the annotations: discloses that only passed fields change, that Hydrata rejects requests with plain-language reasons, and — critically — that correcting a series already used by a built scenario forces a rebuild and user re-review. That downstream consequence is exactly the kind of side effect annotations cannot express. It also notes the return is a compact record rather than rows.

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

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

Front-loads the verb and the PATCH contract in the first clause, then layers validation rules, then the scenario consequence in order of increasing risk. No sentence is padding; the density is appropriate for a nine-parameter mutation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the operation semantics, validation behavior, failure modes, and the cross-tool side effect on built scenarios, which is the main risk an agent needs to know before calling. An output schema exists, and the description still usefully clarifies the return shape is a compact record rather than the rows.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents every parameter including the rowData shape and validation limits. The description adds the conditional rule that a hydrograph or hyetograph must end at 0 unless hold_last_value, but that constraint already appears in the parameter docs, so it is mostly reinforcing rather than new.

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

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

States a specific verb and resource ('Correct a time series you created') and immediately distinguishes the operation as a PATCH with partial-update semantics. An agent can tell it apart from create_time_series and delete_time_series without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use it to fix a series instead of leaving a wrong one behind' gives a clear trigger condition, and the explicit cross-reference to create_time_series rules tells the agent what validation contract applies. It does not, however, state when to prefer delete_time_series plus recreate over a correction, so the alternative path is left implicit.

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

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

Goes well beyond the annotations: says the existing default layer is replaced but kept and unlinked, that a geometry mismatch refuses the entire write atomically, the ~150 KB pre-flight limit, that the layer is attributed to the agent key and is UNREVIEWED until browser review. These are precisely the side-effect and state details the hints (destructive=false, idempotent=false) cannot convey.

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

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

The payload, the replace behavior and the size limit are front-loaded, with the safety-critical inflow warning last. Dense but a couple of clauses ('No file, no key, no upload') restate the same idea the preceding sentence already made.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need no prose. For a write tool with a nested GeoJSON payload, the description covers validation failure modes, size ceiling, coordinate assumption, review state and the escalation path — everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by adding per-kind geometry constraints (lines for boundary/inflow/culvert, polygons for friction/rainfall/building/mesh_region) and culvert structure (one two-point line, Inlet then Outlet) that the schema's FeatureCollection description does not state. The `method` parameter is only covered in the schema, not the prose.

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

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

Names a specific verb (write) and resource (project input layer) and enumerates the seven kinds it accepts. It is immediately distinguishable from siblings attach_input_layer and request_input_upload, which are named in the text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes away from attach_input_layer ('nothing to poll') and instructs the agent to use request_input_upload plus a browser upload when the payload exceeds ~150 KB. Also gives an exclusion for inflows ('never invent an inflow location'), which is a when-not rule.

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