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

The description goes far beyond the annotations by disclosing parallel upstream calls, expected 3-6 second response time, and the heuristic nature of earthquake_risk_level. It also thoroughly explains failure behavior: the tool never raises, failures surface as caveats, and data_status/upstream_error semantics are defined. This is exemplary behavioral disclosure.

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 detailed but every sentence earns its place: sources, latency, heuristic caveat, examples, and failure semantics are all relevant. It is well-structured with a clear lead sentence, examples in a block, and failure behavior at the end. No 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 the tool's complexity, the description covers input, expected latency, output status semantics, failure behavior, and the important caveat about official vs. heuristic risk. An output schema exists, so return-value details need not be in the description. The agent has everything needed to invoke and interpret 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 already fully documents the single location parameter as 'Municipality, city, or province name,' so schema coverage is 100%. The description adds only usage examples like 'Manila' and 'Batangas,' which reinforce but do not substantially extend the schema's meaning. 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 and resource: 'Multi-hazard risk assessment combining PHIVOLCS + PAGASA.' It clearly names the two data sources and hazard types, and the examples show concrete usage. This distinguishes it from single-source sibling tools like get_volcano_status or get_active_typhoons.

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 clearly implies when to use the tool: when a combined multi-hazard snapshot from PHIVOLCS and PAGASA is needed. It also gives a when-not by stating the earthquake risk level is 'never an official PHIVOLCS hazard assessment.' However, it does not explicitly name alternative sibling tools for single-hazard or official-data 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 description is exceptionally transparent about behavior: it details validation errors, 'indeterminate' status with never-cached responses, partial failures with caveats, and upstream errors with real error messages. This goes beyond the annotations (readOnlyHint, idempotentHint) and adds substantial context about system 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 longer than typical but well-structured: opening sentence, examples, and then a clear breakdown of failure modes. While it could be trimmed slightly, the density of useful information justifies the length, and it remains readable.

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 presence of an output schema and annotations, the description covers all necessary context: navigation pattern, error handling, caching behavior, and partial-failure semantics. It leaves no gaps for an agent to guess about how to invoke or interpret results.

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

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

The single parameter 'code' is fully documented in the schema (100% coverage) and further explained in the description with examples. The semantics of '0', region codes, and 7-digit codes are explicit, leaving no ambiguity about what values to pass.

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 purpose: walking the election results tree from regions down to precincts. It uses specific verbs like 'Walk' and 'go one level deeper', and distinguishes it from other data-browsing tools by focusing on the hierarchical COMELEC 2025 results structure.

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

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

Provides explicit usage instructions: start with code '0' for regions, use returned codes to drill down, and includes concrete examples for each level. It also explains what happens with invalid input and partial failures, giving clear guidance on when and how to use the 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 thoroughly explains failure modes (validation_error, upstream_error, data_status values) and clarifies that an empty list does not mean an empty folder. This goes well beyond the readOnlyHint/idempotentHint annotations, providing detailed behavioral expectations.

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 well-organized, uses bullet-like examples, and conveys all necessary information without unnecessary verbosity. It is concise yet comprehensive.

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 one-parameter tool, the description provides sufficient context about the tree structure, failure handling, and integration with sibling tools. The existence of an output schema covers return format, so no critical information 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?

Even though the input schema already fully describes the 'path' parameter, the description adds valuable examples ('1F', '1F/FY') and clarifies the navigation rule 'keep browsing until entries come back as datasets', which is absent from 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 clearly states that the tool lists one level of the PSA OpenSTAT catalog, providing examples and explaining its role in navigating the catalog tree. It also distinguishes itself by mentioning 'find a dataset without guessing a table id', making the purpose specific and actionable.

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 practical usage guidance, including examples and how to use the 'path' field to go deeper, and mentions sequencing with describe_psa_dataset. However, it does not explicitly contrast this tool with sibling search_psa_catalog, which could confuse an agent about when to browse versus search.

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 goes beyond annotations by detailing the internal behavior: it calls get_area_profile for each place, and on validation failure it never calls that tool. It also explains partial failure state (unresolved places get rows, data_status becomes indeterminate/unavailable, comparable false with caveat). This matches the readOnly and idempotent hints without contradiction.

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 well-structured and includes examples, but it is somewhat repetitive (e.g., the opening sentence and the aggregation explanation are similar). Still, it earns a high score because all content is relevant and directly aids usage.

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, the description is remarkably complete. It covers normal usage, aggregation, validation errors, partial failures, and the output fields that signal these states (validation_error, data_status, comparable, caveat). The presence of an output schema reduces the need for return-value detail, and the description fills the remaining gaps.

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 covers all three parameters, and the description enriches them further: it lists the exact metric names, the default for metrics, the format options, and the location count constraint. It also adds semantic meaning about validation rules that are not fully captured 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 clearly states the tool's purpose: comparing civic indicators across multiple Philippine places. It distinguishes itself from the get_area_profile sibling by noting it aggregates per-place calls into one row per place, preventing the agent from needing to call the profile tool repeatedly.

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

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

Provides explicit usage examples, clarifies the allowed parameter ranges (2-5 locations, 8-metric allowlist, json/csv formats), and explains the conditions under which to use this tool versus alternatives. The failure behavior is also described, giving clear guidance on error handling.

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. The description adds substantial behavioral detail: failure modes (data_status 'invalid_request' vs 'unavailable'), validation_error for non-.px paths, upstream_error with caveats, and the empty dimensions list on failure. It also mentions total_cells and max_cells_per_query, which are not in annotations. No contradictions.

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 gives usage guidance, a concrete example, and a structured failure-mode explanation. Every sentence adds value; the length is justified by the tool's role as a prerequisite and its multiple edge cases. The structure is logical and easy to parse.

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 that an output schema exists (not shown here but implied by the context signal), the description need not detail return values. It covers the essential calling context (what to do before querying, what the query tool needs), the example path, and all failure modes with their flags. An agent has everything needed to invoke it correctly and interpret outcomes.

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% (the only parameter dataset_path is fully described, including how to get it from browse_psa_catalog). The tool description provides an example but does not add meaning beyond the schema. Per the baseline for high schema coverage, a 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: 'Read the dimensions and valid value codes of one PSA OpenSTAT dataset.' It clearly distinguishes itself from sibling tools like query_psa_dataset (which it supports) and browse_psa_catalog (which provides the path). The example further clarifies the exact input format.

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

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

