DataQuoll

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

The readOnlyHint annotation already establishes safety, and the description adds valuable behavioral context: the required entitlement and the important distinction between an error from lack of entitlement versus an empty result. It also clarifies the data-merging and LGA-list 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 sentences carry all essential information with no filler. The main purpose is front-loaded, and the auth/error nuance is placed second where it can be absorbed without distracting from the tool's primary function.

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 simple single-parameter lookup with no output schema, the description adequately covers what the tool returns (declaration/activation merged across sources with full affected-LGA list), who can call it, and how errors behave. Nothing necessary for a correct call 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?

With 0% schema description coverage, the description compensates by expanding AGRN to 'Australian Government Reference Number' and clarifying it identifies a declaration/activation. It provides the core semantic meaning for the single parameter, though it does not give format or example.

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 identifies the resource as a declaration/activation for an Australian Government Reference Number and distinguishes it by noting the merged-across-sources scope and full affected-LGA list. An explicit verb like 'retrieves' is missing, but the title and phrasing make the read/lookup intent clear.

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 gives clear context: this is the tool for looking up a single declaration/activation by AGRN with cross-source merging and the full affected-LGA list. It also provides a prerequisite, the 'declarations' entitlement. It does not explicitly describe when to use other sibling tools, but the by-identifier purpose is unambiguous.

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 readOnlyHint annotation, the description discloses that the request is safe to retry, coordinates are never stored/logged/echoed, responses use Cache-Control: no-store, and missing entitlements produce a clear error rather than an empty result. This is substantial behavioral context that annotations alone do not 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 purpose, then efficiently covers method rationale, privacy behavior, return edge cases, boundary resolution quirks, and entitlement requirements. Every sentence adds distinct information; none are redundant 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?

Given there is no output schema, the description does a strong job of explaining key return behavior: unknown_location for outside points, onBoundary=true for shared boundaries, and per-LGA lists. It does not enumerate every possible status value or the full response envelope, so a bit of return-value detail remains unspecified, keeping this just below a 5.

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 60%; lat and lng have no schema descriptions, and the description adds meaning to them by explaining that they are resolved against ABS LGA 2022 full-resolution boundaries and by covering outside/boundary edge cases. The optional parameters as_at, include_expired, and instrument_type are already described in the schema, so the description does not need to repeat them.

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: it returns declaration STATUS for the local government area containing a lat/lng point. The 'exact point' framing and LGA-boundary resolution clearly separate it from siblings like declarations_by_postcode and declaration_by_agrn, even though those alternatives are not named.

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 gives clear context for when this tool applies: you have an exact lat/lng point and need declared-area status only. It also explains boundary cases and scope, but it does not explicitly say 'use declarations_by_postcode instead for a postcode' or provide an exclusion list, so it stops short of a 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?

Beyond the readOnlyHint annotation, the description discloses the entitlement requirement, the error-versus-empty behavior for unauthorized accounts, and that the result is declared-area status only, which prevents an agent from over-interpreting a 'not_declared' result. It also flags that suburb narrowing can legitimately change matchStatus.

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 result and status list, then layers usage, entitlement, and parameter nuance in readable paragraphs. Every sentence adds decision-relevant information; there is no filler or repetition.

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 no output schema, the description still tells the agent what the result contains (status, per-LGA detail, source links) and how each parameter behaves, including the important edge case of 'Mingoola in 4380'. It is complete enough for an agent to call this tool without guessing.

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?

Despite 80% schema coverage, the description adds substantial semantics: exact matching after normalisation with no fuzzy matching, unmatched-suburb fallback behavior, narrowing can change matchStatus, and include_expired/instrument_type never change matchStatus. This is material guidance 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?

The description opens with a specific verb and resource: 'Returns the declaration STATUS for a postcode', enumerates the possible statuses, and adds per-LGA detail plus source links. This clearly distinguishes it from point- and AGRN-based sibling tools such as declarations_by_point and declaration_by_agrn.

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 a clear intended context ('Built for Medicare disaster telehealth checks') and explicit exclusions ('Reports declared-area status only... billing/eligibility decision rests with the practitioner'). It does not explicitly name sibling tools as alternatives or state when to prefer declarations_by_point, so it stops just short of a 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?

