Hydrata - ANUGA Flood Simulation

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

With no annotations provided, the description carries full disclosure burden and succeeds well: it details destructive side effects ('terminates EC2 instance, Celery task, or Batch job'), documents error conditions (409 response for terminal states), and specifies the status lifecycle constraints. It omits idempotency or async behavior details, but covers the critical operational risks.

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 sentences structured logically: action definition, operational scope/cleanup effects, and error handling. No redundant words. High information density without verbosity. The technical implementation details (EC2, Celery, Batch) are relevant to the cleanup behavior and warrant inclusion.

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?

Appropriately complete for a cancellation tool with an output schema. Covers the full lifecycle (valid statuses → cleanup → error), underlying infrastructure impacts, and HTTP error codes. Given the complexity of distributed compute cleanup, mentioning specific technologies (EC2, Celery, Batch) provides necessary context for understanding the scope of the operation.

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?

Input schema has 100% coverage with 'run_id' fully documented as 'The run ID to cancel'. Since the schema completely describes the parameter, the description appropriately focuses on behavioral context rather than repeating parameter documentation. Baseline 3 is correct for 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?

The description opens with a precise action statement: 'Cancel an in-flight simulation run.' It uses a specific verb (Cancel) with a specific resource scope (in-flight simulation run), clearly distinguishing it from siblings like start_simulation (creates new) and retry_run (restarts failed).

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 defines valid preconditions ('Works on runs in built, queued, or computing status') and invalid states ('Returns 409 if the run is already in a terminal state'). This implicitly guides selection over retry_run (for failed runs) and get_run_status (for checking), though it doesn't explicitly name those 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?

No annotations provided, so description carries full burden. Documents return payload (name, projection, base map ID, configuration) but lacks operational characteristics: error behavior for invalid IDs, data freshness, or performance implications of fetching associated scenarios.

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 efficient sentences: first establishes action and scope, second specifies return payload. No filler words. Information density is appropriate.

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?

Adequate for a simple 1-parameter read operation with existing output schema. Describes return structure sufficiently, though error handling and explicit sibling differentiation (particularly regarding 'scenarios') would strengthen completeness.

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 has 100% description coverage ('The project ID'), so baseline is 3. Description adds no additional semantics about project_id (e.g., source, format constraints, examples).

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?

Clear verb (Get) + resource (ANUGA project) + scope (details including scenarios). 'Specific' distinguishes from list_projects. However, mentioning 'scenarios' creates ambiguity with sibling get_scenario without clarifying the relationship.

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?

Implicit guidance via 'specific' suggests use when ID is known vs listing all projects. However, lacks explicit when-to-use/when-not guidance and doesn't clarify overlap with get_scenario despite mentioning scenarios.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It comprehensively enumerates the returned data fields (status, progress, timing, compute details, mesh info, error messages, result log), giving the agent clear expectations of what data is accessed. A minor gap is the lack of explicit read-only/safety declaration, though implied by 'Get'.

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 tightly constructed sentences: purpose declaration, return value specification, and usage guidance. Zero redundancy. Information is front-loaded with the core action in the first sentence, followed by elaboration and selection criteria.

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 retrieval tool. Despite having an output schema (which obviates the need for detailed return descriptions), the description helpfully previews the data structure. The single parameter is trivial, sibling differentiation is addressed, and no additional contextual gaps exist.

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% with the single parameter 'run_id' fully described as 'The run ID'. The description contextualizes this as identifying a 'simulation run' but does not need to elaborate further given the complete schema documentation. Baseline 3 is appropriate 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?

The description clearly states the specific action ('Get full details'), resource ('simulation run'), and scope ('including timing and results'). It explicitly distinguishes from sibling tool get_run_status by contrasting 'lightweight polling' vs 'final results', making selection unambiguous.

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?

Provides explicit comparative guidance: 'Use get_run_status for lightweight polling; use this for final results.' This directly maps usage scenarios to the correct tool, preventing the common error of using a heavy details call when a lightweight status check suffices.

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?

