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

With no annotations, the description carries the full behavioral burden. It usefully discloses return categories (population, income, poverty, education, housing, commuting) and coverage breadth (~30,000 places, ANY US city), but says nothing about read-only nature, auth requirements, rate limits, or behavior on unrecognized city names.

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

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

Three short sentences, front-loaded with the core purpose and scope before the return-field list. Efficient with minimal waste, though the trailing field enumeration is slightly listy.

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

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

For a one-parameter comparison tool with no output schema, the description adequately covers what it does, the breadth of supported cities, and what data comes back. It leaves minor gaps around input edge cases and constraint (2-6) enforcement, but is largely complete.

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

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

Schema coverage is 100% and the single 'cities' parameter already documents the 2-6 array with an example. The description adds no syntax or format detail beyond the schema, which is expected at this coverage level (baseline 3).

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 (Compare) and resource (demographic data) with a clear scope: multiple US cities side by side. The 'side by side' framing hints at how it differs from single-city siblings like query_demographics, but no sibling is named explicitly, so an agent must still infer which tool to pick.

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 multi-city 'compare side by side' framing implies this is for comparing 2-6 cities, but there is no explicit when-to-use guidance and no named alternative (e.g., query_demographics for a single city). Usage is inferable from the phrasing rather than stated.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that it uses only Census ACS data across about 75 cities and lists comparison dimensions, but it does not state whether it writes or stores anything, what permissions are needed, or what the return format looks like.

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 purpose and speed, then lists compared dimensions and criteria, and ends with the alternative. Every sentence earns its place and there is no waste.

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

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

For a simple three-parameter read-style tool with 100% schema coverage and no output schema, the description is nearly complete: it covers purpose, data source, comparison criteria, and the alternative tool. It leaves minor gaps around return shape and side effects, but not enough to prevent 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?

Schema description coverage is 100%, so the schema already documents city, criteria, and cohortSize. The description lists the criteria enum values and comparison dimensions, adding some context, but does not add syntax or default behavior beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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: find peer cities based on Census demographic data. It distinguishes this fast, Census-only tool from the richer multi-source sibling create_full_cohort. An agent can identify its scope and purpose without opening the schema.

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

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

It explicitly says to use this for quick demographic peer matching and directs the agent to create_full_cohort for richer multi-source comparison. The when-to-use and alternative conditions are stated plainly.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses useful traits such as broad source coverage, 10-20 second runtime, and country auto-detection, but it does not state read-only safety, auth requirements, rate limits, or failure handling.

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 purpose, then grouped source lists by country, and closes with usage and timing cues. The source enumerations are long but informative for setting expectations; there is little wasted text.

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

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

For a complex aggregator with no output schema and no annotations, the description supplies source coverage, latency, and country handling. It leaves the exact briefing structure and error behavior unspecified, but gives enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description repeats country auto-detection and optional specification but adds no syntax or ambiguous-city details beyond what the schema provides, making the baseline score of 3 appropriate.

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

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

The description uses a specific verb and resource: 'Pull data from ALL available sources and assemble a structured executive briefing.' It states scope (city in US, UK, or Canada) and distinguishes itself from sibling query tools as the 'give me everything' tool, so an agent can identify it without opening the schema.

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

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

The phrase 'The give me everything tool' clearly signals when to use this broad aggregator over single-domain siblings. It also gives latency context (10-20 seconds). However, it does not explicitly name alternatives or state when not to use it.

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

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

No annotations are provided, so the description carries the behavioral burden and does reasonably well: it discloses multi-source API calls, the slower runtime, and the ~50-city candidate pool. It does not address latency magnitude, failure behavior if a source is unavailable, or that this is a read-only operation, but the key cost/scope traits are surfaced.

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

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

Front-loaded with the core action and cost tradeoff, then structured into dimension list and criteria options. Slightly long, but every line (sources, dimensions, enum meanings) carries decision-relevant content rather than filler.

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

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

No output schema exists, and the description compensates by spelling out the 12 dimensions being compared and the criteria weighting semantics, so the agent knows what it gets back conceptually. Remaining gaps are return shape details (e.g., scoring/ranking format) which are minor for this tool.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description goes beyond the schema's terse 'What dimensions to weight most' by explaining what each of the six criteria enum values actually prioritizes. That is genuine added meaning for the one parameter an agent is most likely to get wrong.

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

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

States a specific verb+resource ('Find peer cities') and immediately scopes it to the union of four named data sources, listing the 12 comparison dimensions. It explicitly distinguishes itself from the sibling create_census_cohort, so an agent can route between them without opening either schema.

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

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