The readOnlyHint annotation already covers the safety profile. The description adds meaningful behavioral context by stating that it returns attribution information for all data sources and includes licence details, which goes beyond the bare annotation.

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 a single sentence with a clear subject, action, and scope, followed by a purposeful compliance note. Every word earns its place; there is no fluff or 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?

For a zero-parameter, read-only metadata tool, the description fully equips an agent to select and invoke it. It explains what data is returned, highlights the licence detail, and states the compliance purpose. No output schema is needed for this level of simplicity.

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 tool has zero parameters and 100% schema coverage vacuously, so the baseline of 4 applies. There are no parameter semantics to document, and the description appropriately focuses on the output instead.

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 uses a specific verb ('Returns') and names the exact resource ('attribution information for all data sources'), including licence details. This clearly distinguishes it from the sibling tools, which all concern domain-specific declarations, incidents, or gauges.

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 phrase 'Required for CC BY compliance' gives a clear context for when this tool should be used. There are no overlapping sibling tools offering similar attribution data, so explicit exclusion guidance is less necessary, though the description does not spell out when not to use 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?

Annotations already declare readOnlyHint=true, so the description does not need to establish safety. The description adds functional detail about include_incidents but no additional behavioral traits such as error cases, pagination, or response structure beyond what the annotation implies.

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 two concise sentences with no filler. The primary behavior is stated first, and the optional parameter behavior is a natural addendum.

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 simple read-only tool with two parameters and no output schema, the description provides enough to invoke it correctly: the ID identifies the event, and the optional flag controls incident inclusion. It does not describe the full response shape, but this is a minor gap given the tool's simplicity.

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%, but the description enriches the include_incidents parameter by clarifying that setting it to true retrieves 'all incidents that belong to this event cluster,' which is more specific than the schema's generic 'Include linked incidents in the response.'

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 uses a specific verb and resource: 'Returns a single clustered event by ID.' It clearly distinguishes from sibling tools like list_events and get_incident by emphasizing the clustered-event concept and the optional linked-incidents 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?

The description conveys clear usage context: use this tool when you need a single event by its ID, optionally including its linked incidents. It does not explicitly name alternatives or exclusions, but the single-event scoping is unambiguous enough for an agent to select it over list-style 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?

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds useful context about the 6-hour recent window and raw readings, which goes beyond the annotation. It does not describe response structure or pagination, but for a simple read-only tool this is acceptable.

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 two sentences with no filler. The first sentence front-loads the core behavior, and the second provides a relevant pointer to the deeper-history endpoint. 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?

For a one-parameter, read-only tool with no output schema, the description covers the essential facts: what is returned, the time window, and where to obtain deeper history. It lacks field-level response detail, but that is not required for correct invocation. It is sufficiently complete for an agent to select and call the tool 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% for the single id parameter, including a concrete example ('hydstra-nsw-410001'). The description itself adds no parameter-level semantics, so the baseline of 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 uses a specific verb ('Returns'), a specific resource ('a single gauge station'), and a specific scope ('trailing 6 hours of raw readings'). It clearly distinguishes this tool from list_gauges (multiple stations) and get_gauge_summary (summary rather than raw readings).

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 points to the /gauges/{id}/readings endpoint for deeper history, creating a clear when-not-to-use boundary. It implies usage for checking the current trend ('enough to see the current trend'), but does not enumerate all alternative siblings such as get_gauge_summary.

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 readOnlyHint annotation already signals a safe read, but the description adds meaningful behavioral detail beyond that: the 500-station cap and, more importantly, the STALE GUARD rule that stale readings are excluded from class counts. This materially changes how an agent should interpret the results.

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, both information-dense. The core output is stated first, and the critical stale-readings caveat is highlighted and separated clearly. No filler or repetition.

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 absence of an output schema, the description does a good job outlining both the count summary and the list output, including the 500 cap. The main gap is that the 'staleness horizon' is not quantified, so an agent must still discover that boundary elsewhere.

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 descriptions already cover groupBy and variable, including the default behavior and rain-gauge exclusion. The tool description mostly restates the grouping concept and does not add parameter-level meaning for the undocumented state parameter, though the title and context make its purpose fairly evident. With 67% schema coverage this is adequate but not exceptional.

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 specifies exactly what the tool returns: counts of gauges at each flood classification threshold, grouped by state or LGA, plus a capped list of stations. This clearly differentiates it from sibling tools like list_gauges or list_gauge_readings, which return different kinds of data.

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 intended use case is implied by the description: get flood-status counts and at-or-above-minor stations, grouped by geography. However, there is no explicit guidance on when to prefer this over siblings, nor any stated exclusions or 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?