With no annotations provided, description carries full disclosure burden. It successfully provides critical performance data (<50ms response time), documents return payload fields, and defines terminal states. Lacks explicit mention of auth requirements or rate limits, though the polling interval implies throttling guidance.

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?

Highly structured with line breaks separating distinct concepts: performance, usage context, return values, polling frequency, and terminal states. Every sentence provides essential operational information with zero 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?

Exceptionally complete for a status-check tool. Despite having output schema available, description proactively documents return fields. Covers performance expectations, sibling differentiation, polling strategy, and lifecycle states—sufficient for correct agent implementation.

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?

Input schema has 100% description coverage ('The run ID' for run_id parameter). Description adds no additional parameter semantics, but baseline 3 is appropriate given complete schema documentation.

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?

Explicitly states 'Lightweight status check for a simulation run' with specific performance characteristics (<50ms). Clearly distinguishes from sibling get_run by stating 'Use this for polling instead of get_run', making tool selection unambiguous.

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?

Provides explicit usage guidance: when to use vs alternative (polling instead of get_run), how often to poll (every 5-10 seconds), and when to stop (terminal states: complete, error, cancelled). Covers the full polling lifecycle.

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?

With no annotations provided, the description carries full behavioral disclosure burden. It successfully explains that status is computed from latest run, enumerates all 9 possible status values (domain-specific state machine), and clarifies the 'built' prerequisite constraint. Missing only minor details like rate limits or caching 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?

Three sentences with zero waste: sentence 1 states purpose, sentence 2 documents status field behavior, sentence 3 states operational prerequisite. Information is front-loaded and each sentence earns its place by adding domain knowledge not present in structured fields.

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 existence of output schema (indicated in context signals), description appropriately focuses on domain logic (status states, prerequisites) rather than return structure. Adequately covers the 2-parameter input contract and scenario lifecycle complexity.

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% (both project_id and scenario_id fully described in schema). Description adds no additional parameter syntax, constraints, or cross-parameter logic, but this is acceptable given complete schema documentation. Baseline 3 appropriate 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?

Description uses specific verb 'Get' with resource 'scenario details' and scope 'including its current status and latest run.' It distinguishes from sibling 'get_run' by emphasizing it retrieves the scenario container with embedded status/run info, and from 'list_projects'/'list_runs' by being a specific ID-based retrieval.

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?

Provides explicit prerequisite guidance: 'A scenario must be in 'built' status before it can be run,' which directs usage relative to sibling 'start_simulation'. Lacks explicit 'when not to use' oralternative tool recommendations (e.g., when to prefer 'get_run' over this), but the status enumeration helps clarify return value interpretation.

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?

No annotations provided, so description carries full burden. Discloses pagination behavior ('paginated list') and previews return content ('names, projections, and base map references'). Could improve by mentioning behavior when no projects exist or auth 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?

Two sentences with zero waste. First sentence establishes scope (verb + resource + access control), second sentence discloses return format and key fields. Front-loaded with essential 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?

Appropriate for a standard pagination list operation. Given output schema exists, the description provides sufficient preview of return values. Covers auth context and pagination. Minor gap: no mention of maximum page size constraints (though present in schema) or empty result handling.

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% with clear descriptions for 'page' and 'page_size'. Baseline 3 applies. Description mentions 'paginated list' which semantically links to the parameters, but does not add syntax details, validation rules, or cross-parameter constraints 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?

Specific verb 'List' with resource 'ANUGA simulation projects' (domain-specific clarification beyond generic 'projects'). Plural form distinguishes from sibling 'get_project' (singular retrieval), and 'accessible to authenticated user' scopes the operation vs potential admin listing tools.

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?

Implied usage through 'accessible to the authenticated user' (suggests personal workspace listing) and plural 'projects' (distinguishes from single-item retrieval). However, lacks explicit guidance on when to use 'get_project' vs this tool, or relationship to 'list_runs'.

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?