Provides an explicit alternative and the tradeoff that selects it: 'Richer but slower than create_census_cohort (~50 cities pool)' plus 'Use this for comprehensive benchmarking.' That is a clear when-to-use-this-vs-that signal.

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

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

No annotations are provided, so the description carries the full burden. It discloses what is returned (supported cities and their data categories), which is useful behavioral context, but does not explicitly state that the operation is read-only, has no side effects, or requires no authentication. For a zero-parameter listing tool these are minor gaps, but the description could be more transparent about safety and return behavior.

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

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

Two short sentences with zero waste; the core action and its purpose are front-loaded. Every sentence earns its place, 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?

Given the tool's low complexity (0 parameters, no output schema), the description adequately explains what it returns and why to call it. It could specify the return format more precisely, but for a simple discovery endpoint it is sufficiently 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?

There are zero parameters, so per the rubric the baseline is 4. The description adds no parameter information because none exist, and the schema already fully covers the empty input object.

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 ('List') and resource ('all supported cities and the data categories available for each'), clearly distinguishing this discovery tool from the many query_* siblings that retrieve actual data. An agent can tell immediately that this tool returns a catalog, not query results.

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 says 'Use this to discover what data you can query,' which gives clear context for when to call it before using query tools. However, it does not name specific alternatives or state when not to use it (e.g., if you already know the city/category).

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that free-text is keyword-matched to the closest topic and gives an example of what gets pulled, which is useful. However it never states that this is a read-only, non-mutating operation, nor what happens for an unrecognized topic or a city with no coverage.

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

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

Purpose is front-loaded in the first sentence, and the long topical inventory is dense but earns its space because it supplies the missing enum values plus the data each topic returns. Slightly bloated by bolding/label repetition, but no filler sentences.

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 two-parameter tool with no output schema and no annotations, the description is largely sufficient: it explains inputs, accepted topic values, free-text behavior, and roughly what data each topic yields. It could note the shape of the returned data or the read-only nature, but nothing essential to a correct call is missing.

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

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

Schema coverage is 100% and both parameters are documented, so the schema baseline is met. The description goes beyond it by effectively supplying the missing enum for `issue` (0 enums in schema), enumerating 11 valid topic keys with their canonical strings and covering the free-text fallback — meaning the description materially improves how the agent fills that parameter.

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 ('find all relevant hard data for a city' given an issue topic) and frames itself as a cross-reference engine, which cleanly distinguishes it from the many single-domain siblings like query_housing or query_traffic. An agent can tell this aggregates across domains rather than answering one metric.

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 'residents say X, here's what the data shows' framing plus the topical list makes the use case clear: map a concern to data. It implicitly routes away from single-domain siblings but never states an explicit when-not or names a preferred alternative for narrow lookups, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden. It does disclose the returned data shape (categories, volumes, monthly trends) and a US-only scope restriction, which is useful context. It omits read-only/auth/rate-limit or any pagination behavior, but for a plainly read-only analytics call this is a modest, not severe, gap.

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

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

Purpose and returns are front-loaded efficiently, but the block of thirteen broken '[object Object]' city entries is pure wasted space that interrupts the flow. The remaining prose is tight, so the structure is acceptable but not clean.

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 two-parameter query with no annotations or output schema, the description covers purpose, outputs, scope, and usage reasonably well. The critical gap is the unreadable 'Available cities' list: the one piece of information an agent needs to pass a valid city is effectively missing.

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

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

Schema coverage is 100%, so the baseline is 3. The only parameter-related value the description attempts to add is the 'Available cities' list, but it renders as malformed placeholders ('[object Object]'), giving the agent no usable enumeration and arguably adding noise rather than meaning.

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

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

States a specific verb and resource ('Analyze 311 service request trends') and enumerates the concrete outputs (top complaint categories, request volumes, monthly trends). This clearly separates it from siblings like query_homelessness, query_traffic, or query_city_data, so an agent can route without opening the schema.

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

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

The 'Great for understanding what residents are actually reporting' line implies context and 'US only' sets a scope boundary, so usage is somewhat guided. However, no alternatives or when-not conditions are named (e.g., versus query_city_data), leaving the agent to infer the distinction between this and its 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?

With no annotations, the description carries the full burden and discloses valuable behavioral context: different per-country data sources and scales, and that the US endpoint requires AIRNOW_API_KEY while UK/CA do not. It stops short of describing return format, error behavior, or rate limits, but the auth and data-source disclosure is well beyond the schema.

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

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