The description explicitly states when to use this tool: 'Call this before query_psa_dataset.' It explains why ('The query tool needs an explicit value code for every dimension, and those codes live here') and gives a concrete example. While it doesn't mention when not to use it (e.g., for listing datasets), the guidance is unambiguous for its primary role.

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 is unusually explicit about behavior: it never raises, defines data_status values for all failure combinations, explains upstream_error and caveats entries, and notes that partial results still return. It also clarifies that high_cost_no_published_progress is a transparency flag, not a true missing-progress finding, preventing misinterpretation.

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 well organized with separate rule and failure sections, but the 'Examples:' block and repeated explanations make it slightly longer than necessary. Still, every sentence carries useful information and the structure is scannable.

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 analysis tool, the description covers all key contextual aspects: rule logic, default thresholds, filtering options, failure states, partial results, and return semantics. Since an output schema is indicated, return fields need not be enumerated in prose.

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 fully describes region, province, and min_cost_php with defaults. The description adds meaningful rule context for min_cost_php and shows example values, though it adds little beyond schema for region/province filters.

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 immediately identifies the tool's purpose: flag PhilGEPS infrastructure projects for further review by cross-referencing PHIVOLCS earthquakes and PAGASA typhoons. It clearly names the three heuristic rules and explicitly frames outputs as indicators, not accusations, so an agent knows what the tool is for.

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 concrete invocation examples and explains when each rule fires, including the default threshold. It doesn't explicitly contrast with sibling tools like search_infra_projects or assess_area_risk, but the purpose and failure semantics are clear enough for appropriate use.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description details the data source (PAGASA bulletin), the parsing mechanism, the distinction between an empty list and failure/indeterminate states, and the exact shape of failure responses. This greatly enhances transparency for an agent.

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 succinct, using a single sentence for the core purpose plus a compact failure-mode block. It avoids redundancy and is well-structured, making it easy for an agent to parse quickly.

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 lacking an explicit output schema in the prompt, the description enumerates all return fields (local_name, international_name, category, etc.) and specifies the alternative failure dict. This gives the agent complete information to use the tool and interpret results.

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 input schema is an empty object with 100% coverage. There is nothing to describe; the description correctly does not add parameter details because none exist.

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 purpose: 'Get active tropical cyclones in/near the Philippine Area of Responsibility (PAR).' It uses a specific verb and resource, distinguishing it from weather-related siblings like get_weather_forecast or get_historical_typhoons_ph.

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

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

The description implies usage through its name and clear purpose (fetching current typhoon data), but it does not explicitly state when to use it versus alternatives or mention exclusion criteria. The failure and edge-case behavior is well explained, providing context, though not a formal when-to-use statement.

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 readOnly/idempotent annotations: measured_at is always UTC, coverage is limited to ~80 cities via a local coordinate table, and there are three explicit failure modes with distinct data_status values. This gives an agent a precise model of the tool's runtime 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 front-loaded with the core purpose and return payload, followed by concise examples and a clearly organized failure-mode section. The length is justified by the operational details, and every sentence serves a distinct 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 single-parameter, read-only tool with an output schema, the description is complete: it covers inputs, outputs, timezone behavior, coverage limits, and all documented error states. No critical information needed to invoke the tool correctly is missing.

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

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

The schema already describes the location parameter well with examples, and schema coverage is 100%. The description adds meaningful semantics by explaining the city-coverage limitation and the invalid_request behavior when a location is not in the coordinate table, going beyond the schema's basic type and 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 states a specific verb and resource: real-time air quality for a Philippine city via Open-Meteo. It enumerates the exact pollutants and AQI types returned, and the Philippine-city scope clearly separates it from sibling weather, earthquake, and health 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 clearly indicates when to use the tool: when a user needs real-time air quality for a Philippine city. It provides usage examples and a coverage caveat, but it does not explicitly name sibling tools or state when-not-to-use conditions, so it falls just short of full routing guidance.

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

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

Annotations already state readOnly and idempotent, and the description further details failure behavior: per-block status, caveats for failed siblings, and the specific condition for upstream_error. This provides additional behavioral context beyond 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?

The description is efficient and well-structured, including examples and failure handling without redundant words. Every sentence contributes valuable 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 input expectations, usage examples, and error behavior, which is sufficient for an agent to invoke the tool correctly. It does not enumerate the exact output structure but mentions the block layout, which is adequate for a composite tool of this nature.

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 fully describes the 'location' parameter with examples for municipalities, cities, provinces, and regions. The description does not add extra semantic detail beyond the schema, 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 clearly states the tool provides a one-call civic profile for a Philippine location, specifying the scope and giving concrete examples. It implicitly distinguishes itself from specialized siblings by emphasizing aggregation of multiple data types into a single result.

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 mentions consolidating eight data types in one call, suggesting use over multiple specialized tools, but does not provide explicit when-to-use guidance or alternatives. Examples show usage but no clear directive on when to prefer this tool over 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals important behavioral details: it makes no upstream calls, always returns a dict, and that source_health starts empty on a cold process. This transparency helps the agent understand runtime 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 well-structured with sections for purpose, example, failure behavior, and return fields. It is informative without being overly verbose, and the example clarifies that no arguments are needed.

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 fully covers what the tool returns, including edge cases (empty cache on cold start, note field), and explains when to use it. Given the zero-parameter complexity, it provides all necessary context for correct invocation and interpretation.

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 coverage is 100% (empty schema). The description adds no parameter-specific meaning because none exist. Per the rubric, with high schema coverage and no parameters, the baseline score 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 clearly states the tool's dual function as a server health/version probe and a data-source catalog, and explicitly explains its purpose: to judge whether a stale cached response is acceptable or a re-fetch is needed. This distinguishes it from sibling data-fetching 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 direct usage guidance: 'Use it to judge whether a stale cached response is fine or a re-fetch is needed.' It also notes the tool doubles as a version/health endpoint, giving clear context for when to invoke it over other 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?