The readOnlyHint annotation already signals a safe read operation. The description adds the key behavioral detail of the return type (GeoJSON Feature). While it does not discuss edge cases like not-found behavior, this is minor for a simple getter with annotations covering the safety profile.

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 a single sentence with no wasted words. It front-loads the core resource ('a single incident') and specifies the output format, earning every word's 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 low complexity (one parameter, no nested objects, no output schema), the description, schema, and annotation together are sufficient for an agent to select and invoke the tool correctly. The return format is stated, the parameter is documented, and the read-only nature is annotated.

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 the 'id' parameter fully documented including an example format. The description adds no parameter semantics beyond what the schema provides, so the baseline of 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 ('Returns'), resource ('a single incident'), and return format ('GeoJSON Feature'). This clearly distinguishes it from sibling tools like list_incidents (plural) and get_event (a different resource type), so an agent can tell what it 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?

The description implicitly conveys usage: retrieve one incident by ID. However, it does not explicitly state when to prefer this over siblings such as incident_snapshot or nearby_incidents, nor does it mention any exclusion conditions. No alternatives are named.

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 readOnlyHint annotation already marks this as read-only, and the description adds a useful behavioral fact: 'No authentication required.' It also discloses that the returned enum set is exhaustive for the listed fields. The output format is not specified, but this is a simple zero-parameter metadata endpoint.

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 short, focused sentences with no filler. The core purpose and the practical usage instruction are both front-loaded.

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 zero-parameter, read-only metadata tool, the description is complete. It explains what the caller will get (valid enum values), why to call it (to discover filter values), and the auth expectation. No output schema exists, but the description sufficiently covers the return value semantics.

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 tool has zero parameters and the schema already reflects that, so there is no parameter burden for the description to carry. The baseline of 4 applies here.

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 tool returns all valid enum values for event types, categories, states, warning levels, and other filterable fields. This makes it immediately distinguishable from sibling data-retrieval tools like list_events or list_states.

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 says to use this tool to discover what values are accepted by filter parameters. It does not name alternatives, but no sibling tool appears to provide schema/enum discovery, so the usage guidance is clear and sufficient.

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 readOnlyHint annotation, the description discloses the POST body design, that coordinates are never stored/logged/echoed, Cache-Control: no-store, the required hazard-history entitlement, the no-record-is-not-evidence caveat, and per-record precision. All of this is consistent with the readOnlyHint.

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 purpose and structured into logical details: lanes, example, HTTP behavior, privacy, limits, and entitlement. It is longer than average, and a few caveats are restated, but the density is high for a complex tool.

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 no output schema and only a read-only annotation, the description carries the burden of explaining what comes back: two lanes, AGRN deduplication, declared status, and precision. It also covers auth, retry safety, privacy, and disclaimers, making the endpoint fully usable by an agent.

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 input schema already describes every parameter, including bounds and defaults, so the baseline is 3. The description adds no parameter-specific guidance beyond what the schema says; it mostly contextualizes the two lanes, which is return behavior rather than parameter semantics.

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 purpose—'Observed record and declared status for an exact point'—and then details exactly what is returned: an observed lane of historical/live incident records within a radius and a declared lane of LGA disaster declarations. This clearly distinguishes it from point/incident-only siblings like nearby_incidents or declarations_by_point.

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?

Clear context is provided: the tool is for exact coordinates, combines two required lanes, and is safe to retry because it is read-only. It even gives a concrete use example (Lismore flood via declared lane) and notes it is not a risk/insurability assessment, but it never explicitly names sibling tools or states when to choose another endpoint.

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: true, and the description adds substantial behavioral detail: data reconstruction from live/lifecycle versus historical archive, the 2026-04-08 cutoff, tier-based lookback limits, archive state-filter requirement, and meta.source output hint. This goes well beyond the annotations and gives the agent a solid mental model of 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?