Purpose is front-loaded, followed by a scannable per-country breakdown and a single summarizing note. It is efficient, with only minor redundancy between the closing note and the schema's auto-detect guidance.

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 two-parameter query tool with no output schema and no annotations, the description covers the data sources, differing scales, and auth needs an agent needs to call it correctly. Return payload details are absent but are not strictly required given there is no 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?

Schema coverage is 100% and both parameters (including the country enum and its ambiguous-city guidance) are already documented in the schema. The description adds the meaning of the differing scales per country, but largely restates the auto-detection behavior already in the schema, so it lands at 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 opens with a specific verb and resource ('Get air quality data for a city') and scopes the tool to the US, UK, and Canada, cleanly separating it from siblings like query_weather and query_public_health without needing to open any schema.

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

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

It notes that country can be auto-detected or specified for ambiguous cities, which is useful invocation guidance, but it never states when to use this tool versus alternatives such as query_weather or query_public_health, nor any exclusions. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full behavioral burden. It discloses meaningful coverage constraints: US supports 30 cities, UK 11 cities, CA not available, which is genuinely useful scoping information. However, it says nothing about permissions, error behavior for unsupported cities, or data recency.

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

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

The description is compact and front-loads the resource, then organizes availability by country in parallel structure. The final sentence about auto-detection duplicates schema content, but overall there is little waste.

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

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

For a read-only data query with a fully documented two-parameter schema, the description covers coverage scope adequately. It omits any sense of return structure (no output schema exists), pagination, or fallback behavior for unsupported cities, leaving some gaps for an agent to call confidently.

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

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

Schema description coverage is 100%, so the schema already documents both parameters including the ambiguous-city list for the country field. The description's mention of country auto-detection reiterates what the schema already states, adding little beyond the structured fields. 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 the tool returns city government budget data and enumerates the specific fields available (total budget, per-capita spending, category breakdown, council tax Band D). This clearly distinguishes it from sibling query_* tools, though the opening 'City government budget data' is somewhat generic before the specifics arrive.

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 no when-to-use guidance, no conditions distinguishing it from siblings like query_city_data or query_economics, and no alternatives named. The country coverage notes imply availability constraints but do not tell the agent when this tool is the right choice.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the geographic restriction ('US only'), the open data portal source (Socrata), the constrained set of cities and categories, and the return shape ('recent data with category breakdown and sample records'). However, it says nothing about rate limits, authentication requirements, error behavior for unsupported cities, or pagination – meaningful gaps with zero annotation coverage.

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

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

Four tight sentences, front-loaded with the core purpose, followed by the geographic/data-source constraint, supported values, and return shape. Zero filler; every sentence contributes useful scoping 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 4-parameter, no-output-schema tool, the description covers the essential context: what data, which cities, which categories, geographic restriction, data source, and what comes back. Parameter defaults are covered by the schema. Nothing an agent critically needs is absent.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including defaults (limit=50, daysBack=30). The description adds only the category values ('crime, 311') and city list, which are largely redundant with the schema's enum and description. Baseline 3 is appropriate when schema does the heavy lifting.

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 ('Query') and resource ('publicly available data for a US city by category'), and names the data source (Socrata). However, it does not distinguish itself from siblings like query_national_crime, query_311_trends, or query_demographics – an agent might reasonably ask why it would use this general query when specialized tools exist.

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

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

The description implies usage context by listing supported cities and categories ('crime, 311'), giving an agent some idea of when this tool applies. But it provides no explicit when/when-not guidance, no mention of overlapping sibling tools (e.g., query_national_crime vs. the 'crime' category here), and no exclusions beyond 'US only'.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the data source, the coverage limit (17 metros), and the shape of the returned content (overall inflation rate plus category breakdown, YoY rates, monthly trends), which is useful. It does not say what happens for a metro outside the 17, whether this is cached/rate-limited, or how fresh the data is.

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

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

Two short, front-loaded paragraphs with no filler; the source and scope lead, and the returned dimensions follow. Slightly abbreviated but nothing wasteful.

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

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

For a single-parameter read tool with no output schema, the description covers source, coverage, and return shape adequately. The main omission is behavior for unsupported cities and whether metro names must match a fixed list.

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

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

Schema coverage is 100% and the single 'city' parameter is documented with examples in the schema itself. The description adds no extra parameter detail, so baseline 3 is appropriate when the schema fully covers the input.

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 resource (Consumer Price Index / cost-of-living data) with its authoritative source (Bureau of Labor Statistics) and the scope of coverage (metro areas, category breakdown). An agent can tell this is the CPI/inflation tool, though it does not explicitly contrast itself with close siblings like query_economics, query_city_data, or compare_demographics.

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

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