Beyond the annotations (readOnly, idempotent, etc.), the description discloses substantial behavior: what data it parses (magnitude, depth, location, date/time, per-municipality intensity), and detailed failure handling (empty/malformed/non-PHIVOLCS/404 returns a dict without data_status or upstream_error; exceptions set data_status 'unavailable' and upstream_error true).

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 information-dense and well-structured, covering purpose, usage, example, and failure modes. It is slightly verbose with the example and failure specifics, but every sentence adds useful context, so it earns a strong score rather than a perfect one.

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 (one parameter, failure modes, external data source), the description is complete. It explains the input requirement, the parsing behavior, and all failure scenarios. Since an output schema exists, the description need not enumerate return fields, and it still covers edge cases thoroughly.

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 describes bulletin_url as 'Full URL returned by get_latest_earthquakes.bulletin_url.' The description adds meaning by reinforcing the source constraint, stating that hand-built or off-host URLs are refused, and giving an example URL shape. This goes beyond the schema's basic type/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 clearly states the tool's purpose: 'Get the full bulletin for a PHIVOLCS earthquake event.' It specifies the resource (PHIVOLCS bulletin) and distinguishes it from sibling tools like get_latest_earthquakes, which lists events rather than retrieving details for a single event.

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 guidance: pass a bulletin_url returned by a prior get_latest_earthquakes call, and explains that hand-built or off-host URLs are refused. This tells the agent exactly when and how to invoke the tool, and provides failure conditions.

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 goes far beyond the readOnlyHint/idempotentHint annotations by detailing exact failure modes: invalid 8-digit codes produce validation_error and 'invalid_request'; unrecognized codes produce a 403 with an AccessDenied marker; malformed payloads produce 'indeterminate'; and other outages produce 'unavailable' with the real error in caveats. This is exceptional behavioral disclosure.

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 provides an example and a well-organized failure taxonomy. Every sentence serves a distinct purpose: defining the resource, explaining the input source and output, giving an example, and enumerating error shapes.

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 single-parameter read tool with an output schema present, the description fully covers what the tool returns, how to get the parameter, and every known failure mode. Nothing an agent needs to call it correctly is missing.

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

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

The input schema already documents precinct_code with an example, and the description reinforces that with the '28010001' example and the source instruction 'from browse_election_results.' It also adds parameter-validation behavior (non-8-digit codes return validation_error with no request sent), which goes 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-resource pair: 'One precinct's official vote tally from the COMELEC 2025 archive.' It clearly distinguishes this tool from browse_election_results by stating the code comes from that browsing tool and that this returns all contests for a single precinct.

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 instructs the agent to obtain the 8-digit precinct code from browse_election_results, which is a concrete usage path. It does not, however, explicitly state when not to use this tool or name an alternative for browsing multiple precincts, though the single-precinct framing implies 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?

The description thoroughly discloses behavior beyond the annotations: it states the output is a model estimate rather than a gauge reading, and enumerates three distinct failure modes (invalid_request, unavailable, indeterminate) with exact conditions and returned fields. No contradiction with the readOnly/idempotent hints.

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 detailed but efficiently organized, with a clear opening statement, examples, and a structured failure mode list. Slightly longer than necessary but every sentence adds critical operational detail.

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

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

The presence of an output schema is noted, and the description provides a high-level summary of the response (daily series, max/min bounds, units). It does not repeat the schema verbatim but gives enough context for an agent to understand the result shape and error handling.

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

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

All three parameters are fully described in the input schema, and the description repeats their semantics (e.g., location is a city/municipality/province, past_days range 0-30, forecast_days range 1-30). The description also illustrates their usage in the examples.

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

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

The description clearly states it provides a daily river discharge forecast for a Philippine location from the GloFAS model, specifying the return series and units. It distinguishes itself from other weather and disaster tools by focusing on river discharge.

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

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

Provides explicit usage context with examples for both default and customized parameters, and explicitly advises treating the output as 'one signal among many' for flood risk. This guides an agent on when and how to invoke the 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 is fully transparent about behavior, including failure modes with data_status updates, caveats, and upstream_error flags. It adds context beyond the annotations by detailing specific error scenarios, and does not contradict any 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 concise yet comprehensive, using structured sections for examples and failure modes. It front-loads the core purpose and avoids extraneous detail, making it easy 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 tool with an output schema, the description adequately covers return behavior (headline set, indicators array, data_status, caveats, error flags) without needing to restate the schema. It is complete for an agent to understand what to expect and how to handle edge cases.

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 the optional indicator parameter with examples, and the description reinforces this by explaining the fuzzy-match behavior, the default null behavior, and that the list is browse-discovered rather than hardcoded. This goes well beyond the baseline coverage.

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

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

The description clearly states the tool's purpose: retrieving national health indicators from PSA OpenSTAT (subject 1D). It distinguishes itself from sibling tools by focusing specifically on health data, with explicit examples of default outputs and fuzzy matching behavior.

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 explains when to use the tool: with no argument for a default headline set, or with an indicator name for fuzzy matching. It does not explicitly contrast with alternative tools such as search_psa_catalog, but the specialization to health indicators makes the appropriate use case clear.

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

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

The annotations already declare readOnlyHint and idempotentHint, and the description adds transparency about failure modes (e.g., returning a dict with data_status and caveats on errors) and streaming behavior. This goes beyond the annotations by explaining what happens on failure, though it does not discuss performance or side effects beyond that. The additional detail is valuable but not exhaustive.

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 reasonably concise but contains some redundancy—for instance, 'Historical' appears in both the title and first sentence, and the filtering/aggregation details are restated. The structure (purpose, source, output, examples, failure) is logical and efficient, with no irrelevant information, but slightly more compression would improve clarity.

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 only two optional parameters and no output schema, the description provides a comprehensive picture: it states the data source, filtering logic, output fields, default behavior, examples, and error handling. This is sufficient for an agent to invoke the tool correctly without further reference. The inclusion of failure modes and examples makes it highly 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 input schema covers 100% of parameters with clear descriptions (year nullable with default, limit with default). The description reinforces these with examples showing defaults and clarifies the meaning of 'None' for year. While the schema alone already explains the parameters, the examples and context about 'most recent' add useful practical nuance, earning a slightly above-baseline score.

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 it returns historical tropical cyclone tracks within the Philippine Area of Responsibility, with details on source (NOAA IBTrACS), filtering, and output fields (peak intensity, minimum pressure, track period). It is readily distinguishable from sibling tools like get_active_typhoons, which focus on current storms, by the explicit 'Historical' label and the 'most recent storms' phrasing tied to the optional year parameter.

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 examples and explains parameter defaults, implicitly guiding when to use this tool (e.g., for historical typhoon data). However, it does not explicitly contrast with alternatives like get_active_typhoons or state 'use this for historical data, not for active storms.' The guidance is implicit rather than explicit, so it falls short of a clear when/when-not directive.

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 mark readOnly, idempotent, and not destructive, and the description adds explicit failure semantics: any error sets data_status to 'unavailable' and upstream_error true, while validation_error stays false even for an invalid area name. This goes beyond the annotations and fully discloses edge-case 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 somewhat verbose but includes necessary repetition of examples and failure modes in a structured manner. It stays focused and does not include irrelevant information, though it could be tightened without losing clarity.

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 simple one-parameter tool and the presence of an output schema (per context), the description adequately explains the return concept (year-on-year change) and failure behavior. It does not enumerate specific output fields, but the output schema and simple structure make this unnecessary.

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 fully describes the single 'area' parameter with default null and examples. The description repeats and clarifies that null returns the national figure, and the schema coverage is 100%, leaving no ambiguity.

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 the most recently published month's year-on-year inflation change from PSA, with national and regional options. It distinguishes from siblings like get_health_indicators and get_weather_forecast by explicitly naming inflation and the PSA source.

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

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