With no annotations provided, the description carries the full disclosure burden. It successfully notes the pagination behavior ('Returns a paginated list'), but omits other critical behavioral traits: it does not confirm this is read-only (though implied), mention rate limits, error handling for invalid project_ids, or whether the list is sorted. Mentioning pagination saves it from a lower score.

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 optimally structured with three tight sentences: purpose first, return format second, and optional filtering third. Zero wasted words—'Returns a paginated list' efficiently explains both the output type and the need for page parameters. Every sentence 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?

Given the input schema has 100% coverage, the output schema exists (removing the burden to describe return values), and the tool has only 4 simple parameters, the description is appropriately complete. It covers the essential operational context (pagination, filtering) that structured fields do not convey, though it could have mentioned the read-only nature given the lack of annotations.

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%, establishing a baseline of 3. The description adds valuable semantic context beyond the schema: 'across all scenarios' clarifies the scope of project_id, and mapping status_filter to user-friendly terms ('active, completed, or failed') helps agents understand the filter's purpose. The mention of 'paginated' also gives meaning to the page parameters.

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 clearly states the verb 'List' and resource 'simulation runs', with specific scope 'across all scenarios in a project'. However, it does not explicitly distinguish this bulk operation from sibling 'get_run' (likely single-run retrieval), which could confuse agents on which to select.

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 provides implied usage context by mentioning optional status filtering ('to find active, completed, or failed runs'), but lacks explicit guidance on when to use this versus 'get_run' for single-run lookups or versus 'get_run_status' for status checks. It does not state prerequisites like requiring a valid project_id first.

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?

With no annotations provided, the description carries full behavioral disclosure burden and succeeds admirably. It reveals state mutations ('Resets an errored run back to 'created' status'), side effects ('triggers a new package build'), resource handling ('The same run ID is reused'), and error responses ('Returns 409').

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 structure is efficiently front-loaded: single-line purpose statement, followed by technical mechanics (reset, build trigger, ID reuse), then constraints and error codes. Every sentence delivers specific operational information without 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?

Given the existence of an output schema (which obviates the need to describe return values), the description comprehensively covers the necessary domain context: the exact state precondition (error), the internal state machine transition (to 'created'), and side effects. Complete for a state-transition mutation 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% with 'The run ID to retry' already clear. The description adds valuable semantic context beyond the schema by specifying 'The same run ID is reused,' clarifying that this is an idempotent update to an existing resource rather than creating a new entity with a new ID.

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 'Retry a failed simulation run' provides a specific verb (retry) and resource (simulation run). It clearly distinguishes from sibling 'start_simulation' by emphasizing the retry aspect and from read-only siblings like 'get_run' or '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?

The description explicitly states the precondition 'Only valid when status is 'error'' and the failure consequence 'Returns 409 for any other state,' providing clear when/when-not guidance. It lacks explicit mention of alternatives (e.g., 'use start_simulation for new runs'), but the constraint documentation is thorough.

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?

With no annotations provided, the description carries full disclosure burden. It documents the state machine lifecycle ('built → queued → computing → processing → complete'), HTTP response codes (202, 409), and implies async nature via the polling instruction. Could benefit from explicit mention of idempotency or permission requirements.

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 tightly constructed sentences each serving distinct purposes: action+precondition, return value+lifecycle, polling guidance, and error handling. Front-loaded with the core action and zero redundant text.

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 an async operation starter: documents HTTP response codes, references the output schema implicitly by not duplicating return structure details, explains the full state transition lifecycle, and links to the specific monitoring tool (get_run_status).

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 (scenario_id and compute_backend) fully documented in the schema including default values and options. The description provides no additional parameter semantics beyond the schema, meeting 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?

The description opens with a specific verb ('Start'), clear resource ('flood simulation run'), and precondition ('for a built scenario'), distinguishing it from read-only siblings like get_run_status and from retry_run which handles existing runs.

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?

Provides explicit prerequisites ('scenario must be in built status'), names the specific sibling tool for polling ('poll get_run_status'), and documents error conditions ('Returns 409 if not in correct state'), giving clear when-to-use and when-not-to-use guidance.

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