It gives a scope constraint ('17 metros available') that implicitly bounds when the tool is applicable, but there is no explicit when-to-use, when-not-to-use, or alternative-tool guidance. With ~28 siblings that overlap on city data, the absence of routing guidance is a real gap.

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

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

No annotations and no output schema, so the description carries the burden alone. It does disclose valuable behavioral context: the data sources per country, the ~30,000-place US coverage, and the auto-detection logic. It says nothing about return shape, data freshness/vintage, or failure behavior for unmatched cities.

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

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

Front-loaded with the core purpose, then cleanly organized as per-country data inventories, with invocation rules last. Slight redundancy with the schema's country description costs it the top score, but every line is informative.

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

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

With no output schema or annotations, the description must stand alone, and it does cover scope, data categories, and input ambiguity. The remaining gap is the return format/structure, which an agent would want before calling.

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

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

Schema coverage is 100% and the schema already documents both parameters, including the enum and the ambiguity rule, so the baseline is 3. The description largely restates the schema's auto-detection and ambiguous-city guidance rather than adding new semantics (no formats, no canonical city-name guidance beyond what the schema shows).

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

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

The description states a specific verb and resource ('Query demographic data for a city') and enumerates the dataset each country taps (Census ACS, ONS/Nomis, StatCan), which tells an agent exactly what it will get. It does not explicitly distinguish itself from the sibling compare_demographics or query_city_data, so it falls short of a 5.

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 useful invocation guidance — country is auto-detected, and must be supplied for ambiguous cities — but never says when to pick this tool over compare_demographics (multi-city comparison) or query_city_data. Usage context is implied rather than stated.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses the source agencies per country (FRED/ONS/StatCan) and the country auto-detection behavior, but does not cover permissions, rate limits, latency, or what the response contains.

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

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

Front-loaded with the core purpose, then compact per-country indicator lists with no wasted prose. The structure makes coverage easy to scan, which is earned length for a multi-region tool.

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

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

For a 2-parameter, no-output-schema tool with no annotations, the description supplies the key missing context: which indicators exist in which country and how country resolution works. Return shape is not described, but the indicator enumeration substantially compensates.

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

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

Schema description coverage is 100%, so the schema already documents both parameters including examples and the ambiguity caveat for London/Birmingham/Richmond. The description's 'auto-detected or specify' line largely restates the schema's country description, adding no new syntax or format detail. Baseline 3 applies.

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

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

States a specific verb (Query) and resource (economic indicators for a city), and enumerates the indicator families per country (FRED unemployment/HPI/income, ONS CPI/GDP/GVA, StatCan CPI/GDP/retail). It distinguishes itself from regional-scoped siblings, though it does not explicitly differentiate from overlapping siblings like query_employment or query_cost_of_living.

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

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

Usage is implied rather than stated: the geography lists tell the agent what data this tool covers, and 'Country auto-detected or specify with country parameter' gives one operational rule. There is no explicit when-to-use vs alternatives guidance, nor any exclusion for overlapping siblings such as query_employment or query_housing.

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

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

No annotations exist, so the description carries the full behavioral burden. It usefully discloses the underlying source per country (BLS, ONS/Nomis, StatCan LFS) and coverage breadth, but says nothing about rate limits, auth, caching, or freshness of the statistics.

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

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

Front-loads the purpose, then organizes source coverage in compact per-country lines with no filler. The structure is scannable and appropriately sized, though the final sentence slightly duplicates the schema's country parameter text.

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

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

For a 2-parameter read tool with no annotations and no output schema, the description supplies the source landscape and country scope an agent needs to invoke it confidently. Return-value shape is unspecified, but that is a minor gap given the no-output-schema note.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the ambiguous-city list. The description only repeats the auto-detect rule and country set, adding little beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Query employment statistics for a city') and scopes the geography to US, UK, or Canada. It does not explicitly differentiate itself from close siblings like query_economics or query_demographics, so it stops short of a 5.

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

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

Gives implied usage through the country-by-country data source breakdown and the auto-detection rule, but never states when to pick this over query_economics or compare_demographics. Guidance is inferable rather than 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?

With no annotations, the description carries the full burden. It usefully discloses provenance (January 2024 PIT count, AHAR Part 1) and coverage limits (20 cities), but does not describe return format, how missing cities are handled, or any data freshness caveats beyond the snapshot date.

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

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