The description gives concrete examples and notes the publication lag, helping the agent decide when to call it. It does not explicitly compare to a sibling tool for inflation-related queries, but the purpose is evident from the title and examples.

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 annotations (readOnly, openWorld, idempotent). It explains the window concept, how missing or empty IDs are handled (return matched: false with caveat), and how upstream failures are reported (data_status 'unavailable', upstream_error true). This fully discloses expected behavior in edge cases.

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 concise yet comprehensive, structured with a clear main purpose, followed by context about the window and failure modes. It uses consistent formatting with examples, making it easy to parse. No redundant or extraneous information is present.

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 fully explains the tool's behavior in normal and edge cases, and its relationship to search_infra_projects. Since an output schema exists, it does not need to describe return values. The description is self-contained enough for an agent to invoke it correctly without additional context.

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 100% coverage with the description 'Reference number from search_infra_projects.' The tool description repeats the parameter name and includes examples, but does not add new semantic information beyond the schema. Given the high coverage, 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 clearly states the tool's purpose: 'Return the full record for one infrastructure project by project_id.' It specifies the resource (infrastructure project) and the action (return full record), distinguishing it from search_infra_projects which likely returns multiple results. The scope is unambiguous.

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

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

The description implies when to use it by referencing the 'same latest ~100-notice PhilGEPS window search_infra_projects reads,' suggesting it is the follow-up to a search. It also explains failure behavior, but it does not explicitly state when not to use it or mention alternative tools, though the sibling list provides context. Overall, usage is clear but not explicitly exhaustive.

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

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

Beyond the readOnly and idempotent annotations, the description discloses failure behavior in detail, including data_status 'unavailable', upstream_error true, caveats carrying the real error, and validation_error always false. This gives agents a clear picture of success and failure modes.

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

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

The description is well-structured, starting with purpose, then return content, then parameter behavior, examples, and failure semantics. It is concise without redundant padding and each section adds 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?

For a simple one-parameter read-only tool, the description covers purpose, return indicators, parameter semantics, example calls, and failure behavior. It is fully sufficient for an agent to decide when and how 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?

The sole parameter 'region' is fully described in both the schema and the description, with explicit clarification that it is accepted for API symmetry and does not filter results. The description adds meaningful behavioral detail beyond the schema.

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

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

The description clearly states the tool returns key labor-force indicators from the PSA Labor Force Survey, including participation, employment, unemployment, and underemployment rates. It also notes the national-only scope, distinguishing it from other area-level statistics 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 clear context for when to use the tool: when national labor-force indicators for the latest period are needed. It explicitly explains that passing a region does not filter results but only adds a caveat, giving clear usage expectations without referencing 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?

Adds concrete behavioral details beyond the readOnly/idempotent annotations: describes empty results with caveats, validation_error flags, and upstream_error handling. This enriches the annotation-only view.

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?

Well-structured: purpose first, then grouped examples, then failure behavior. Each sentence adds value; no fluff 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 an output schema present, not detailing return fields is acceptable. The description covers usage scenarios, parameter relationships, and error behavior, making it complete for the tool's complexity.

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

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

Input schema covers all 6 parameters (100%), and the description adds the grouping constraint (center_lat, center_lon, radius_km must be given together or not at all) and explains the distance_km output field, exceeding the schema alone.

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

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

States a specific verb and resource: 'Get the latest earthquake events from PHIVOLCS.' This clearly distinguishes it from siblings like get_usgs_earthquakes_ph and get_earthquake_bulletin.

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

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

Provides clear context with examples of default, filtered, and location-based calls, and describes failure modes. Does not explicitly contrast with similar earthquake tools, but the PHIVOLCS focus makes usage apparent.

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

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

Beyond the annotations (read-only, idempotent), the description explains validation before network calls, distinct failure modes for malformed codes, unknown well-formed codes, and mirror outages, plus which return fields distinguish them. This is substantial behavioral disclosure 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 longer than average but each part earns its place: purpose, behavioral model, examples, and failure modes. The main purpose is front-loaded, and the examples illustrate edge cases clearly. Minor redundancy exists between the examples and the later failure explanation.

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 a single required parameter, rich annotations, and an output schema, the description covers everything needed to invoke the tool correctly: valid input, rejected input, unknown input, and outage behavior. An agent can predict results across all relevant cases.

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?

Even though the schema covers the single psgc_code parameter 100%, the description adds meaningful semantics: well-formedness checks, examples with real codes, and how different code classes map to different return fields. An agent gains practical understanding beyond the raw type/format.

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

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

The first sentence states a specific verb and resource: 'Return the full chain region -> province -> city/municipality -> barangay for one PSGC code.' The output is precisely scoped, making it easy to distinguish this from location-adjacent siblings like resolve_ph_location or list_admin_units.

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 for a single PSGC code and produces a full hierarchical chain. It does not explicitly name alternative tools or exclusion conditions, but the usage context is strong enough that an agent can decide when this tool applies.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description thoroughly discloses runtime behavior: it details pagination URL patterns, all failure modes (invalid_request, unavailable, indeterminate, empty), and specific handling of items lacking title or link. This goes well beyond the basic 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 detailed yet well-organized, starting with purpose, then examples, then failure modes. While slightly long, every sentence adds value and there is minimal redundancy with the schema description. The structure is logical and front-loaded with the core 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?

