eYKON Intelligence

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds useful behavioral context by stating it returns nodes/edges bounded by hop count, but it does not disclose result format, size limits, or error 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 short sentences with no filler. The action, input, and output are front-loaded, and every phrase contributes meaning.

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 read-only graph traversal tool, the description covers the main elements: starting point (seed entity), operation (walk graph), and result (nodes and edges within N hops). Additional details like exact return structure would help, but the description is sufficient for basic 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?

The schema documents hops values and default, so that parameter is covered. The description adds meaning to entity_id by calling it a 'seed entity', but this is modest and does not fully compensate for the lack of entity_id documentation 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?

The description uses a specific verb ('Walk') and resource ('fleet kinship graph'), and states what it returns ('nodes and edges within N hops'). This makes the tool's function clear, though it does not explicitly distinguish it from sibling query 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?

Usage context is implied: use this tool when you need to traverse the fleet kinship graph from a seed entity. However, no explicit when-to-use or when-not-to-use guidance is provided, and no alternative tools are mentioned.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that reports are 'recent' and 'structured' with severity, narrative, and entity references, which is useful but does not disclose details like default time window behavior, pagination, or how severity filtering interacts with the 'minimum' semantics beyond 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?

The description is a single sentence that front-loads the main action and resource, then adds a brief note on return contents. It is concise and structured well, though it could be slightly more informative about usage context.

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 read-only query tool with no output schema and three optional parameters, the description is adequate but not complete. It does not explain the default look-back behavior, how severity 'minimum' works, or how this tool relates to the many sibling query tools. An agent could call it correctly but might not know when to prefer it.

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 three parameters. The description adds context that reports include severity and entity references, which aligns with the severity parameter, but it does not add meaning beyond the schema for hours or domain. 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 states a specific verb ('Retrieve') and resource ('intelligence reports generated by eYKON Sub-Agents'), and mentions the report contents (severity, narrative, entity references). It is clear what the tool does, though it does not explicitly differentiate from sibling query tools beyond the 'reports' resource.

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 for retrieving recent intelligence reports, and the parameters (hours, domain, severity) suggest filtering use cases. However, it does not explicitly state when to use this tool versus sibling query tools like query_entities or query_conflicts, nor does it provide exclusions or alternative 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 establish readOnlyHint=true and destructiveHint=false, and the description does not contradict them. However, the description adds no behavioral context beyond that—no mention of data freshness, whether results are live or historical, pagination, or potential rate limits. For a read-only query tool, the annotations cover safety profilers adequately, but the description adds minimal extra behavioral nuance.

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, well-structured sentence with no filler. The verb and core constraint are front-loaded, making it immediately clear what the tool does.

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 6 parameters, 0% schema coverage, and no output schema, the description is too terse. It does not state what the response will contain, how the parameters are interpreted (e.g., coordinate system, boundaries inclusive), or any format for altitude values. An agent would have to infer the bounding box semantics from parameter names alone, which is insufficient for reliable invocation, especially among many similar query_* siblings.

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 0%, the description must compensate for undocumented parameters. It does not—it only mentions 'geographic area' but never explains that lat_min/lat_max/lon_min/lon_max form a bounding box, nor does it mention the optional altitude_min/altitude_max filters. Parameter names are somewhat self-explanatory to a domain-aware agent, but the description adds no explicit meaning beyond what the names suggest.

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 action (Query), a concrete resource (ADS-B aircraft positions), and a clear scope (within a geographic area). This makes it readily distinguishable from siblings like query_airports or query_ports, which target different resources, without needing to inspect 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?

The description implies usage: use this tool when you need aircraft positions inside a geographic area. However, it does not explicitly mention when not to use it, nor does it name alternative tools that might be more appropriate for related queries (e.g., query_entities for a broader entity search). The context is clear but no exclusions or alternatives 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 signal read-only, idempotent, non-destructive behavior. The description adds important behavioral details: the default commercial-airport filter, the optional expansion to include minor airports, and the dataset provenance. No pagination or rate-limit notes, but these are secondary for a read-only query 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?

Three focused sentences deliver the dataset, default vs. expanded behavior, return fields, and usage examples without repetition or filler. The most decision-relevant information is 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?