Two tight sentences that front-load the data source and enumerate returned measures before adding the coverage/date constraint. Efficient, though the long metric list borders on being a data dictionary.

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 lookup with a fully documented schema, the description is enough to know what it returns and its source. It is still incomplete about behavior for unknown cities and the exact response shape, which is not covered by any 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?

Schema coverage is 100%, so the single city parameter is already documented with examples. The description does not add syntax, matching, or case-sensitivity details beyond what the schema provides, making the baseline of 3 correct.

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

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

States a specific source (HUD Point-in-Time), resource (homelessness counts), and scope (US cities, 20 available). It clearly distinguishes itself from thematic siblings like query_housing or query_demographics by naming the exact data source and the specific measures returned.

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

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

Usage is implied by the specificity of the data covered, so an agent can tell this is the tool for homelessness figures. However, there is no explicit when-to-use/when-not guidance and no routing against similar data tools such as query_housing or query_city_data.

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

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

With no annotations, the description carries the full burden and does it reasonably well: it discloses the upstream sources per country and explicitly notes 'No API key needed' for US and UK, which is real auth context an agent cannot get elsewhere. It omits failure modes, rate limits, and return shape, so it is not a 5.

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

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

Front-loaded with the core statement, then per-country breakdowns that each carry distinct information (source, metrics, auth). No filler sentences, though the country-by-country list is on the verbose side for a two-parameter tool.

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

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

No output schema and no annotations, so the description must do the work itself — and it largely does, telling the agent what data each country returns and that no credentials are needed. The main gap is return format (shape, units, currency normalization across US/UK/CA), which is left unspecified.

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

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

Schema description coverage is 100% and both parameters already document auto-detection and the ambiguous-city caveat, so the description largely repeats the schema. Baseline 3 is correct; it adds no format or syntax detail beyond what the schema provides.

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

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

States a specific verb+resource ('Get housing data') and scopes it precisely to three countries with the data sources and metric families (FMR, median income, house prices, housing starts). It does not differentiate itself from the ~27 siblings, several of which touch adjacent domains (query_cost_of_living, query_permits), so it stops short of a 5.

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

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

Usage is implied by the resource (call it when you need city-level housing metrics), and it gives one practical rule — country auto-detected, or specify for ambiguous cities. It never states when to prefer a sibling such as query_cost_of_living or query_city_data, and no exclusions are given.

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

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

With no annotations, the description carries the burden; it usefully discloses provenance (ACS 5-Year, Table B07003) and geographic coverage (~30,000 places), which is real added context. However it omits read-only confirmation, latency, or any caveats about the estimates, so it is only partially 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?

Two tight sentences, metric front-loaded and source/coverage details relegated to the second. No wasted words, though it could be slightly more directive about invocation.

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

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

With no output schema, the description does explain the return values (the percentages) and the geographic/data-source scope, which covers what an agent needs. Missing only usage routing and any behavioral caveats.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents 'city' with examples. The description adds the useful scope note that it works for any US city, but nothing about syntax or formats beyond the schema. Baseline 3 applies.

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

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

States a specific data domain (census geographic mobility) and the exact metric returned (percent moved in from another state/abroad vs stayed). This clearly separates it from generic siblings like query_demographics or query_city_data, though it never names an alternative.

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

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

No when-to-use guidance, no exclusions, and no mention of alternatives among the many query_* siblings. The agent must infer that this is for migration/mobility questions purely from the topic.

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

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

With no annotations, the description carries the full burden, and it does disclose meaningful behavioral traits: geographic granularity differs by country (US state-level, UK street-level, CA CMA-level) and UK data is reported by category. It says nothing about authentication, rate limits, data freshness/lag, or the shape of the result, which leaves real gaps for a data-retrieval tool.

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

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

Front-loaded purpose sentence followed by a tight, scannable per-country breakdown and a one-line note on country handling. Every sentence carries information and nothing is padded.

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 query tool with no output schema and no annotations, the description supplies the key context an agent needs: what each country returns and at what granularity. It is nearly complete, missing only return-format or data-freshness detail that an agent might benefit from.

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

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

Schema description coverage is 100%, so the schema already documents both 'city' (with examples) and 'country' (enum plus auto-detect and ambiguous-city note). The description largely restates the auto-detection behavior, so baseline 3 is appropriate.

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

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