The description is dense but every sentence carries necessary information: purpose, data source behavior, tier restrictions, archive requirements, and result provenance. The main purpose is front-loaded, and the detail is organized logically without repetition.

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?

The description covers the most important operational nuances: archive cutoff, tier access, required filter, and source indicator. There is no output schema, so a little more detail about the result shape would improve completeness, but the description is sufficient for an agent to select and invoke the tool 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?

The input schema covers all four parameters with descriptions, so the baseline is 3. The description adds meaningful context beyond the schema by explaining the live/archive split, the exact cutoff date, why a state filter is required for archive snapshots, and how tier affects archive access. This helps the agent interpret datetime and state more effectively.

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 and resource: 'Returns the incidents that were active at a specific point in time.' This clearly distinguishes the snapshot operation from sibling tools like list_incidents or get_incident, and the temporal focus is immediately evident.

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 clear context about when archive vs live data applies, tier lookback restrictions, the requirement for a state filter on archive snapshots, and how to identify the data source via meta.source. It does not explicitly name alternative sibling tools, but the conditions for using this tool are well specified.

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 annotations only declare readOnlyHint, and the description adds substantial operational context beyond it: status is derived at query time, the API key must hold the 'declarations' entitlement, and the error-vs-empty-result semantics are spelled out ('an empty response never means not entitled'). This is exactly the kind of behavioral disclosure that prevents an agent from misinterpreting results. It does not contradict the read-only annotation.

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?

Very compact and front-loaded: the first sentence states the purpose, the second scopes filtering and pagination, the third clarifies status derivation, and the final sentence covers the entitlement/error nuance. Every sentence earns its place with no filler, and the critical caveat about empty-vs-error is placed as a deliberate closing note.

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 seven parameters, zero enums, 14% schema coverage, and no output schema, the description leaves significant gaps: filter-value semantics are unexplained, and there is no mention of return shape, default page size, or date formats. The operational side (auth, error semantics, status derivation) is well covered, but for a browsing tool with heavily undocumented filter parameters, the missing semantics materially hinder correct invocation.

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 schema description coverage at only 14% (only cursor is documented in the schema), the description bears the burden for the other six parameters. It does explain keyset/cursor pagination, which aids understanding of limit and cursor, and notes that record status is derived at query time. But it never explains what status, active_on, jurisdiction, disaster_type, or instrument_type accept — formats, permitted values, or semantics are entirely absent.

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 pair ('Browse and historically report on declaration records') that clearly positions this as the general collection-listing tool, in contrast to lookup-shaped siblings like declaration_by_agrn, declarations_by_point, and declarations_by_postcode. The filter/pagination mention reinforces the list scope. However, it never explicitly names the sibling alternatives, so differentiation relies on the reader's 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?

No explicit when-to-use or when-not-to-use guidance is given. The description never names alternatives like declarations_by_point or declarations_by_postcode for location-based queries, nor declaration_by_agrn for single-record lookups. The 'browse/report' framing implies general listing, but an agent is left to infer which tool to route to.

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=true, so the safety profile is known. The description goes beyond this by disclosing the output format, the clustering algorithm (PostGIS ST_ClusterDBSCAN), per-event fields, and the active-only default filter. It does not mention pagination or rate limits, but for a read-only aggregation tool this is meaningful, useful behavioral context.

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 compact and front-loaded: the first sentence states the primary behavior and output format, with subsequent sentences adding clustering rationale, returned fields, and the default active filter. No sentence is redundant or wasteful.

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?