The description covers all key operational aspects: pagination, error handling, data_status values, and item filtering. It does not detail the output schema fields, but that may be provided separately. For a feed-reading tool, the description is sufficiently complete to guide correct usage.

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 provides comprehensive description of the 'page' parameter (range, URL mapping, default). The tool description adds meaning by explaining the consequences of out-of-range pages (invalid_request) and behavior for pages above 1 with zero items (empty), enriching the semantic understanding 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?

Clearly states the tool reads the Official Gazette RSS feed of Philippine issuances. The verb 'Reads' and resource 'Official Gazette' are specific, and it is easily distinguished from sibling tools focused on earthquakes, weather, or procurement.

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 examples and explains pagination and failure modes, but it does not explicitly state when to use this tool over alternatives (e.g., no comparative guidance against other government data tools). The usage context is implied by the tool's unique purpose but not explicitly contrasted with 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?

The description is transparent about output behavior on success and failure, including population being None, caveats carrying error text, and failures never being cached. The readOnlyHint and idempotentHint annotations align with the described behavior, and no side effects are hidden.

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 well organized with a concise overview, a set of illustrative examples, and a separate failure-mode section. While detailed, the information is directly relevant and avoids unnecessary fluff.

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 provides enough context for an agent to know when to call this tool, how to choose parameters, what output fields to expect, and how to interpret error states. Combined with the fully described input schema, it is self-sufficient.

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?

All three optional parameters are described in the schema with clear semantics, including examples, default behavior, constraints such as not combining psgc_code with region, and validation_error outcomes for unknown values. The description complements the schema rather than duplicating it.

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 Philippine population statistics from the PSA Census, including defaulting to the latest census year and supporting national, regional, provincial, city, municipal, and barangay lookups. It also gives concrete examples that illustrate the intended use.

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 explains default behavior, available years, parameter combinations, and the prerequisite relationship to resolve_ph_location for PSGC codes. It also enumerates failure modes with corresponding data_status values, making expected behavior explicit.

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 goes well beyond the readOnly/idempotent annotations by detailing data_status values, upstream_error and validation_error conditions, handling of unpublished '..' cells, and subsistence-table failure behavior. This gives an agent a clear picture of success and failure modes.

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

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

The description is front-loaded with the core purpose, followed by examples and then failure semantics. It is somewhat lengthy but each section serves a distinct informative purpose, and the organization is logical.

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 existing output schema, the description covers source cadence, data lag, live discovery, examples, and an extensive set of error/status behaviors. It is sufficiently complete for an agent to invoke the tool correctly and interpret unusual results.

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 the optional region parameter and its None default. The description adds useful examples with 'Bicol' and 'NCR', and clarifies that an unlisted region leads to an invalid_request status, enriching the parameter semantics 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 clearly states that the tool returns poverty incidence from the PSA Full Year Poverty Statistics table, and the title and examples make the tool's purpose immediately understandable. It is distinct enough from siblings by referencing the specific PSA poverty dataset.

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 when PSA poverty incidence data is needed, and the examples show national and regional calls. However, it does not explicitly compare against sibling tools or state when not to use this tool, so guidance is mainly implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral context beyond annotations by explaining the 6-hour cache window, error response structure (data_status, upstream_error, validation_error), and dropped-count notes in caveats. This is useful, though it stops short of detailing internal side effects (which are none anyway).

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 repetitive: the same text about the ~100-notice window, rules_evaluated, rules_not_computable, and error handling appears nearly verbatim in multiple paragraphs. It is not concise and could be halved without losing information. The structure is okay, but the redundancy significantly harms the score.

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 lacking an explicit output schema listing, the description comprehensively enumerates key output fields (data_status, upstream_error, totals, by_mode, by_region, top_agencies, caveats, validation_error) and covers all error scenarios and validation rules. It also mentions the cache window and filter behavior, making it self-sufficient for an agent to invoke 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 already provides 100% description coverage for all three parameters (year, agency, region), including details like dropping undated records. The description repeats these examples but does not add any new semantic meaning beyond what the schema already states, so it does not improve upon the baseline.

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

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

The description clearly states the tool aggregates procurement statistics over the latest PhilGEPS notices and explicitly contrasts with search_procurement by referencing the same ~100-notice window. The verb 'aggregate' and resource 'procurement statistics' are specific, and the sibling differentiation is direct.

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 provides explicit guidance on when to use this tool versus search_procurement (same window, different purpose) and includes concrete examples. It also documents validation error behavior and failure conditions, leaving no ambiguity about the intended use case.

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 readOnly and idempotent hints in annotations, the description details data source, units, return variables, and comprehensive failure modes including specific data_status values for upstream errors, invalid dates, range violations, and malformed responses. This gives a full behavioral picture.

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 well-structured with purpose, return values, use cases, examples, and failure modes, but it is somewhat lengthy and repeats that daily solar irradiance and climate variables are returned. Overall it is appropriately detailed without being excessively verbose.

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 output schema exists and the description covers data source, units, typical use cases, examples, and detailed error behavior, the context is largely complete. It does not specify exact output fields, but the output schema and error descriptions fill that gap sufficiently.

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 covers parameter meanings with defaults, date span limits, and coordinate format, so the description adds limited new parameter-level semantics. It reinforces validation behavior regarding invalid dates and out-of-range coordinates, but does not define latitude/longitude ranges or add detail beyond the schema.

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

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

The description clearly states the tool returns daily solar irradiance and climate variables from NASA POWER for any coordinate, naming specific variables and units. It also identifies use cases like solar-site screening and farm planning, leaving no ambiguity about the tool's purpose.

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 concrete examples and notes general use cases, but does not explicitly guide when to choose this tool over closely related siblings like get_weather_forecast or get_flood_forecast. The examples and stated applications give enough practical direction for most agents.

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 openly discloses network dependency on the USGS API, validation failure modes, upstream failure modes, and caching behavior. It aligns with the readOnlyHint, idempotentHint, and destructiveHint annotations, and there is no contradiction between the described behavior and 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?