The description names a specific verb and resource ('query crime data') and scopes it to three countries, with per-country detail on the underlying sources (FBI UCR, data.police.uk, StatCan UCR). It clearly distinguishes the tool from non-crime siblings like query_public_health or query_demographics by domain, though it does not name any sibling explicitly.

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

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

Usage is implied by the domain (call it when you need crime statistics) and it usefully notes that country is auto-detected and required for ambiguous cities such as London or Birmingham. However, it gives no explicit when-to-use vs alternative guidance and names no competing sibling 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?

With no annotations, the description must carry the behavioral burden; it discloses the data source, geographic limit (US only), granularity claim, and time window (2020-2024), which is genuinely useful. It says nothing about data freshness, caching, pagination, or return shape, and the 'county level' claim sits oddly against a city-only parameter.

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

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

Two short, front-loaded paragraphs with no filler; the source and scope come first and availability second. Slight redundancy/ambiguity around cities vs. county-level output keeps it from a 5.

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

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

No output schema or annotations exist, so the description does the heavy lifting and mostly succeeds: source, scope, timeframe, and dataset size are all covered. The unresolved city-vs-county granularity is the one real gap for an agent deciding whether the result matches its need.

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

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

Schema description coverage is 100% for the single 'city' parameter, so the baseline is 3. The description adds the useful constraint '52 cities available', but the stated county-level granularity conflicts with the city-only input rather than clarifying 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?

Names a specific resource (building permit trends) with source (Census Bureau Building Permits Survey) and scope (US only, 5-year 2020-2024 trend). This clearly separates it from siblings like query_housing or query_city_data, though it never explicitly names the adjacent alternative.

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

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

No when-to-use or when-not-to-use guidance relative to siblings such as query_housing, query_city_data, or query_economics. The line 'Rising permits = development activity; declining = slowdown' is interpretation help, not selection 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?

With no annotations, the description carries the full burden and does disclose meaningful behavioral facts: data provenance (BRFSS/CDC PLACES), coverage breadth (500+ cities, 30+ measures), and no API key required. It omits error behavior and rate limits, keeping it short of a 5.

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

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

Front-loaded with the core action and source, then measure list, then usage hint. Efficient overall, though the trailing 'Great for' sentence leans slightly promotional.

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?

No output schema exists, but the description enumerates the returned measure categories, which largely compensates. Provenance and coverage are also covered; only return format specifics (units, aggregation level) are missing.

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

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

Schema description coverage is 100% for the single 'city' parameter, so the schema already documents the format and examples. The description adds nothing beyond it, making the baseline 3 appropriate.

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

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

States a specific verb+resource (get public health indicators) and names the data source (CDC PLACES) plus scope (US city). It clearly distinguishes from domain-different siblings like query_employment or query_weather, though it never names a sibling explicitly.

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

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

The 'Great for' line implies usage contexts (community health understanding, social media anchoring) but offers no explicit when-not conditions and no routing to alternatives like query_city_data or query_demographics.

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

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

With no annotations, the description carries the full burden and does well: it discloses per-country auth requirements (GOOGLE_CIVIC_API_KEY, TWFY_API_KEY, none for CA), the source backends, and the auto-detection behavior. It omits error behavior, rate limits, and coverage limitations, keeping it short of a 5.

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

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

Front-loaded purpose followed by a compact per-country block; every line (provider, official level covered, key requirement) carries information an agent needs before calling. No filler sentences.

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 2-parameter lookup with no output schema or annotations, the description covers the essentials: sources, auth, geographic scope, and the level of officials returned per country. It does not describe the response shape or attribution requirements, which is a minor gap given no 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?

Schema coverage is 100%, so both parameters are already documented in the schema, including the auto-detection and ambiguous-city rule. The description restates the country override rather than adding format or resolution detail beyond the structured fields, matching the baseline for high 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?

States a specific verb and resource ('look up elected officials') and scopes it to three countries with named upstream providers. It is immediately distinguishable from demographic, crime, or transit siblings, which query statistics rather than officeholders.

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

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

Gives clear context for use: which backend serves each country, which require API keys, and that country is auto-detected or can be overridden. It stops short of naming alternatives or stating when not to use it, so it is context-rich but not routing-complete.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose valuable coverage limits (US limited to 52 cities, CA unsupported) and the underlying data sources (NCES, DfE GIAS), but says nothing about permissions, rate limits, response shape, or whether results are read-only snapshots.

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

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

Front-loads the core purpose, then organizes the data-source detail by country in a scannable structure. Every line earns its place, though the standalone 'CA: Not yet available.' line could be folded in without loss.

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

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