The description is sufficiently complete for a read-only, all-optional-parameter tool: it explains what is returned, what each event contains, and the default active-only behavior. Parameter details are covered by the schema, and the output shape is described even though no output schema exists. Minor gaps like exact filter semantics or pagination limits are not critical here.

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 descriptions for all five optional parameters, so the schema already documents parameter meaning. The description adds no parameter-specific details such as value formats or interactions, so it stays at the baseline rather than adding extra value.

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 tool 'Returns spatially clustered emergency events as a GeoJSON FeatureCollection,' naming a specific verb, resource, and output format. It also distinguishes itself from siblings like list_incidents and list_historical_incidents by emphasizing spatial clustering and the active-events default.

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 context is implied: the title 'incident intelligence' and the clustering language suggest this is for grouped incident views, not raw incident lists. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternative tools are named, so the agent must infer the appropriate context from sibling names.

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 readOnlyHint annotation, the description reveals a detailed retention ladder, tier lookback limits, flood-event window preservation, and the behavior of interval=auto. This gives the agent concrete expectations about data availability that are not encoded anywhere else.

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 main purpose and packs tier/retention details into a dense paragraph. Every sentence earns its place, though the tier and retention lists could be slightly more scannable. No filler or repetition.

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 7-parameter read-only tool with no output schema, the description covers purpose, tier restrictions, retention behavior, and interval semantics. It does not explain ordering or default limit, but those are not critical for correct invocation and some are implied by the schema.

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 71%, and the schema already explains most parameters. The description adds meaningful context for interval=auto and clarifies that after is tier-limited, which helps an agent choose valid values. It does not add much about limit or cursor, but the existing schema descriptions cover those reasonably.

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 states a specific verb and resource: historical water level readings for one gauge. The parenthetical contrast with current readings on /gauges and /gauges/{id} clearly distinguishes this from sibling listing/detail tools. An agent can identify the tool's core function immediately.

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 gives explicit tier-based guidance, including that free tier is blocked and points to the free current-reading endpoints as alternatives. It does not explicitly name sibling MCP tools or state 'use this when you need readings older than 6 hours,' but the context is clear enough for selection.

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 adds substantial behavioral detail beyond the readOnlyHint annotation: readingStatus stale horizons by source, local datum units, AHD caveat, and the fact that rainfall gauges carry no flood classification. This gives the agent a clear model of what the tool actually reports and how to interpret its data.

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 dense but every sentence earns its place: main return payload, units/datum, stale-data semantics, rainfall mode, and status-not-prediction caveat. It is front-loaded with the core purpose and structured logically for agent consumption.

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 the tool's complexity (8 parameters, no output schema), the description covers primary return content, classification logic, unit semantics, stale-data thresholds, mode switching, and a clear scope boundary. The remaining parameter semantics are fully covered by the schema, so nothing essential 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 baseline is 3. The description adds value beyond the schema by explaining that water-level readings are in metres relative to local datum, that rainfall values are incremental millimetres with no flood class, and that variable defaults to water_level. This meaningfully clarifies parameter behavior beyond raw 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?

The description states a specific verb ('Returns') and resource ('river gauge stations') with a clear scope: latest water level, BoM flood thresholds, and a derived floodClass. It also differentiates itself from siblings by covering list-level station data with live flood status, not a single gauge or readings time series.

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?

Clear context is given about defaults (water-level gauges) and the variable=rainfall alternative, plus a negative boundary ('Status reporting, not flood prediction'). However, it does not explicitly route the agent away from sibling tools like get_gauge or list_gauge_readings for single-station or time-series 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?

The readOnlyHint annotation already communicates the non-mutating nature. The description adds genuinely useful behavioral context about blocked free tier, tier-specific lookback limits, and the archive's scope, but it does not disclose error behavior on blocked access, pagination details, or response ordering. 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?

The description is two concise sentences with the primary action and scope front-loaded. Every sentence adds relevant information: the first defines what the tool returns, the second defines access constraints. There is no filler or 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?

For a tool with no required parameters, 100% schema coverage, and a readOnly annotation, the description provides sufficient access and scope context to invoke it correctly. Minor gaps remain: the response shape is not described, pagination behavior is not mentioned, and the relationship to list_incidents is left implicit, so it is not maximally 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?