The description is longer than average but well structured and information-dense, with examples and failure cases. Very little is redundant; the only minor inefficiency is repeating the 'give all three together' rule in both the parameter section and the main description.

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 invocation, parameter constraints, expected output markers, and error states, which together provide sufficient context for correct use. It does not detail the full success output schema, but the output schema is indicated as available and the result fields are not necessary for invoking 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 schema already covers all parameters, and the description adds useful semantic detail: limit caps, default magnitudes, date format expectations, the center/radius grouping rule, and the resulting distance_km field. This goes well beyond the schema descriptions and fully clarifies how parameters interact.

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 the tool as retrieving Philippine-region earthquake data from USGS and explicitly contrasts it with PHIVOLCS-oriented offerings. It states the geographic scope, the source, and the distinctive value (international-standard magnitudes, global-network analysis), so an agent can distinguish it from sibling earthquake 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 concrete usage examples, default behaviors, and explicit constraints such as 'give all three of center_lat, center_lon, and radius_km together, or none of them.' It also enumerates failure scenarios and what the caller should expect in response, making invocation behavior predictable.

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 thoroughly explains edge cases: successful empty results over water, partial MODIS band failures, invalid-request handling, and date span limits. This goes well beyond the basic annotations and gives an agent a precise mental model of the tool's 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 detailed yet structured, with examples and explicit failure-mode statements that each add value. It is slightly verbose, but the richness of edge-case information 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?

Given the output schema and annotations, the description covers input validation, output behavior for successes and failures, and partial-failure handling. No significant gaps remain for an agent to safely invoke and interpret the tool's results.

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 covers all parameter descriptions, including units, date format, defaults, and the 366-day span limit. The description adds examples and failure explanations but introduces no new parameter-level semantics 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 clearly identifies the tool as retrieving NASA MODIS MOD13Q1 NDVI and EVI vegetation index values at a coordinate. It also distinguishes the tool by stating common use cases like farm monitoring, deforestation tracking, and drought checks.

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 examples and lists typical use cases, providing clear context for when the tool is appropriate. It does not explicitly contrast alternatives among the many sibling tools, but the examples are sufficient to imply when 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?

The description fully discloses failure modes: per-entry fetch failures produce upstream_error and caveat instead of null alert_level, and unreachable/empty lists yield data_status 'unavailable', upstream_error true, empty results, and error in caveats. This matches the readOnly and idempotent 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 logically organized with examples and failure cases, but it is slightly verbose and repeats some details (e.g., failure behavior is mentioned twice). Still, it remains focused and readable.

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 output schema exists, the description doesn't need to enumerate return fields, but it does mention key fields (data_status, upstream_error, results, caveats) in failure scenarios, providing enough context for callers to handle errors without additional lookup.

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 description for volcano_name is comprehensive, including examples and the special case of None returning all monitored volcanoes. There are no enums, but the free-form string is adequately 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 clearly states 'Get current alert level for Philippine volcanoes' and specifies the data source (WOVODAT bulletin list). It is distinct from sibling tools covering earthquakes, weather, and other 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?

Provides explicit examples for calling with no arguments or with a volcano name, and describes behavior when the list is unreachable or a name is unmatched. However, it does not explicitly contrast with sibling tools or state when to prefer this tool over others.

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?

Honestly discloses that only the 'No Active Warnings' state is reliable, and that active warnings may be missed due to navigation text. Also explains data_status values, upstream_error, and caching behavior, making side effects and limitations transparent.

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 slightly verbose but every sentence carries valuable caveats or examples. The structure is logical, covering purpose, limitations, and failure behavior without unnecessary fluff.

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 and caveats, the description covers all necessary context: what it can and cannot do, parameter behavior, failure states, and when to call upstream directly. No missing information that would impair correct usage.

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 covers the region parameter with examples, and the description adds the crucial insight that region only affects the cache key, not the result set. This goes beyond the schema and prevents misuse.

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?

Clearly states the tool fetches active PAGASA weather alerts and advisories, distinguishing it from weather forecasts or typhoon tracks. The examples further clarify its narrow 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?

Provides explicit usage caveats: region only changes the cache key, not filtering; direct access for real-time advisories is recommended; failure modes are described. This tells the agent when to use and not use the 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 annotations already indicate readOnly, idempotent, and non-destructive behavior. The description goes beyond by detailing the data source fallback logic, the exact data_status values on failures (e.g., 'unavailable', 'indeterminate'), and caching behavior. This provides a rich picture of expected behavior without contradicting 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?

The description is well-structured: a clear opening statement, concise paragraphs on fallback and error behavior, and illustrative examples. It delivers necessary details without redundancy or fluff, making it easy to parse.

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 complexity of data sources and error handling, the description covers key output fields (data_status, caveats, upstream_error, days) and explains when they appear. Although the full output schema is not shown, the description provides sufficient context for an agent to interpret results 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 schema already covers both parameters with descriptions (location as municipality/city/province, days as integer with default 3). The description adds practical examples for parameter usage and clarifies error outputs, which enhances understanding. Since schema coverage is 100%, the baseline is 3, but the examples push it to 4.

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: 'Get the weather forecast for a Philippine location.' It uses a specific verb and resource, and the scope is well-defined. It also distinguishes itself from weather-related siblings like get_weather_alerts and get_active_typhoons by focusing on forecasts.

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 explains the fallback behavior (PAGASA vs Open-Meteo) and how to interpret error cases via data_source and caveats, which guides usage. However, it does not explicitly mention when to use this tool over alternatives like get_weather_alerts, so it falls short of fully explicit guidance.

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

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

The description discloses every failure mode in detail: invalid request shape, upstream unavailability, skipped non-numeric rows, and the special case where all rows are skipped. It also mentions the pre-validation of indicator codes to prevent URL redirects. This aligns fully with the readOnly and idempotent annotations, with no contradictions.

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 well-structured: it starts with a clear purpose, provides concrete examples, then lists all failure conditions in a readable bullet-like paragraph. It is detailed but not wordy, with every sentence contributing to understanding the tool's behavior.

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 all necessary aspects for correct usage, including input formats, output expectations through failure cases, and edge cases. Although the output schema is not shown in the prompt, the description explains the key fields (data_status, observations, caveats) and the conditions under which they appear, making it self-sufficient.

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 describes both parameters with 100% coverage. The description adds value by explaining alias behavior, giving examples of per_page values, and clarifying that aliases are curated in INDICATOR_ALIASES. This goes beyond the schema's basic type and default information.

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 fetches a World Bank macroeconomic or social indicator for the Philippines, with concrete examples for both code and alias input. It distinguishes itself from siblings by focusing specifically on World Bank data, though it does not name alternative 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 usage examples and explains the behavior for valid and invalid inputs, including error handling. It does not explicitly contrast with sibling tools like get_poverty_stats, but the purpose is unambiguous enough that an agent can infer when 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?