With no output schema, the description does the work of indicating what data comes back per country, which is the right thing to cover. The 52-city US limitation is a helpful completeness note, though the exact response structure and any pagination or result-count behavior remain unstated.

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

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

Schema description coverage is 100% and the schema already documents both city and country, including the ambiguous-city rule. The description only restates auto-detection with the country parameter, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific resource (school data) and immediately enumerates what is returned per country — enrollment, student-teacher ratios, finance (US); school counts, types, Ofsted ratings (UK). An agent can tell this apart from siblings like query_demographics or search_uk_datasets from the description alone.

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 implies when the tool applies by scoping geography (US/UK supported, CA 'not yet available'), which usefully prevents misuse for Canadian cities. However, it names no alternative tool and gives no explicit when-to-use guidance relative to siblings such as search_uk_datasets or query_city_data.

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

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

With no annotations, the description carries the full behavioral burden. It does usefully disclose data vintage (2019-2022), coverage limits (county primary view, congestion only for 33 metros), and that no API key is required. However it omits response behavior, error handling, and anything about result size or freshness beyond the fixed year range.

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

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

Front-loaded with the data sources and scope, then coverage caveats. Every sentence carries information, though the staging of 'No API key needed' and the geo-resolver line is slightly disjointed from the rest.

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

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

With no output schema, the description steps in to describe return contents (fatal crash statistics with pedestrian, cyclist, and alcohol breakdowns) and the county/state granularity. That is enough to call it correctly, though it doesn't hint at response shape or volume.

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

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

There is a single parameter with 100% schema description coverage and inline examples ('Denver', 'Austin', 'NYC'). The description adds no format or naming guidance beyond the geo-resolver claim, so the schema does the work and a baseline 3 applies.

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

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

The description names a specific topic (traffic safety + congestion) and its underlying datasets (NHTSA FARS, TTI), which clearly distinguishes it from siblings like query_transit or query_city_data. It never explicitly contrasts itself with those alternatives, but the resource 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?

It states the geographic constraint ('US only') and that any US city works via the geo-resolver, but there is no when-to-use guidance, no mention of when to prefer query_transit or query_city_data, and no exclusions. The agent must infer the use case entirely.

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

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

With no annotations, the description carries the full burden. It usefully discloses the underlying data sources and the unavailability of CA coverage, but says nothing about return format, data recency, pagination, or any auth/rate constraints an agent would need to set 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 text is short and front-loaded with the core purpose, then bullets the country coverage compactly. The bulleted fragments read slightly telegraphically but waste no words.

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 two-parameter, no-output-schema query tool, the description covers scope, sourcing, country handling, and a coverage gap (CA). What remains missing is how results are returned, but that is a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the auto-detection rule and the ambiguous-city caveat. The description largely restates that same auto-detection behavior, adding little semantics beyond the schema, so the baseline 3 applies.

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

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

The description states a specific resource (public transit/transport data) and breaks it down by source and country (NTD ridership, DfT road/bus/rail), which lets an agent distinguish this from siblings like query_traffic or query_city_data. It stops short of naming an alternative tool directly, so it lands at a solid 4 rather than 5.

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 useful operational context – country auto-detected, CA not yet available, and that ambiguous city names require the country parameter. However, it never says when to choose this tool over query_traffic or search_uk_datasets, so usage selection remains implied rather than 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?

No annotations are provided, so the description must carry the full behavioral burden. It discloses data sources and that no API key is needed, which is useful. However, it omits critical behavior: error handling for unsupported cities, rate limits, data freshness/update frequency, and what the response looks like.

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?

Information is front-loaded with the core purpose, then structured by country. Sentences are efficient and earn their place. Could be slightly tighter by combining the country bullets.

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 2 parameters (one enum) and no output schema, the description covers the essentials of what data is returned and source constraints. However, it lacks error behavior, output format details, and explicit tool selection guidance, leaving gaps 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?

Schema description coverage is 100%, so the baseline is 3. The description adds marginal value by listing the countries supported and noting auto-detection, but it doesn't provide additional syntax or format details beyond what the schema already documents.

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 ('Get') and resource ('real-time water monitoring data') with clear scope (US/UK/CA cities). Distinguishes itself from siblings like query_weather or query_air_quality by naming the data sources and metrics (streamflow, levels, discharge). However, it doesn't explicitly explain how it differs from query_city_data, which might be a broader aggregator.

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?

Implicitly tells when to use it (need real-time water data for a supported country), but provides no explicit when-not-to-use criteria or named alternatives. The country auto-detection and ambiguity warning imply usage context but don't guide selection among sibling 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?