The schema already documents all five parameters at 100% coverage, so the baseline is 3. The description adds meaning beyond the schema by quantifying what 'Tier-limited' on the after parameter means: Starter gets 1 year, Developer/Business get 5 years, and Pro/Enterprise get unlimited access, plus free tier is blocked.

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 uses a specific verb and resource ('Returns historical emergency incidents from the 4.8M+ record archive (1840-2026)') and clearly identifies this as a read-oriented historical lookup tool. It does not explicitly call out the difference from siblings like list_incidents or list_events, so it misses a point for sibling differentiation.

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 context about when the tool can be used by describing paid-tier access and lookback limits, which is useful for eligibility decisions. However, it does not state when to prefer this over sibling tools such as list_incidents or nearby_incidents, nor does it provide exclusions or 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 provide readOnlyHint=true, and the description adds meaningful behavior: it returns a GeoJSON FeatureCollection, includes pagination, and shows a detailed example response. It does not contradict the read-only annotation, and while it leaves out auth/rate-limit caveats, the added context is solid.

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 defining sentence is front-loaded and precise, and the long example response is justified because there is no output schema. The only weakness is that the example is shown truncated, which slightly weakens structural completeness, but the summary alone already carries the essential 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?

For a tool with 15 parameters and no output schema, the description plus 100% parameter descriptions is quite complete. The response example compensates for the missing output schema and the readOnly annotation covers safety behavior. The main gap is the absence of explicit guidance on when to prefer 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%, so the schema already documents all 15 parameters. The tool description adds a high-level grouping of capabilities and an example response, but it does not add parameter-level semantics beyond what the schema provides, so the 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-resource pair: Returns a GeoJSON FeatureCollection of all current emergency incidents. The word current clearly separates it from historical and single-incident tools, and the statement of filtering, pagination, and bbox support establishes the tool's purpose precisely.

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 phrase all current emergency incidents implies the primary use case, and filtering/pagination/bbox suggest general query scenarios. However, the description never names alternatives such as get_incident, list_historical_incidents, or nearby_incidents, nor does it state when not to use this tool, so routeing to siblings 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?

The readOnlyHint annotation already covers the safety profile. The description adds useful context by specifying the returned status fields, but it does not discuss behavior such as data freshness, error conditions, or how to interpret 'health' values.

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?

A single sentence front-loads the action and resource, and every clause adds a specific output field. There is no redundant or filler content.

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 zero-parameter, read-only operation, the description names the action, resource, and output fields, so nothing is missing to invoke the tool. It is slightly light on output semantics, such as what 'health' values look like, but this is a minor 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?

The input schema has zero parameters with 100% coverage, so there is no parameter ambiguity. The description correctly implies an unfiltered aggregate listing across all state feeds.

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 ('Returns'), a specific resource ('each state feed'), and enumerates the returned fields: last poll time, health, and incident count. This clearly distinguishes it from sibling tools like list_incidents or list_gauges, which target different resources.

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?

No guidance is provided about when to use this tool versus alternatives, and no sibling tools are named. The use case is implied by the title and description, but there is no explicit selection criteria or exclusionary context.

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 readOnlyHint annotation already establishes that this is a safe read operation, and the description adds the radius-filter and distance-sort behavior. However, it does not disclose edge-case behavior such as result limits, default filtering, or how ties in distance are handled, though nothing it states contradicts 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?

A single front-loaded sentence with zero filler, putting the spatial scope first and the sort detail second. It is efficiently written, but it is lean to the point of under-specification given the tool's 14-parameter surface, so it does not earn 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?

With 14 parameters, no output schema, and no enums, the one-sentence description is insufficient. It never mentions the extensive filter capabilities, the default behaviors (e.g., status defaults to all, include_retracted defaults to false), or what the response structure looks like, leaving the agent to discover these from the sparse schema.

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 only 36%, so the description carries a heavy burden that it does not meet. It only clarifies lat/lng/radius (and even repeats the 'km' detail that the radius schema already provides), while the 11 remaining parameters — state, status, urgency, severity, certainty, eventType, warningLevel, eventCategory, limit, and include_retracted — go unexplained in both the schema and the description.

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 names a specific verb ('Returns'), a resource (incidents), a unique spatial scope (within a radius of a lat/lng coordinate), and the sort order (by distance). This clearly identifies the tool's function, but it does not explicitly differentiate it from overlapping siblings such as list_incidents or the point-based declaration 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?

The title 'Find incidents near a location' and the description's spatial framing imply when to use this tool, but there is no explicit guidance on when to choose it over list_incidents, nor any exclusions or alternative tool names. The agent must infer that this is the location-scoped variant.

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