The description explains output fields and gives realistic use cases, but it omits the required bounding-box parameters, which are essential for constructing a valid query. With no output schema and 43% parameter schema coverage, this is a meaningful gap, though the examples and default behavior keep it partially 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 coverage is only 43%, and the description does not compensate for the undocumented parameters. It clarifies include_minor and iso_country indirectly, but the required latitude/longitude bounding-box parameters (lat_min, lat_max, lon_min, lon_max) are never explained, leaving the most critical inputs ambiguous.

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 dataset ('Query airports from OurAirports') and clarifies the default scope plus output fields. It clearly distinguishes this tool from other query_* siblings by dataset and examples.

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 usage context with concrete examples ('airports near conflict zones', 'airports in Ukraine') and explains the default vs. include_minor=False behavior. It does not explicitly contrast with alternative sibling tools, but the context is strong.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: unscored rows are excluded (never counted as zero), there is deliberately no combined figure, and skill is measured against the track's own base rate inside the window. This goes beyond the annotations and helps the agent interpret results correctly.

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 moderately sized but information-dense. It front-loads the core purpose and then provides essential behavioral details. Every sentence earns its place, though the window_days explanation is somewhat long and could be tightened. Still, it is well-structured and not bloated.

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 tool's moderate complexity (3 optional params, no output schema), the description covers the key aspects: what is returned, how tracks are separated, how scoring works, and how to interpret the window. The only minor gap is that it doesn't explicitly describe the reply structure beyond pct_scored_last_7d, but the description is otherwise complete enough for an agent 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 description coverage is 100%, so the schema already documents all three parameters. The description adds meaning by explaining the track semantics (house, machine, creator) and the window_days nuance (90d is the shortest window with house evidence, and the yardstick is computed inside the window). This adds value beyond the schema's enum and type definitions.

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 ('query') and resource ('eYKON's own forecast record'), and clearly distinguishes this tool from siblings by naming the three tracks (house, machine, creator) and the metrics (Brier and log-loss per track). It also explicitly notes that tracks never blend, which differentiates it from other query 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 description provides explicit guidance on when to use this tool: it is for eYKON's own forecast record, and it explains the track semantics. It also gives practical usage advice, such as checking pct_scored_last_7d to determine if the window bound, and notes that 90 days is the shortest window with house-track evidence. This is strong contextual 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?

Annotations already establish read-only, open-world, idempotent, and non-destructive behavior, so the bar is lower. The description adds data provenance (GDELT-backed with ACLED fallback when licensed), which is useful context, but it does not disclose request behavior such as response shape, pagination, or data-availability conditions.

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 the operation front-loaded and no filler; the parenthetical data-source note is compact and adds value. The slight mismatch between the stated dimensions and the actual schema is the main cost.

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 seven-parameter query tool with no output schema, the description is incomplete: it omits parameter descriptions, return format, expected result semantics, and example values. Annotations cover safety but not how to construct a valid query or interpret the response.

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 0% and all seven parameters are undocumented, so the description must compensate; it provides only broad categories that roughly map to country/bbox, days, and event_type. The mention of 'actor' has no corresponding parameter, and lat/lon boundary semantics are not explained.

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 ('Query') and a concrete resource ('armed-conflict events'), and the data-source parenthetical helps distinguish it from other conflict-adjacent tools like query_dark_contact_events. However, the listed query dimensions ('region / date / event type / actor') do not all map cleanly to the schema, which slightly undercuts clarity.

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?

There is no guidance about when to use this tool versus siblings such as query_dark_contact_events or query_agent_reports, and no exclusions or conditions are provided. The only selection signal is the resource name, so an agent must infer when this tool is appropriate.

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, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful context about the output composition (synthesis and contributing anomaly IDs) and the semantic nature of convergence events, but it does not disclose ordering, pagination, or any look-back limits beyond the schema's default.

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 one concise sentence with no filler. The core resource and key output attributes are front-loaded, making it easy for an agent to scan.

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 query with one optional parameter and no output schema, the description adequately explains the domain concept and return payload. It omits explicit return-type/list semantics and potential caveats, but the annotations and schema cover the most important operational details.

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 'hours' parameter, which already documents type and default. The description only loosely ties 'recent' to the time window and adds no additional format, range, or edge-case detail, so it does not need to compensate.

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 identifies a distinct resource ('convergence_events') and explains it as 'anomaly-of-anomalies', which helps differentiate it from sibling query tools. It also states what the result includes: synthesis and contributing anomaly IDs. It lacks an explicit verb such as 'list' or 'returns', but the tool name and 'Recent...' phrasing make the operation 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?

There is no guidance on when to use this tool versus alternatives like query_thermal_anomalies, query_precursor_matches, or query_regime_shifts. The unique resource name is the only implicit signal, and no exclusions or alternative routing are provided.

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 readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context: the event lifecycle, the three resolution outcomes, the epistemic caveat about still_dark (never saying 'confirmed dark'), and the response's coverage and tally contents. This goes well beyond the structured 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 front-loaded with the core distinction (events, not a leads snapshot), and every clause adds necessary domain semantics, wording constraints, or usage guidance. It is dense but not bloated, and 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 the domain complexity and the absence of an output schema, the description is unusually complete: it defines open/resolved/void, explains the meaning of still_dark, names the sibling tool for the alternative use case, and summarizes what the response contains. Nothing essential for selecting or invoking this tool 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 schema covers both parameters at 100%, so the baseline is 3. The description enriches 'status' by explaining what resolved means (reappeared/still_dark) and what void means, but it leaves a small ambiguity around 'resolved' as a status filter versus 'void' also being a resolution outcome in the lifecycle.

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 exact resource (dark-contact events from the Shadow Fleet board), contrasts it with a leads snapshot, and later explicitly distinguishes it from query_shadow_fleet_leads. The purpose is clear and the tool is readily differentiated from 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?

It explicitly states when to use this tool ('what went dark / what came back' questions) and names the alternative for the current ranked list (query_shadow_fleet_leads). This gives an agent direct routing guidance without requiring 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds minimal behavioral context beyond the word 'search' and the source ('entities registry'). Since it does not contradict the annotations and the bar is lowered by their presence, a baseline 3 is appropriate.

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 that names the verb and resource immediately and appends a useful scope list in parentheses. No wasted words. It earns its place, though it is sparse — a concise but not fully informative definition.

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 search tool with required q, a filter (entity_type), a limit, no enums, and no output schema, the agent is left guessing at the query format, supported type values, and result shape. With 3 parameters and zero schema documentation plus almost no description coverage, the definition is incomplete for reliable 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?

Schema coverage is 0%, so the description must compensate for documenting q, limit, and entity_type, but it does not. The parenthetical list of entity classes indirectly hints at valid entity_type values, which is some value, but q's search format/semantics and limit's behavior are entirely unexplained. With a required q parameter and no schema text, this is a notable gap.

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 ('search') and a specific resource (the entities registry) and lists the covered classes: vessels, operators, owners, flags, ports, refineries, mines. This is clear and concrete. However, it does not distinguish itself from the overlapping specialized siblings query_vessels, query_ports, query_mines, and query_refineries, which weakens the 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?

No guidance on when to use query_entities versus the specialized query_vessels/query_ports/query_mines/query_refineries tools. Since the covered type list overlaps directly with those siblings, an agent cannot determine whether to prefer this general registry search or a domain-specific query. There are no exclusions or selection criteria.

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 readOnlyHint, idempotentHint, and openWorldHint, so the bar for additional context is met by the description's behavioral details: the dataset is frozen at 2011, the default filter excludes prospects/occurrences, and commodity matching is case-sensitive against the commodities[] array. These are exactly the kinds of non-obvious traits an agent needs to know.

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 dense sentences deliver dataset provenance, row contents, filter behavior, usage examples, and parameter semantics without redundancy. The most important information (purpose and scope) is front-loaded, and every clause 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?

The description is largely complete for a read-only query tool: it enumerates the row fields returned, explains the default filter and include_minor behavior, and clarifies commodity matching. It omits pagination details and any discussion of the bounding-box parameters, but given the schema annotations and the simplicity of spatial bounds, 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?

With schema coverage at 56%, the description compensates notably: it explains commodity case-sensitivity, include_minor's effect on the default filter, and the presence of commodity fields (commod1/2/3) not fully detailed in the schema. The lat/lon bounds are left to inference, but they are standard spatial parameters and the required coordinate set is already 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?

The description opens with 'Query mineral deposits from the USGS Mineral Resources Data System', naming a specific verb and resource, and adds substantive context: public-domain government dataset, ~304k records, 2011 archival snapshot. The usage examples ('lithium mines in Chile', 'rare-earth deposits worldwide') further pin down the tool's scope, making it clearly distinct from sibling query_* 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 description gives explicit usage scenarios ('Use for questions like...') and explains the default significant-sites filter and how to override it with include_minor. It does not, however, name alternative tools or state when not to use it, so it stops short of full when/when-not 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds substantial behavioral context beyond annotations: radiance is not power state, cloudy readings average ~100x brighter, absence of a row means absence of a look rather than darkness, counts are per physical site not registry row, and NASA latency means responses describe a week 1-2 weeks in the past. These are critical interpretation rules an agent could not 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?

The description is long but deliberately structured: it opens with the core definition, then mode-specific usage, then CRITICAL INTERPRETATION RULES in capitalized sections, then latency and sensor-independence notes. Every sentence carries necessary caveats or guidance; the length is justified by the complexity of interpreting night-lights. It is slightly dense, which prevents a 5, but it is far from bloated.

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 output schema and high interpretative complexity, the description is remarkably complete. It specifies what the response contains (site-level events or radiance rollup, plus a coverage block with newest_night and lag_days), explains event semantics, provides critical false-positive causes, and tells the agent how to frame answers relative to latency. Nothing essential for correct invocation and interpretation 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 baseline is 3. The description adds value beyond the schema by explaining the meaning of mode values ('site-level significance events' vs 'per-facility nightly radiance rollup'), defining the event types, and clarifying that days ends at the newest data night rather than today. It reinforces the country attribution caveat and adds the physical-site counting rule, which enriches parameter understanding without repeating 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?

The description opens with a precise definition: query NASA Black Marble night-lights (VIIRS VNP46A2, ~500 m), listing the data product, resolution, and what is sampled. It clearly distinguishes two modes ('events' vs 'radiance') and names the specific event types (went_dark_lights, surge, first_light). It also separates this tool from FIRMS/thermal sensing by stating they are independent sensors, which differentiates it from the sibling query_thermal_anomalies.

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 when-to-use guidance with concrete example queries ('which power stations went dark last week', 'unusual lighting activity in Kuwait', 'how bright is Bandar Abbas at night'). It also provides a clear when-not-to-use: a dark pixel is not a confirmed outage and went_dark_lights is an inference, never a verdict. It explicitly instructs the agent to corroborate with FIRMS/thermal data before characterizing an outage, effectively naming the alternative sensor/tool.

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 behavior beyond the annotations: the response is a mixed list with infra_subtype, pipeline rows carry different fields than LNG rows, the default is operating-only, and include_minor bypasses that default. This gives the agent a reliable model of what the tool returns without an output 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?

The description is dense but well-organized: it leads with the combined resource scope, then explains the mixed output, per-type fields, example use cases, and parameter switches. Each sentence adds value, though the list of example questions could be trimmed without much loss.

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 tool's complexity (9 parameters, no output schema, mixed return types), the description covers the essential disambiguation logic, default behavior, and representative use cases. It does not mention pagination behavior or the meaning of the coordinate bounds, but the parameter schema already covers limit and the coordinate names are reasonably clear.

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 only 56%, but the description compensates for key parameters by explaining fuel values, the operating-only default, and include_minor's effect. It also clarifies the meaning of returned rows and fields. The four coordinate parameters remain undocumented, though their names are self-explanatory for a bounding-box query.

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 a specific verb ('Query'), the exact resources covered (gas pipelines, oil/NGL pipelines, LNG terminals), and notes that a single call returns all three with an infra_subtype field to disambiguate. This clearly distinguishes it from other query_* siblings, which each target different infrastructure or event types.

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 concrete example questions ('Russian gas pipelines into Europe', 'LNG export terminals in Qatar') and explains how to slice results with fuel, facility_type, and include_minor. It does not explicitly state when not to use this tool versus alternatives, but it provides clear usage context and parameter-driven 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds useful dataset context (NGA World Port Index, ~3,800 ports) and the fact that harbor_size slices to a single tier, but does not disclose additional behaviors such as pagination, coordinate handling, or output ordering. With annotations present, a 3 is appropriate.

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 no filler: the first states the action and dataset, the second lists output fields, and the third gives usage examples and the filter hint. The most important information is front-loaded, and 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?

The description is largely complete for a read-only query tool: it names the source, data fields, filter, and typical usage questions. The main missing piece is explicit guidance on how to express the coordinate bounds, which is necessary to call the tool correctly. Otherwise, annotations handle safety and schema handles limits.

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 only documents limit and harbor_size, so coverage is 33%. The description adds sematic value by listing the exact harbor_size values and explaining its filtering purpose. However, the required lat/lon parameters are only implied via examples; their bounding-box meaning and units are not explicitly described, leaving a gap for the low-coverage 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: 'Query commercial seaports from the NGA World Port Index.' It states the dataset (~3,800 ports) and the row contents, and the example questions make the function unmistakable. This clearly distinguishes it from sibling tools like query_airports or query_vessels.

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 explicit 'Use for questions like...' examples, giving an agent concrete cues for when to invoke this tool. It does not state exclusions or alternatives, but the usage context is clear enough that an agent can select it over related query tools.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context about recency, theatre grouping, and the composite/sub-score structure, but it does not disclose default limit behavior or pagination.

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?

One tightly written sentence that is front-loaded with the core domain and scoping ('posture_scores rows per theatre') and contains no filler. Every phrase contributes meaningful 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 read-only query with strong annotations, the core purpose and output composition are adequately covered, and the theatre enum is available in the schema. However, with no output schema and no parameter descriptions, the missing limit semantics and default behavior leave an agent uncertain about row counts and optional filtering.

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 0% and no property descriptions exist, so the free-text description must compensate. It only hints at theatre_slug through 'per theatre' and never explains the limit parameter or how it interacts with theatre_slug. The enum values are in the schema, but the meaning of the optional limit is left ambiguous.

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 concrete resource ('posture_scores rows') and a specific return shape ('composite + 5-domain sub-scores'), so an agent knows exactly what this tool fetches. It does not explicitly distinguish itself from sibling query_* tools, but the posture_scores domain is unique enough to avoid confusion.

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 'Most recent ... per theatre' implies the tool is for retrieving the latest posture scores, which gives some usage context. However, it does not explicitly say when to use this tool versus alternative query tools or what conditions would make a sibling more appropriate.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the default operating-only filter, the capacity floor, and the effect of include_minor=true. It does not mention pagination or rate limits, but the annotations carry the main burden.

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: it opens with the resource, then data fields, then example questions, then parameter guidance. Every sentence earns its place with no repetition of schema details.

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 read-only query tool with no output schema, the description covers the dataset, fields, example questions, and key parameter behaviors. It does not explain the return format or pagination, but the annotations and schema cover the safety and parameter basics, and the example questions make the tool's purpose fully clear.

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 56%, so the schema documents fuel, limit, status, include_minor, and min_capacity_mw. The description adds meaning by explaining the default operating-only filter and capacity floor, and by giving example usage for fuel. It does not fully compensate for the undocumented lat/lon parameters, but those are self-explanatory bounding-box coordinates.

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 ('Query'), a precise resource ('unit-level power plants from the Global Energy Monitor — Global Integrated Power Tracker (GIPT)'), and enumerates the data fields and example questions. It clearly distinguishes this tool from sibling query tools by naming the exact dataset and scope.

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 concrete example questions and explains when to use include_minor=true and fuel. It does not explicitly name sibling alternatives or state when not to use this tool, but the context is clear enough for an agent to select it for power-plant queries.

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, destructiveHint=false, so the description does not need to repeat that. The description adds the behavioral trait of 'by cosine similarity', which is useful. However, it doesn't disclose potential limitations, such as behavior on unknown theatre_slug or edge cases, and with openWorldHint=true the description doesn't add much beyond the 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 one concise sentence, front-loading the core purpose and method. It avoids unnecessary detail, making it efficient for an agent to parse. Slightly more context could be added, but for the length, it is well-structured.

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 tool's complexity is low (3 params, no output schema), the description is nearly sufficient. However, it lacks explanation of what 'precursor_library' is and how event_type affects results, leaving some ambiguity for an agent deciding to invoke it. The output format is not described, but since there is no output schema, this could be 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 description coverage is 67%: theatre_slug is well-described with an enum, top_k has a brief description, but event_type has no description in the schema. The tool description says 'by cosine similarity' which adds meaning to the function but does not clarify event_type's role. Since coverage is moderate, the description partially compensates but not fully.

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 the tool's purpose clearly: 'Nearest precursor_library entries for the given theatre, by cosine similarity.' It specifies the verb 'query' implicitly through the name, the resource 'precursor_library entries', and the criterion 'cosine similarity'. However, it does not differentiate from siblings like query_posture_scores, which might also be related to theatres, and the term 'precursor_library' is not explained.

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?

There is no explicit guidance on when to use this tool versus alternatives. The description implies it is for finding similar precursor entries, but does not state when to prefer it over, say, query_posture_scores or query_calibration. No mention of exclusions or conditions under which another tool would be more appropriate.

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 supply readOnly, openWorld, idempotent, and destructive hints. The description adds useful behavioral context: data source (OSM), canonical tag limitation, approximate number of global facilities, and the optional capacity field. It does not contradict annotations and goes beyond a bare safety profile, though it omits details like return format or how the bounding box is applied.

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 packs essential facts in four short sentences, front-loading the verb and resource. The example questions are somewhat verbose but still relevant. It avoids fluff and each sentence carries useful 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?

Since there is no output schema, the description partially covers return values by listing facility fields ('each with name, operator...') and the canonical tag scope. It omits details about the response format or bounding-box behavior, which would round it out, but the core question of what data is returned is addressed.

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 only 33%; the four required lat/lon parameters have no schema descriptions. The description only paraphrases the already-documented 'country' parameter ('Pass country to slice') and offers no meaning for limit, lat_min, lat_max, lon_min, or lon_max. Given the low schema coverage, the description does not compensate for missing 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 states a specific verb and resource: 'Query oil refineries from OpenStreetMap' with a clear scope via canonical tags. Among sibling tools like query_pipelines and query_mines, this unambiguously targets refineries and its data source, so an agent can differentiate it 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?

The description explicitly gives usage examples ('Use for questions like...') covering geographic/refinery topics, which provides clear context for when to invoke this tool. It does not name alternative tools or give exclusion criteria, but the examples are specific enough to route an agent correctly in most cases.

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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the active-only scope and the return of p-values and effect sizes, but does not explain what 'active' means or how the 30d-vs-60d result should be interpreted. This is useful context but not rich behavioral detail.

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 fragment with no filler; the resource, detection method, and key result fields are packed into one line. Every phrase 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 read-only tool with one optional parameter and no output schema, the description partially covers return values via p-values and effect sizes, but not their structure or the meaning of the 30d-vs-60d test. The optional region filter is discoverable in the schema, so this is adequate but not 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 coverage is 100%: the only parameter, 'region', has the description 'Theatre slug or label'. The description adds no parameter-level meaning beyond the schema, so the baseline for high coverage 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 phrase 'Active regime shifts (30d-vs-60d test)' identifies a distinct resource and a specific detection method, which separates it from the many sibling query_* tools. It lacks an explicit verb, but the tool name supplies 'query', so the intended operation is 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 no when-to-use guidance, alternatives, or exclusions. With 24 sibling tools, an agent must infer that this is the right choice based on the resource name alone.

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, open-world, idempotent, and non-destructive behavior, so the bar is lower, but the description adds substantial behavioral detail: unscored vessels are not defaulted, silence_hours is measured against the data clock, commodity is ignored, and vessels in stale coverage boxes are voided and never ranked. This is far beyond what annotations alone 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 dense but every sentence earns its place: scoring criteria, non-defaulting behavior, silence_hours semantics, the commodity trap, and coverage-gating behavior are all critical for correct invocation and user communication. Nothing is 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?

With no output schema, the description carries the burden of describing both result semantics and special-case handling. It covers scoring, unscored vessels, silence_hours, the ignored commodity argument, coverage gating, and per-box coverage state, leaving little ambiguity for an agent deciding whether and how to call the 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?

The description fully explains the commodity parameter's key quirk: it is accepted but not applied. It also gives context for min_score by describing the composite scoring model. However, limit has no schema description and the tool description does not explain its effect or default, so not every parameter is fully compensated for.

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 that the tool returns ranked shadow-fleet vessel leads and specifies the scoring basis: silence relative to each vessel's own 14-day cadence baseline, vanished-under-way status, and flag of convenience. This makes it distinct from sibling tools like query_vessels, even though no sibling 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?

The description implies use when shadow-fleet lead rankings are needed, and it gives operational guidance about the commodity caveat and coverage gating. However, it does not explicitly state when to prefer this tool over alternatives such as query_vessels or query_dark_contact_events, so the selection logic is left mostly 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: the ~3h latency, the regional (non-global) ingest coverage, the shallow archive caveat, the meaning of a detection as a hot pixel rather than a confirmed fire, and the explicit warning that absence of detection does not mean absence of fire. It also discloses that every response carries a coverage block and instructs the agent to read it before characterizing zero 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?

The description is long but every sentence earns its place: it covers mode selection, interpretation rules, coverage caveats, and parameter semantics. The critical interpretation rules are clearly marked with 'CRITICAL INTERPRETATION RULES' and the coverage warning is front-loaded enough to be noticed. It could be slightly tighter, but the density of essential guidance justifies the length.

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 12-parameter tool with no output schema, the description is remarkably complete. It explains both modes, the return fields for facilities mode, the coverage block semantics, the interpretation pitfalls, and the regional limitation. The only minor gap is that it doesn't describe the exact return shape for raw mode, but the schema and the mode descriptions make this inferable, and the interpretation rules are more important for correct use.

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 baseline is 3. The description adds value by grouping parameters by mode (facilities vs raw), explaining the default behavior of min_detections (default 1, pass 0 to include quiet facilities), and clarifying that country names are full English not ISO codes. It also explains the meaning of FRP in context. However, it doesn't add much beyond the schema for lat/lon bounds or limit, which the schema already documents adequately.

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 ('Query') and a precise resource ('NASA FIRMS satellite thermal anomalies'), names the two data products (VIIRS 375m + MODIS 1km), and immediately distinguishes the two modes. It clearly differentiates itself from siblings like query_refineries and query_power_plants by focusing on thermal anomaly detections rather than static infrastructure.

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 when-to-use guidance for both modes: mode='facilities' for facility-centric questions with concrete example queries, and mode='raw' for geographic questions not anchored to a monitored facility. It also provides critical interpretation rules that tell the agent when NOT to attribute detections to strikes or fires, and how to handle zero results via the coverage block.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds the returned attributes and the time/area constraint but does not disclose behavioral nuances like AIS data coverage gaps, coordinate order requirements, maximum result limits, or units for speed/heading. It supplements the annotations modestly without contradicting 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?

Two sentences, front-loaded with verb and scope, followed by a compact return-field list. No redundant phrasing or reiteration of the tool name; every clause adds 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?

The description covers the core query semantics and output fields, which compensates for the lack of an output schema. However, it omits important context such as coordinate format, units (e.g., knots, degrees), bounding-box ordering expectations, and any limits on the look-back window. For a moderate-complexity query tool this is adequate but not comprehensive.

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 1 of 5 parameters (hours) has a schema description, leaving lat_min/lat_max/lon_min/lon_max as bare numbers. The description mentions 'geographic area and time window' but does not clarify bounding-box semantics, coordinate format, units, or that all four bounds are required. The hours default conveyed by the schema is not restated. Schema coverage is only 20%, so the description should carry more parameter meaning; it largely fails to.

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 ('Query'), names the exact resource ('AIS vessel positions'), and scopes it by geography and time window. It also enumerates the returned fields, making the purpose unambiguous. Among siblings like query_aircraft and query_ports, the resource and scope clearly set this tool apart.

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 no guidance on when to choose this tool versus related sibling tools (e.g., query_ports, query_aircraft), nor any conditions or exclusions. It only states the operational scope (bounding box and look-back window), which falls short of explicit usage direction.

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, openWorld, idempotent, non-destructive), so the description doesn't need to restate that. It adds the 'current' temporal scope and Open-Meteo as the data source, but does not disclose output variables, units, or any service-specific 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 a single front-loaded sentence with no filler. Every word contributes to the meaning, and the structure is appropriately sized for a simple two-parameter weather lookup.

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 query tool, the description is adequate but leaves some gaps: it does not describe return values (and there is no output schema), nor does it clarify coordinate parameter semantics. Annotations cover the safety context, so the main missing piece is expected response behavior.

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 provides 0% description coverage for parameters, and the description does not compensate by explaining latitude and longitude formats, coordinate order, units, or ranges. The property names are self-explanatory at a basic level, but the description adds no functional detail beyond 'specific location.'

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 identifies a specific action ('Query'), a resource ('current weather conditions'), and a location qualifier. 'Open-Meteo' adds source context, making the tool's purpose obvious even among many query_* sibling tools, though it does not explicitly contrast with them.

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 this tool should be used when current weather conditions for a location are needed, but gives no explicit guidance about when not to use it or which sibling tool might be a better fit. With numerous query_* siblings, the intended use is inferable but not 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: 'nothing is persisted on this path' and 'A MODEL, not an observation' – clarifying that results are computed projections, not real-world data. This goes beyond what annotations 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?