Beyond the readOnly/idempotent annotations, the description explicitly explains malformed inputs return an empty list rather than a validation error, and that only an upstream API outage produces a failure envelope. This goes well beyond the annotations in setting caller expectations.

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 well-structured with examples and clear behavior notes. It is slightly repetitive around malformed arguments returning empty results, but overall every sentence serves a purpose and the layout aids readability.

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 has optional parameters, an output schema, and no prerequisites, the description covers all necessary caller context: pagination, empty-result behavior, and error semantics. It does not need to describe return fields because the output schema exists.

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 covers all parameters with useful descriptions, and the tool description reinforces this with examples, offset pagination guidance, and the parent_code=None region-list behavior. It adds helpful context without being redundant with 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 clearly states the tool's purpose with a specific verb ('Browse'/'List') and resource ('children of a PSGC node' or 'top-level regions'). The examples further distinguish it from related location tools by showing concrete calls such as list_admin_units(parent_code="072200000").

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 to invoke the tool: top-level regions without parent_code, children with parent_code, and optional level filtering. It does not explicitly compare against sibling tools like get_location_hierarchy, but the examples and parameter semantics sufficiently imply the intended usage.

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

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

The description goes well beyond the readOnly/idempotent annotations by detailing the exact source (nginx directory index), the returned fields (name, URL, last-modified time, size), the fact that no PDF bytes are returned, and the full failure-mode taxonomy with data_status values. It also flags the storm surge folder as stale, adding meaningful 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 detailed but well structured: purpose is front-loaded, followed by mechanism, examples, and failure behavior. Every sentence adds useful information, and the examples with comments make the intended usage immediately understandable.

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 output schema exists, the description covers everything an agent needs: data source, return fields, the important caveat that only URLs are returned, and exhaustive failure-status behavior. Nothing needed for correct invocation 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 input schema already covers both parameters with defaults, ranges, and allowed values, so the baseline is 3. The description adds value by showing example calls, clarifying the meaning of kind as a folder selector, and confirming validation behavior for out-of-range limits and unknown kinds.

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: it lists PAGASA public PDF files from the pubfiles directory index, newest first. It clearly differentiates this from weather-content tools by stating it returns file URLs only, never PDF bytes, which distinguishes it from siblings like get_weather_alerts or get_weather_forecast.

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 usage examples and an explicit when-not-to-use condition: if you need PDF contents, fetch the PDF yourself. It does not name sibling alternatives or conditions for choosing them, but it clearly communicates the intended use case for this 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 discloses detailed error handling: validation errors, upstream outages, indeterminate statuses, and empty rows on failure. It also reveals that missing cells are null, never zero, which is not covered by 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?

The description is long but every sentence serves a purpose: stating the core function, the critical all-dimensions requirement, an example, and detailed failure semantics. It is front-loaded with the most important constraint and well-organized.

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 all relevant operational aspects: required parameters, constraints, error conditions, and return behavior for failures. It is sufficient for an agent to call the tool correctly without needing to see the output 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?

The input schema already provides extensive parameter descriptions, and the description reinforces key points like the need to cover every dimension and the rejection of 'all'/'*'. It adds the practical hint to obtain value codes from describe_psa_dataset, which aids parameter selection.

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 defines the tool as running a bounded query against a specific PSA OpenSTAT dataset. It distinguishes this from sibling tools like browse or search by focusing on retrieving data rows for a known dataset path.

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

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

The description explains how to use the tool (must provide explicit value codes for all dimensions, avoid 'all'/'*') but does not explicitly state when to choose this tool over alternatives like describe_psa_dataset or search_psa_catalog. There is no comparison to siblings, so usage context is inferred.

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 transparently explains return behavior beyond the annotations: it states that no data_status field is set, that matched and upstream_error should be checked, and precisely describes the two failure modes. This is consistent with the readOnlyHint, idempotentHint, and openWorldHint 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 concise and well-structured, with a clear opening statement, useful examples, and explicit failure-mode explanations. Every sentence contributes to understanding the tool's behavior without redundancy.

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

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

Given the simple one-parameter input and available output schema, the description sufficiently covers expected outcomes, including success, ambiguous matches, and both failure modes. It provides all necessary context for an agent to 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?

The schema already describes query as a free-text place name with examples. The description adds meaning by clarifying that fuzzy matching and common nicknames are accepted, which informs how the query parameter is interpreted. No additional parameter details are needed.

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 specific verb and resource: fuzzy-resolve a Philippine place name to a canonical PSGC record. It also differentiates itself from sibling tools by focusing on place-name resolution rather than data retrieval, and includes concrete 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 gives practical usage guidance by noting that common nicknames are handled, ambiguous names return a best match plus alternatives, and failure modes are distinguishable via matched and upstream_error. It does not explicitly compare against alternate sibling tools, but the usage behavior is well explained.

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 goes far beyond annotations by detailing all error conditions (validation_error, upstream_error, indeterminate), data_status values (invalid_request, unavailable, empty), caching behavior, and edge-case handling (e.g., zero results with a real count). This is a model of transparent behavior disclosure.

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 well-structured with paragraphs covering purpose, examples, and failure modes. It is dense with useful information without being redundant. Every sentence contributes essential details, and the formatting makes it easy to scan. Despite its length, it is appropriately concise given the number of edge cases it addresses.

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 all relevant aspects needed to correctly invoke the tool and interpret results: source API, country filter, sorting, output fields (license_id), error handling, and caching. It even includes warnings about consent (reading license_id before reuse). This provides comprehensive contextual information beyond the schema and annotations.

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

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

The input schema already covers the parameters and their constraints (query length, rows range). The description adds value by providing usage examples, explaining the default sorting, and clarifying the effect of invalid values (e.g., rows outside 1-50). Since schema coverage is 100%, the baseline is 3, and the description gives extra context, earning a 4.

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 purpose: searching HDX for Philippine humanitarian datasets by keyword. It also explains the underlying CKAN action and provides concrete examples, making it unambiguous and distinct from sibling tools like search_procurement or search_psa_catalog.

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 examples and details on query and rows parameters, but it does not explicitly contrast with alternatives. However, the tool's specific scope (HDX datasets) and the provided examples make it obvious when to use it, so it falls just short of a 5 due to lack of explicit 'use this instead of X' 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?