No annotations are provided, so the description carries the full burden, and it does well: it discloses the upstream data source per country (NWS, Met Office DataHub, MSC GeoMet), the auth prerequisite for the UK (METOFFICE_API_KEY), and which providers need no key. It does not mention rate limits, failure behavior, or pagination, so it stops short of full behavioral coverage.

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

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

Front-loaded with the core purpose, then a compact per-country breakdown where each line earns its place. No redundancy or 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?

With no output schema and no annotations, the description must carry the definition, and it covers coverage area, data sources, auth needs, and roughly what is returned (conditions, forecast, alerts). It could be slightly more complete by describing the response shape or error cases, but nothing essential for a correct call is missing.

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

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

Schema coverage is 100%, and both parameters (city, country enum with auto-detection and ambiguity notes) are fully documented in the schema itself. The description restates country auto-detection and the ambiguous-city case but adds no syntax or format detail beyond structured data, so the baseline 3 applies.

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

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

States a specific verb+resource ('Get current weather conditions and forecast') with an explicit geographic scope (US, UK, or Canada). It is immediately distinguishable from siblings like query_air_quality or query_water without opening the schema.

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

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

Gives clear context for how the tool behaves per country and how to disambiguate, and explicitly notes the UK path requires METOFFICE_API_KEY. However, it never states when to prefer this tool over an alternative (e.g., air quality or UK dataset search), so the routing guidance is implied rather than 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?

With no annotations, the description carries the full behavioral disclosure burden. It notes 'No API key required' and that results include titles, publishers, formats, and links, which is useful. But it omits rate limits, pagination behavior, whether the search supports filtering, and failure modes. This is a thin behavioral profile for a network-backed search tool.

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

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

Three short sentences: purpose, return fields, and an operational note. Every sentence delivers information and is front-loaded with the primary action. No filler or redundancy.

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

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

For a simple two-parameter search tool with a fully documented schema and no output schema, the description covers the essentials: what it searches, what it returns, and that no auth is needed. However, without annotations it should do more to explain return shape (e.g., result count limits, pagination), and it doesn't help distinguish from the many sibling query tools. It is minimally complete but leaves 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?

Schema description coverage is 100%, so the baseline is 3. The description adds a concrete example of the catalogue domain ('data.gov.uk') and mentions the returned fields, which slightly enriches understanding of what the query parameter targets, but it doesn't add parameter syntax or format detail beyond the schema. The example-driven schema already provides good guidance, so the description is adequate but adds marginal value.

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

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

The description states a clear verb+resource: 'Search the UK government's open data catalogue (data.gov.uk).' This distinguishes it from the many query_* siblings that appear to target specific data domains (crime, housing, weather, etc.), since this is a general catalogue search. However, it does not explicitly name or contrast with those siblings to help an agent choose.

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 by naming the catalogue to search, but offers no explicit when-to-use guidance or alternatives. Siblings like list_available_data or the numerous query_* tools could overlap, yet the description doesn't state when this broad search is preferable. No exclusions or prerequisites are given.

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

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

With no annotations, the description carries full burden and does meaningful work: it discloses the underlying data sources, the return structure (per-metric improving/declining/stable tags), and the analytical framing. It omits anything about auth requirements, rate limits, latency, or data freshness, which are the remaining gaps.

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

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

Front-loaded with the core purpose, then supporting sources, then output shape. Mostly earns its place, though 'Great for spotting momentum or emerging problems' is soft marketing filler that a stricter version would cut.

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

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

For a one-parameter read-only aggregate with no output schema and no annotations, the description gives enough: what it aggregates, what it returns, and the directional tagging scheme. Only the absence of any data-source caveats or freshness notes keeps it from 5.

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

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

Single parameter with 100% schema description coverage, so the schema already documents 'city' fully with examples. The description adds nothing about city syntax (e.g., supported formats, whether metro areas count), so baseline 3 applies.

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

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

States a specific verb+resource ('show how a city is changing') and immediately names the aggregation scope — BLS, FRED, FBI, permits, 311 — which distinguishes it from the single-domain siblings like query_employment or query_311_trends. The output shape ('directional dashboard') is also stated, so an agent can tell what it gets without opening a schema.

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

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

Gives clear context ('spotting momentum or emerging problems'), which tells the agent this is a trend/aggregate tool rather than a raw-data query. However, it never names an alternative or states a when-not condition (e.g., use query_city_data for raw values), so the exclusion guidance is absent.

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