Three sentences with no fluff. The key facts are front-loaded: what it does, that it's a model, and that nothing is persisted. The 'A MODEL, not an observation' emphasis is a deliberate, useful clarification. Slightly more detail on parameters would be helpful, but the structure is efficient.

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 read-only, idempotent model run with no output schema, the description covers the essential behavioral contract. However, with 5 parameters and only 40% schema coverage, an agent may not know how to construct valid inputs (especially 'assumptions' and 'diversion_lag_hours'). The lack of output schema means return format is unknown, but the description's 'computed projection' gives some hint.

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 40%, and the description provides no parameter-level detail beyond what's in the schema. The description doesn't explain what 'assumptions' should contain, what 'diversion_lag_hours' means, or how 'closure_type' values map to scenarios. With 5 parameters and only 2 documented in the schema, the description should compensate but doesn't.

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's function: 'Run a chokepoint closure scenario' with a specific verb and resource. It also distinguishes itself from observations by noting it's 'A MODEL, not an observation.' However, it doesn't explicitly differentiate from the sibling 'run_sanctions_wargame' beyond the model name reference, so it's clear but not fully differentiated.

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 context by stating it's a model run and not persisted, but it doesn't explicitly state when to use this tool versus alternatives like run_sanctions_wargame or the query_* tools. The 'same model as the Chokepoint Simulator' reference provides some context but no explicit when/when-not 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds no behavioral context beyond the verb 'Run.' It does not disclose what the scenario produces, how it behaves, or any practical implications beyond what the annotations already state.

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 single sentence is concise and front-loaded with the verb. However, it is so sparse that it reads like a paraphrase of the tool name rather than a substantive explanation, leaving little value for an agent selecting among sibling tools.

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, only 25% schema description coverage, and four parameters, this description leaves nearly every operational detail unspecified: no return shape, no meaning for depth or preset, no relationship between inputs and outputs, and no usage context. An agent would need substantial external domain knowledge to invoke this 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 only 25% (only depth has a minimal '1 | 2 | 3' description), and the description names none of the four parameters. It provides only faint domain context that sanctioning_bodies and target_entities relate to sanctions, which is insufficient to define preset, depth, or list 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 uses a specific verb and resource: 'Run a sanctions propagation scenario,' which clearly names the action and topically distinguishes it from the query siblings and run_chokepoint_scenario. It stops short of 5 because it does not explain what the scenario computes or how it differs behaviorally from the chokepoint alternative.

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 such as run_chokepoint_scenario. There are no exclusions, prerequisites, or context signals that help an agent decide between the scenario tools.

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