Clearly discloses limitations: cost_php is usually null, min_cost_php almost never matches, the upstream DPWH API is blocked, and validation_error is always false. Also states the exact failure return shape, so agents know what to expect.

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 summary is front-loaded and the examples are useful, but the budget caveat is stated twice in slightly different words, adding minor redundancy. Overall it remains appropriately sized.

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 source, filtering scope, parameter caveats, failure behavior, and usage examples. With a full input schema and output schema present, nothing critical is missing for 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?

All seven parameters are described with matching schema types, defaults, and matching semantics (partial match, exclusion of undated records, cap on limit). The min_cost_php caveat is reinforced in 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?

Opens with a precise one-line summary: 'Search Philippine government infrastructure projects.' The scope, data source, and filtering logic (infra-related work categories) are all stated, so an agent immediately knows what the tool returns.

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

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

Provides concrete invocation examples and key caveats (budget data missing, DPWH API blocked, failure object). It does not explicitly contrast with sibling search tools, but the scope and examples make intended usage clear.

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

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

Describes failure behavior in detail: upstream outage returns a structured object with upstream_error and data_status 'unavailable', invalid dates return validation_error; also discloses caching and client-side filtering. This goes beyond the readOnly/idempotent 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?

Description is well-organized: one-sentence purpose, a note on implementation constraints, examples, and a failure-mode paragraph. No redundant content; all sentences carry useful operational 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?

Given the tool's moderate complexity, the description covers caching, filter behavior, examples, and error shapes. It does not explain date formats, but the core calling contract is sufficiently specified and the output schema/annotations fill remaining context.

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 covers limit, agency, region, and keyword decently. Description adds that filters are case-insensitive substring matches and that date_from/date_to are validated. However, date_from/date_to lack format and semantic meaning (e.g., publication date) in both schema and 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?

Clearly names the resource (PH government procurement from PhilGEPS open data) and the action (search). The tool name and title reinforce the scope, and it is distinct from nearby search tools for infrastructure or datasets.

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

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

Provides concrete usage notes: the portal lacks server-side search, so it fetches ~100 notices and filters in-memory; filters are case-insensitive substring matches; data is cached 6 hours. Examples illustrate valid calls including keyword-only and keyword+agency+limit. It does not explicitly contrast with sibling search tools, but the usage context is clear.

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

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

The description fully discloses behavioral traits: read-only, idempotent, first-call latency, 24-hour caching, and specific error conditions (invalid_request, unavailable). It goes beyond annotations by explaining the cold start and caching behavior, with no contradictions.

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 well-structured with clear sections for purpose, examples, and failure modes. It is detailed but not excessively verbose, providing all necessary operational context without redundancy.

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

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

The presence of an output schema covers return format, and the description explains error responses and caching behavior. It gives an agent enough context to decide when to call this tool and what to expect. Could mention output fields, but the output schema handles that.

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?

Both parameters (keyword, limit) are fully described in the schema with defaults and examples. The description reinforces the keyword matching behavior and provides concrete usage examples, adding value beyond the schema itself. Schema coverage is 100%, so this is above the baseline.

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

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

Clearly states the tool searches the PSA OpenSTAT catalog by keyword, explicitly contrasting with browsing level by level. The verb 'find' and resource 'PSA OpenSTAT dataset' are specific, and it distinguishes itself from sibling tools like browse_psa_catalog by emphasizing keyword-based search.

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?

Implies when to use this tool (when you need to find a dataset by keyword rather than browsing) and provides useful performance details (cold start delay, caching) and failure modes. However, it does not explicitly contrast with other search tools like search_hdx_datasets or search_procurement, leaving some inference to the reader.

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 standard read-only and idempotent annotations, the description discloses that the first call fetches and caches the full PSA table for 24 hours. It also transparently enumerates possible failure states (invalid_request, unavailable, indeterminate) and explains that failures are not cached. This goes well beyond the basic 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 somewhat long but well-structured: it opens with the core purpose, then provides examples, and finally covers failure modes. Each paragraph serves a clear function, and the content is not redundant. It is slightly verbose but justified by the need to explain caching and edge cases.

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 that an output schema exists (though not shown in the prompt), the description does not need to detail return values. It does cover important context such as caching, failure behavior, and matching rules, which is sufficient for an agent to invoke the tool and interpret results. The only minor gap is not explicitly describing the output structure, but that is covered by the output 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?

Both parameters (query and limit) are fully described in the input schema, and the description reinforces this with detailed examples of digit vs. text queries and the valid range for limit. The examples add practical clarity beyond the schema's dry descriptions, making the expected input formats unambiguous.

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 purpose: find a PSIC code by description keyword or code prefix. It uses a specific verb ('find') and resource ('PSIC code'), and provides concrete examples that distinguish it from other search tools. The name and description align perfectly.

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 explains the matching logic (digit prefix vs. whole-word text) and failure modes, giving agents enough context to decide when to use this tool. It does not explicitly contrast with sibling search tools, but the specific reference to PSIC codes makes the usage context clear enough for 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?

It discloses metadata behaviors not in annotations: a 6-hour cache, the per-capita sufficiency threshold, the fact that an undated record is dropped, and the exact failure shape (unavailable/upstream_error/real error in caveats). It also calls out the no-op funding_source behavior and retired breakdown. This goes well beyond what readOnlyHint/openWorldHint/idempotentHint tell the agent.

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 long but front-loads the single-line purpose and follows with dense, high-value detail: caching, computable breakdowns, failure shape, and examples. There is no filler or tautology.

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 tool is simple (0 required params, output schema available) and the description covers relevant call dynamics: filtering options, cache freshness, not-enough-data behavior, and failure shape. No additional information seems necessary for an agent to invoke or interpret 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?

With 100% schema coverage, the schema already describes year and region well and calls funding_source a no-op. The description adds value by showing call examples, clarifying that by_funding_source output will be empty, and linking parameters to output behavior (e.g., undated record dropped in caveats).

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 action and resource ('Aggregate infrastructure procurement statistics over the latest PhilGEPS window') and then explicitly ties itself to the same notice window as search_infra_projects, which separates it from that search-oriented sibling. It identifies focus on aggregate infra spending, a distinct purpose from the broader procurement and project-list 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 establishes clear usage context: agent should use it to get aggregate infrastructure statistics over the cached PhilGEPS window, with examples showing valid calls (region='ncr', year=2025). It does not explicitly name when-not-to-use or alternatives, but the connection to search_infra_projects and the aggregate-vs-raw distinction is clear enough to guide selection.

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