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

Beyond annotations (readOnlyHint), the description discloses that key values are never shown, only boolean 'currentlySet'. It explains the return JSON structure, how keys are loaded (env vars/.env), and that this tool reports config state, not key validity. No contradictions with annotations.

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

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

The description is detailed but every sentence adds value. It could be slightly more concise, but the length is justified given the complexity of the tool. It front-loads the purpose and then provides necessary specifics.

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

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

The description is exceptionally complete: it specifies the return structure, behavior around key values, key sources, setup mechanisms, and distinguishes between config and functional verification. It compensates fully for the lack of 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?

With 0 parameters and 100% schema coverage, the description reinforces that the tool is 'KEYLESS (no input)', adding clarity beyond the empty schema. It eliminates any doubt about required inputs.

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: 'List every API key this server can use' with specific details about required vs optional, signup URLs, and configuration status. It distinguishes itself from data-fetching sibling tools by focusing on configuration state.

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

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

The description explicitly says when to use this tool (check configuration state) and when not (to verify a key works, call the source's own tool). It provides guidance on key setup (env vars or .env file). A clear 'when-not' is given, but no explicit listing of alternative tools for verification.

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 (readOnlyHint=true, openWorldHint=true), the description discloses extensive behavioral details: the exact meaning of totalAvailable (exact match count, never page length), handling of ArcGIS epoch millisecond date fields with negative/sentinel placeholders, explicit behavior for no-match (complete:true/returned:0), error throwing on 429/5xx/timeout, invalid_input/upstream for ArcGIS error bodies, and schema_drift for non-array features. It also details SSRF protections. This is far more than annotations provide and contradicts none of them.

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

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

The description is long but densely packed with essential information. It is structured logically: purpose, data details, parameter explanations, honesty behaviors, and SSRF protections. It front-loads the purpose and key differentiator. While it could be more concise, every sentence adds value, and the length is justified by the complexity of the tool's behavior and error handling.

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

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

Given the absence of an output schema, the description fully covers the return format ('{ service, records:[{…attributes verbatim…}] } + honest _meta') and error behavior. It also explains the semantics of key parameters and the data quality rules. For a tool of this complexity, it leaves no critical gaps for an agent to call it correctly. The description is 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 description coverage is 100%, so the baseline is 3. The description adds substantial value: it explains the 'service' parameter as an allowlist ENUM with 27 services and describes the content of each, gives example 'where' clauses, explains 'outFields' default and usage, and clarifies 'limit' and 'offset' mapping to ArcGIS parameters. It also explains the meaning of the returned fields (e.g., date handling). This goes beyond the schema descriptions, justifying 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 'Query rows from a curated US-government ArcGIS REST feature layer' and positions it as 'the QUERY companion to arcgis_hub_discover_datasets', which differentiates it from the sibling discovery tool. It also enumerates specific services (DC PASS, etc.), giving a concrete resource scope. The verb 'Query' and the resource are specific, making the purpose unmistakable.

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 names the companion tool for discovery and implies that this tool is for querying rows from those discovered layers. It gives context on where the data lives ('SLED procurement/GIS data') and provides examples of usage (e.g., 'where' clauses). However, it doesn't contrast with other query tools like socrata_query or ckan_query, so it's not exhaustive about when to choose this over those. Still, it gives clear direction relative to its direct sibling, which is strong.

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

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

Even though annotations already declare readOnlyHint=true and openWorldHint=true, the description adds extensive behavioral context: global non-US/non-governmental publishers, verbatim provenance fields, honest meta semantics, exact totalAvailable behavior, null/boolean handling, 429/5xx/timeout error modes, and schema-drift detection. It fully discloses what the tool can and cannot guarantee.

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 it is densely packed and every sentence earns its place given the tool's complexity and the critical caveats around provenance and non-curated data. It front-loads the core purpose and then layers parameter semantics, discovery-vs-read guidance, and honesty guarantees in a readable, labeled structure.

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 supplies the full return shape, pagination semantics, exact match-count behavior, error conditions, and the crucial global-platform caveat. For a discovery tool with open-world data and trust implications, nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description still adds significant value by mapping each parameter to its Hub API equivalent (q, filter[openData], page[size], page[start]), stating defaults and constraints, and explaining real-world semantics such as the B2G relevance of openDataOnly=true.

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: "Discover ArcGIS Hub datasets by keyword," and immediately positions it as the SLED/GIS open-data layer not covered by Socrata and CKAN. It clearly distinguishes this discovery tool from sibling data-access tools without ambiguity.

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 names explicit alternatives and selection conditions: Socrata/CKAN do not cover this layer, arcgis_feature_query covers only a curated allowlist for reading rows, and socrata_query is a curated official-source allowlist whereas this tool is explicitly not. This is ideal usage routing.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral detail: key requirement and error behavior (honest config error, HTTP 200 with Error object surfaced as invalid_input), parsing of comma-formatted dataValue, mapping of suppression codes to null, non-pre-multiplied unitMult/unitOfMeasure, complete results without pagination, and handling of empty data, 5xx, and non-JSON responses. This far exceeds what annotations alone provide.

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

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

The description is long but every section earns its place. It starts with the core purpose, then critical key requirement, then parameter details, and finally return and error handling. The use of ★ markers highlights key points. It's structured with labels (Input, Returns, HONESTY) and is comprehensive, though it could be tightened without losing 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 tool with 5 parameters, an external API key requirement, and complex error handling, the description covers all essential aspects: parameter formats with examples, return schema (rows and notes), data parsing behavior, suppression codes, pagination absence, and error scenarios. There is no output schema, so the description correctly carries the full burden of explaining return values. It is complete for an agent to call correctly.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds valuable context by giving example table names (CAGDP2, SAGDP2N, CAINC1/SAINC1), explaining lineCode as integer or 'ALL', year options (LAST5, 4-digit, ALL), and frequency choices. It also clarifies the return format, which is not in the schema. This adds meaning 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 provides regional GDP by industry and personal income from BEA Regional Economic Accounts, specifying the dataset and scope (county/state/MSA). It names example tables, making the purpose unambiguous. Though it doesn't name a sibling, it is distinct in this toolset as the only BEA regional data 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?

It explicitly states the tool requires a free BEA_API_KEY, explains there is no keyless tier, and directs users to api_key_status for checking. It also describes the input parameters and options, giving clear guidance on how to invoke it. It doesn't discuss alternatives because none exist for BEA regional data, but it covers prerequisites and invocation fully.

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 readOnlyHint=true and openWorldHint=true, the description discloses a wealth of extra behavior: value:null instead of an error for suppressed/unsurveyed values (H2), measure.units is deterministic per datatype (H3), the API returns real numerics with no top-code (H4), rate limits and series caps with throwing behavior, and the promise of an 'honest _meta'. These are substantive behavioral details not derivable from annotations alone.

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 front-loaded: the core purpose and key constraints appear before the detailed return shape and H1-H4 highlights. Every sentence carries essential caveats for a complex API. Some redundancy exists (e.g., 'NO year input' appears twice), but the structure (inputs → returns → highlighted notes) makes it navigable. It earns its length for the tool's complexity.

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 fully specifies the return object: the result fields (area, occupation, measure, value, valueUnavailable, referenceYear, referencePeriod, footnotes, seriesId) and the '_meta' object. It also details error modes (rate_limited throws, invalid_input for unknown tokens), series caps, and the annual point-in-time nature. An agent has all necessary information to invoke the tool correctly without guessing.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description adds meaningful extra semantics: the mutual exclusivity of occupation/soc (at least one required), the 'NO hyphen' SOC constraint, the area resolution to areatype + zero-padded code with unknown tokens rejected, and the units mapping per datatype. While some details duplicate the schema, these additions clarify interpretation and edge cases enough to merit above-baseline scoring.

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 identification: 'BLS OEWS occupational wage/employment benchmarking by area × occupation × datatype'. It clearly states what data the tool returns (wages/employment from the BLS OEWS API) and differentiates it from similar siblings like bls_timeseries by emphasizing 'NO year input (OEWS serves only the latest annual release)' and 'NOT monthly/current-quarter'.

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

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

The description gives explicit when-not-to-use guidance: 'NOT monthly/current-quarter' and 'NO year input', which steers agents away from using it for time-series or historical queries. It also explains when to use occupation (curated, typo-proof) versus soc (raw long-tail passthrough) and provides defaults and required constraints. However, it never names alternative sibling tools directly, so the exclusion is clear but not fully 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?

Exceptional disclosure beyond the readOnlyHint/openWorldHint annotations. It explains the QCEW suppression semantics (literal-0 encoding, 'N' vs '-' vs blank handling, never blanket 0→null), exact error behavior (404→honest empty, 5xx/timeout→throw, schema_drift→throw), and the fetch-once pagination model. This goes far beyond the annotations' low burden.

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

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

The description is long and dense, but nearly every sentence earns its place given the tool's complexity — the 0→null disclosure trap, pagination honesty, and NAICS edge case are genuinely load-bearing for correct invocation. It is front-loaded with the identifying purpose. The formatting is a wall of text rather than structured sections, which 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?

For a 10-parameter tool with no output schema, this is exceptionally complete: it describes the return shape, the three disclosure codes per row, pagination semantics, error behaviors, and required/optional routing. Nothing an agent needs to call it correctly is missing; the complexity is fully matched.

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?

Though schema coverage is 100% (baseline 3), the description adds high-value semantics: cross-conditional requirements (area REQUIRED for mode=area, industry REQUIRED for mode=industry), the hyphenated-NAICS trap, ownership code mappings (0/1/2/3/5), and the anti-double-counting guidance for aggregationLevel. It materially improves parameter 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?

Opens with a precise statement of function — 'county×NAICS market-size / wages / location-quotient' — naming the resource (BLS QCEW), the data product, and the data source. The two slice shapes (area/industry) are spelled out, making it instantly distinguishable from sibling bls_timeseries and bls_oews_wages.

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 extensive when-to-use guidance nested in the parameter rules: when mode=area vs mode=industry, year coverage window, the explicit NAICS hyphenation pitfall ('31-33 404s'), and the aggregationLevel advice to filter to one agglvl_code. It lacks explicit exclusions naming alternatives, but the mode/parameter routing is thorough enough to qualify as clear context.

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

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

The description discloses far beyond annotations (readOnlyHint/openWorldHint): missing-value handling ('BLS '-' → value:null, NEVER 0'), units warnings ('ECI …A is a 12-month PERCENT CHANGE'), error conditions ('status !== REQUEST_SUCCEEDED THROWS'), tier caps ('overflow is NEVER silently dropped'), clamping, totalAvailable null, typo behavior, and API key placement. These are concrete behavioral traits that materially affect invocation and result interpretation. No contradiction with annotations.

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

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

The description is dense but front-loaded with purpose and key constraintsaren't the core. Every unique behavioral detail (honesty, units, errors, clamping, typo handling) earns its place. However, it repeats some schema content verbatim (e.g., 'At least one of series/seriesId is required; both may be combined' and the charclass) which adds length without new value. Still, it is well-structured and not 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?

This is a complex tool with no output schema, yet the description fully compensates: it specifies the return shape (`series:[{seriesId, key, meaning, units, observations:[...]}]`), error statuses and retryability, tier caps and clamping, missing-value semantics, unit caveats, and even auth key transport. The only thing left to the schema is year-range boundsio, which schema already covers. Nothing an agent needs to call this 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?

Schema description coverage is 100% and already rich: enum meanings, units, charclass for seriesId, defaults for startYear/endYear, and the requirement that at least one of series/seriesId must be provided. The description largely restates these constraints and adds only marginal parameter-level info such as the v1/v2 cap defaults (which are also covered by schema's 'clamped to tier cap' note). It adds value in the behavioral realm, not parameter semantics, 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 opens with a specific verb+object+scope: 'Fetch one or more BLS time-series over a year range.' It further disambiguates from siblings by referencing raw OEWS IDs and mentioning the BLS API, making it distinct from fred_series_observations or bls_qcew. The naming of curated vs raw series also clarifies the tool's two modes of operation.

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 curated `series` keys vs raw `seriesId` passthrough, including examples like 'OEWS area×occupation, local-area unemployment LAUCN…, SA/regional CPI variants.' It also explains v1 vs v2 key usage and span clamping. However, it does not explicitly name sibling alternatives (e.g., bls_qcew or bls_oews_wages) or state when *not* to use this tool in favor of those, stopping short of full exclusion 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 mark readOnlyHint/openWorldHint, and the text goes further by disclosing that this is a curated, live-verified seed of 186 US orgs, that it is partial relative to Bonfire's ~900 orgs, and that totalAvailable is the exact filtered seed count. This prevents false expectations about completeness.

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 parameters, output shape, pipeline, and caveats in a logical order. Despite the density, every sentence adds needed information for a partial, non-obvious data source; there is no filler or redundant restatement of the schema.

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

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

For a tool with no output schema, the description supplies the return shape, pagination semantics, the downstream tool, and critical data-provenance caveats. An agent can decide whether the curated seed is sufficient and knows how to extend it, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the structured schema already documents all four parameters. The description restates filtering and pagination behavior but does not add materially new meaning beyond connecting the filters to the curated seed, so the high-coverage 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 names a specific verb ('List'), a concrete resource ('US governments on Bonfire/Euna eProcurement platform'), and positions itself as 'the directory for bonfire_search_opportunities (keyless)'. This clearly distinguishes it from the many sibling search tools and even previews the output shape.

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 intended pipeline: list organizations, then feed a result's `org` to bonfire_search_opportunities. It also gives explicit exclusions ('Bonfire has NO keyless org-list API... auth-gated, out of bounds') and a concrete extension path ('probe {slug}.bonfirehub.com/opportunities/rss to extend').

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?

Goes far beyond the readOnlyHint and openWorldHint annotations. Discloses that the RSS is the complete set, client-side pagination, exact totalAvailable, honest empty result, error handling (429/5xx/404 throw, no fake empty), schema drift detection, invalid input pre-fetch, fixed-suffix SSRF, and keyless access. Fully 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 long but well-structured with clear sections (HONESTY, etc.) and no wasted sentences. It front-loads the main purpose. A touch verbose but justified by the complexity.

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 output schema, the description explicitly declares the return shape ({ org, opportunities, _meta }) and covers edge cases (empty feed, errors, schema drift). This is complete for an agent to understand and use 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?

All three parameters have schema descriptions, but the description adds critical context: org is from bonfire_list_organizations, limit is 1-200 with default 50, offset is 0-based, and these are client-side pagination over a complete RSS feed. This meaningfully augments 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?

Description clearly states the tool lists currently-OPEN solicitations on Bonfire via RSS. It specifies the source (Bonfire), the scope (open), and the method (keyless RSS), distinguishing it from other government opportunity tools like SAM.gov or Grants.gov.

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

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

Explicitly states that the tool is keyless and requires an org slug from bonfire_list_organizations. It also clarifies that the RSS is the complete set and errors are thrown. However, it does not explicitly compare to sibling opportunity search tools like sam_search_opportunities or opengov_search_solicitations, which would help an agent choose between them.

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 null handling (0 stays 0, closed lanes are null), update time freshness, response integrity (throws on errors, no fake empties), and the _meta field. This provides deep behavioral transparency.

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 lengthy but well-structured with front-loading of the core purpose and subsequent sections for details. Every sentence adds value, though slight trimming could improve conciseness without losing content.

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

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

Given the complexity of real-time operational data with null handling, client-side filtering, and no output schema, the description is remarkably complete. It explains the data structure, null semantics, error behavior, and metadata, leaving no critical 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 has 100% parameter descriptions. The description adds critical context: filters are applied client-side, no server-side filter, empty string reported in _meta.filtersDropped, and pagination via limit/offset. This adds meaningful semantics beyond 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 provides live CBP land-border-port wait times for commercial vehicles at US Canadian and Mexican border ports, using specific verbs ('Live wait times') and resource ('CBP land-border-port'). It is unique among siblings, which are unrelated government data 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 explicitly states it is for freight/logistics situational awareness and notes that passenger lanes are not surfaced. While it does not explicitly state when not to use, it provides clear context about its scope and limitations, guiding 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?

Annotations provide readOnlyHint=true and openWorldHint=true, but the description goes far beyond by dislosing: the tool throws config errors without key, honest handling of missing/invalid keys (invalid_input with 302), mapping of suppression sentinels to null (never negative or 0), that results are complete (no pagination), and potential schema_drift on non-JSON responses. It also clarifies that the key rides only in query param. This is exemplary behavioral disclosure, far exceeding what annotations convey.

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 but somewhat lengthy, with multiple clauses and parenthetical explanations. While it front-loads key requirements (API key) and facts, it could be tightened without losing clarity. It is not excessively wordy given the complexity, but it is not as crisp as it could be.

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 (5 params, no output schema, external API quirks), the description covers all critical operational details: key requirement, error handling, data format nuances, pagination absence, and parameter dependencies. An agent can confidently and correctly invoke the tool with this description alone. Nothing critical is missing.

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

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

Schema description coverage is 100% and each parameter's description is thorough, including validation and required relationships. The tool description adds value by giving examples (e.g., '5415') and clarifying optionality, but the schema already carries the essential meaning. Since coverage is high, baseline 3 is appropriate; the description slightly enhances but does not need to compensate.

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

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

The description states a specific verb ('market sizing'), a clear resource (Census CBP data by NAICS and geography), and lists the output fields. It distinguishes itself from sibling tools like census_geocode_address and census_geographies_by_coordinates by focusing on business patterns data. It fully communicates what the tool does.

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 explains when to use the tool (market sizing) and provides critical usage context: mandatory API key, no keyless tier, where to get the key, how to check key status, and details for each parameter (e.g., county requires state, NAICS optional). It effectively guides the agent on when to invoke this tool versus 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?

Even with readOnlyHint=true, the description goes well beyond annotations: it discloses genuine-empty behavior, multi-match surfacing, historical vintage alternate geographies, HTTP 400 throwing on invalid input, and a mandatory caveat about non-authoritative set-aside determination. This is unusually thorough 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 long but densely informative, front-loading the core purpose before layering edge-case behavior and the mandatory caveat. It avoids fluff, though it does partially restate schema enum content and could be tightened with clearer sectioning.

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 compensates fully by describing the return shape ({matches, matchedAddress, coordinates, geographies, etc.}), error behavior, edge cases, and the caveat about HUBZone/OZ determination. For a complex 3-parameter tool with vintage-dependent behavior, nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents address, benchmark, and vintage. The description adds meaning by stating the 500-character limit, defaults for benchmark/vintage, the 'Current is a MOVING vintage' caveat, and the benchmark-vintage compatibility matrix fail-closed behavior -- all beyond what the enum descriptions alone convey.

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

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

The description opens with a precise verb-resource pair: 'Resolve a one-line US address → matched address(es) + the Census GEOGRAPHIES'. It also names the specific government service and analysis use case (set-aside / place-of-performance), which clearly positions the tool relative to siblings like census_geographies_by_coordinates.

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 states the analysis context ('for set-aside / place-of-performance analysis') and gives practical guidance on address quality, empty results, and follow-up with SBA/Treasury data. It does not explicitly name alternative tools or state when NOT to use it, so it stops short of full exclusion 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 provide readOnlyHint and openWorldHint, but the description adds extensive behavioral details: honesty about null geographies for non-US points, coordinate finiteness check, vintage handling with alternates, GEOIDs as strings, moving vintage warnings, and mandatory caveats. 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 thorough but somewhat verbose, with sections like 'HONESTY:' that could be integrated more concisely. It is front-loaded with the purpose, which is good, but could be tighter.

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 (6 parameters, no output schema), the description is very complete. It covers edge cases (offshore, historical vintage, bad benchmark), mandatory caveats, and explains the return structure with geographies keys.

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%, baseline 3. The description adds value by explaining the x/y aliases, giving examples, and clarifying benchmark/vintage compatibility and defaults.

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 resolves a longitude/latitude point to Census geographies, and distinguishes itself from address-based geocoding (sibling census_geocode_address). The verb 'resolve' and resource 'Census GEOGRAPHIES' are specific.

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 'no address parsing' and 'for a caller that already holds coordinates', indicating when to use. However, it does not explicitly compare to alternatives or state when not to use, though the implication 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 extensively discloses behavior beyond annotations: caching, honesty in field values, failure mode (throws on catalog errors, no fake-empty), and the persistent caveat. This adds significant value beyond readOnlyHint and openWorldHint.

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 verbose (multiple paragraphs with details about failure modes and honesty). While informative, it could be more concise. The key purpose is front-loaded, but the length exceeds what is strictly necessary for typical 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?

The description is remarkably complete given the tool's complexity: it details all 8 optional parameters, describes the response structure (including fields and caveat), failure modes, and the open-world assumption. No gaps remain 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?

Although schema coverage is 100%, the description adds meaningful elaboration: explains cveId returns found:false with caveat, dueBefore as CISA deadline, and other filters' behavior. This provides extra clarity beyond 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?

The description clearly states the tool filters the CISA KEV catalog, distinguishing it from general CVE lookups. It specifies the resource (KEV catalog), action (filter), and unique characteristics (keyless, cached, separate host from NVD).

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 context: use when checking KEV membership, works without NVD key, and includes the critical caveat that absence from KEV does not imply safety. It doesn't list alternative tools but implies full CVEs via sibling names.

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

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

Annotations already declare readOnlyHint:true, but the description adds valuable behavioral context: it is keyless, returns specific fields like resourceId and datastoreActive, warns that datastoreActive:false resources are raw file blobs not in the datastore, and mentions the totalAvailable count. No contradictions with annotations.

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

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

The description is concise yet packed with all necessary information: purpose, inputs with examples, output format, and usage guidance. Each sentence serves a distinct purpose, and critical details are front-loaded. No extraneous content.

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

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

Given the tool's complexity (3 parameters, no output schema), the description fully covers what the tool does, how to use it, and what the returned data means (including datastoreActive flag). It provides enough context for an agent to correctly invoke the tool and interpret results without additional documentation.

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 description coverage, baseline is 3. The description adds extra value beyond the schema by providing example values for q (e.g., 'procurement'), clarifying the enum meanings for host (allowlisted .gov portals), and specifying the limit default (20) and maximum (100). It also notes 'keyless' operation, which is not 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 action: 'Find CKAN datastore resource ids by keyword via package_search (keyless).' It distinguishes itself from the sibling tool ckan_query by indicating that results should be fed to ckan_query for actual data querying. Also, specific host enums and example keywords like 'procurement' and 'checkbook' make the purpose 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 provides explicit input instructions for host, q, and limit, and advises to feed a datastoreActive:true result's resourceId to ckan_query. It implies when to use this tool (to discover datasets) and how to proceed, but does not explicitly compare with other sibling tools like socrata_discover_datasets. However, the guidance is sufficient for proper 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?

Annotations provide readOnlyHint and openWorldHint, but the description greatly expands with details on result.total behavior, total_was_estimated flag, empty vs error handling, SSRF host guard, and value typing. No contradiction with annotations.

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

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

The description is long and packed with detail, but some content is verbose and technical (e.g., 'keyless; the FIRST source on the R2 DataSource port'). It could be condensed without losing essential information. Front-loading is somewhat present with the main purpose stated first.

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?

Without an output schema, the description explains result.total and totalIsEstimated, but does not fully specify the return structure beyond value typing. It covers error cases, pagination, and limitations. Almost complete but missing explicit output field 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%, but the description adds significant meaning beyond descriptions: explains q as full-text, filters as structured object with JSON.stringify, limit cap, offset default, sort error behavior, host enum details, and resourceId format. Every parameter benefits.

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 queries rows from an allowlisted CKAN datastore resource, specifying the host and resourceId constraints, and ties to sibling ckan_discover_datasets. It distinctively focuses on CKAN government data portals, differentiating from siblings like socrata_query or cms_query_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 use for querying government CKAN data but does not explicitly state when to use vs alternatives. It mentions 'keyless; the FIRST source on the R2 DataSource port', which is not helpful for an agent. No clear when-not-to-use or alternative guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description goes far beyond: it details exact counts (typeof NUMBER, schema_drift on non-number), potential truncation (hard cap 250), phase array overlapping counts that must not be summed, and the honest caveat about registrations vs awards. It also discloses the pre-fetch validation (invalid_input) and error behavior (404/400/5xx throws). 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 dense and information-packed, with every sentence earning its place. It front-loads the core purpose (aggregate exact counts) before caveats. It could be slightly more concise by trimming redundant phrases, but for a complex tool with many caveats, this level of detail is justified. Loss of a point for slight length, but well-structured with clear sections.

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 has one array parameter with enum values fully defined in schema, and annotations cover safety and open-world hints. The description provides all essential runtime behavior: return shape, exactness guarantees, truncation, non-filterability, phase overlap, and the critical caveat about registrations vs awards. Nothing missing for an agent to call it correctly 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?

Schema description coverage is 100%, so baseline is 3. The description repeats the enum values and adds context about LeadSponsorClass being richer than the search tool's funderType, plus notes deduping and phase array arithmetic. It adds a little beyond schema but the schema already describes the fields thoroughly; it doesn't change the semantics fundamentally. 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 clearly states a specific action: aggregate exact per-value study counts over the whole ClinicalTrials.gov registry for specific enum fields. It names the API endpoint and explicitly contrasts with the search tool's funderType, distinguishing it from siblings like clinicaltrials_search_studies. The resource and scope are 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 explicitly states when to use this tool (for whole-registry counts, not award data), and when NOT to (for study counts, use clinicaltrials_search_studies; for award-based distributions, use award tools). It also exclusions: non-filterable, rejects query/filter/pageSize, and highlights that it covers registrations not federal awards. This provides clear routing against alternatives.

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

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

The description extensively discloses behavioral traits beyond the annotations: return format including found, nctId, study with briefSummary, and _meta; error handling for 404 (found:false, study:null, never fabricated); honesty about leadSponsor.name being free text and nominal matching; plus warnings about schema_drift and outage behavior. This is highly transparent and informative 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 well-structured with the purpose front-loaded. It covers parameter details, return structure, error cases, and caveats in a logical order. While slightly verbose due to extensive caveats, every sentence adds value and the conciseness is acceptable for the level of detail 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?

Given no output schema, the description fully describes the return structure (found, nctId, study, _meta) and error handling. It also addresses edge cases (nonexistent ID, schema drift, outage) and provides honesty notes. For a simple get-by-ID tool, this is comprehensive and leaves no critical gaps for agent decision-making.

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 nctId parameter with a detailed description (format, validation, return behavior). The description adds the URL path and restates some of the same information but does not provide substantial new meaning beyond what the schema already conveys. With 100% schema coverage, the baseline is 3, and the description adds only 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 starts with 'Fetch ONE clinical study by its NCT id' which clearly specifies the action (fetch) and the resource (clinical study by ID). It distinguishes from sibling tools like clinicaltrials_search_studies by focusing on a single known study. The verb-resource combination is precise and 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 usage for retrieving a single study by NCT ID but does not explicitly state when to prefer this over alternatives like clinicaltrials_search_studies. It provides clear context about ID format validation and injection safety, but lacks an explicit when-to-use or when-not-to-use statement. Baseline 4 for clear context without exclusions.

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

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

Annotations already indicate readOnlyHint and openWorldHint, and the description adds rich behavioral context: honest countTotal, opaque cursor pagination, loud-failure on bad tokens, fake-empty trap for unlisted funderType, AND-conjunctive multi-word tokens, nominal name matching, and error/outage behavior. This far exceeds what annotations convey.

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 densely packed with essential behavioral details, and it is front-loaded with the core purpose. It is structured logically (filters, returns, honesty, pagination, facet caveats, errors, routing). While not concise in length, every sentence adds value, though a bit of redundancy exists (e.g., 'LIVE-CONFIRMED to narrow' repeated), so it earns a 4.

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 having no output schema, the description fully specifies the return structure, pagination, error modes, facet semantics, and handoff to clinicaltrials_get_study. Combined with the annotations, an agent has everything needed to call this tool correctly and interpret results, including edge cases like fake-empty and overlapping facets.

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

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

Schema coverage is 100% with each parameter well-documented, so the baseline is 3. The description adds extra value by clarifying live-confirmed narrowing, funderType overlapping facet semantics and its pre-fetch rejection, and the opaque cursor behavior, which go beyond the schema. However, much of the parameter meaning is already in the schema, so a 4 reflects the added nuance without over-scoring.

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 searches federally-registered clinical-research studies with sponsor/collaborator/funding enrichment. It explicitly distinguishes itself from the sibling clinicaltrials_get_study by noting the briefSummary is excluded and to use that tool instead, making purpose and differentiation clear.

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

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

Provides explicit guidance on when to use the tool: for search with various filters, and when to hand off to clinicaltrials_get_study for full study details. It also explains pagination and error behavior, leaving no ambiguity about usage versus alternatives.

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

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

Annotations already declare readOnlyHint=true, but the description goes far beyond by disclosing honest error handling (totalAvailable from a separate stats query, never length-faked), null semantics (numeric-string → number|null, null-never-empty-string), error mapping (4xx vs 5xx vs schema_drift), and the public aggregate nature of the data. This is substantial transparency beyond the 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 long but dense and well-structured, with a clear opening sentence, input specification, output format, and honesty/error handling sections. Each sentence adds value; it is not bloated, though it could be slightly tightened. The front-loading of purpose and key constraints earns a high 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?

Given the tool's complexity (aggregate data, pagination, honesty guarantees, error handling) and the absence of an output schema, the description is remarkably complete. It covers output fields, _meta, pagination, null handling, error codes, and data vintage. 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?

Schema coverage is 100% and each parameter already has a detailed description including validation regexes and the requirement that at least one of npi/state be provided. The description adds minimal extra parameter semantics—it reiterates the input logic and mentions pagination via _meta, but does not materially enhance understanding beyond the schema. 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 ('Look up') and resource ('Medicare DMEPOS SUPPLIERS') and enumerates exactly what is returned (identity plus aggregate figures). It distinguishes itself from the sibling cms_medicare_provider_services by explicitly calling itself the 'supply-side complement', leaving no ambiguity about which tool to 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?

It clearly states the input requirement (npi OR state, at least one) and references the complementary sibling, giving the agent a direct alternative. It also includes usage cautions ('NOT a fraud/quality/fitness determination') that help the agent decide appropriateness. The guidance is explicit and actionable.

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/openWorldHint annotations: it documents exact count semantics for totalAvailable, the hasMore formula, per-dataset column coalescing, null-never-empty behavior, server-side AND filters, and precise error mapping (invalid_input, not_found, schema_drift, throws on 5xx). This gives an agent an unusually honest 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 long but tightly structured: purpose, inputs, return shape, honesty guarantees, error behavior, and caveat. It front-loads the core purpose and uses compact notation. A small amount of parameter detail repeats the input-schema descriptions, but almost every sentence carries operational value.

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

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

With no output schema and only minimal annotations, the description carries the full burden of explaining return values and edge cases. It specifies the exact response shape ({ facilities: [...] } plus _meta), pagination, coalescing rules, absent-field behavior, and failure semantics. An agent has everything needed to call this tool and interpret its 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter nuance: facilityType selects a dataset via a constant map and never enters the URL path, approximate row counts per enum value are provided, and filter semantics (EXACT state, case-insensitive substring facilityName) are reinforced. It does not fully duplicate the schema and adds operational 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?

The description opens with a specific verb and resource: 'Medicare/Medicaid-certified healthcare facilities by type' and enumerates the four facility types and returned fields. It distinguishes itself from broader CMS/socrata siblings by emphasizing the keyless datastore-query API and the four fixed datasets. The closing 'NOT a clinical-quality or fitness determination' further sharpens its scope.

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

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

The tool is clearly scoped for searching four named CMS provider datasets by facility type, and the description explicitly states what it is not for ('NOT a clinical-quality or fitness determination'). However, it does not name specific sibling alternatives or give explicit when-to-use-this-vs-that routing, so it falls short of the highest bar.

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 only declare readOnlyHint/openWorldHint, and the description adds far beyond that: keyless access, totalAvailable-vs-count honesty, overallRating/emergencyServices normalization rules, null-never-empty-string behavior, precise error taxonomy (4xx→invalid_input/not_found, 5xx→throws, schema_drift), and server-side AND-filtering. This is exceptional disclosure with no 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 long, but every clause carries operational signal: source identity, filter rules, return shape, error mapping, normalization rules, and honest-data warnings. It is dense rather than padded, though a shorter version could front-load the core lookup intent even harder.

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, 5 params, and a conditional requirement, an agent would normally be left guessing. This description specifies the exact return object shape, pagination via _meta, the error contract, and rating semantics, making the tool self-sufficient for correct invocation without any supplemental knowledge.

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 baseline is 3, but the description adds meaning the schema hides: the conditional requirement (at least one of state/facilityName despite required:0), the hospitalType-not-sufficient constraint, and EXACT vs SUBSTRING match semantics that reinforce the schema 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?

States a specific verb + resource ('Look up Medicare-certified hospitals') plus the exact dataset source (CMS Hospital Compare 'Hospital General Information', data.cms.gov provider-data API) and the returned field set. This distinguishes it from CMS siblings like cms_facility_directory and cms_medicare_provider_services 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?

Provides clear operational context: the filter contract (state OR facilityName required, hospitalType alone insufficient) tells an agent exactly the scenario this tool serves. It does not explicitly name alternatives or when-not-to-use conditions, but the context is unambiguous enough that an agent can route to it correctly.

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

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

Beyond the readOnlyHint annotation, the description discloses extensive behavioral details: the honesty policy for totalAvailable (separate stats query, null with note on failure), hasMore logic, numeric-string conversion rules (genuine 0 stays 0, absent → null), null handling for identifiers, error handling (4xx/5xx/schema_drift), and dataset vintage disclosure. This exceeds what annotations provide.

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

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

Despite its length, every sentence adds value: purpose, input requirements, optional filters, return format, honesty guarantees, and scope. The structure is logical, front-loading the core purpose and requirements before diving into details. No redundancy or 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?

With six parameters, no output schema, and no nested objects, the description compensates by fully specifying the return shape, pagination fields, error semantics, and data scope. It covers everything an agent needs to call the tool correctly and interpret results, including edge cases like genuine no-match and schema drift.

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

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

The description adds critical semantic context not in the schema: the mandatory npi-or-state constraint with rationale (9.78M rows), the exact-match requirement for providerType, and the pagination behavior via offset and size. It also explains that providerType/hcpcsCode alone cannot scope the query, which the schema does not convey.

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: retrieving Medicare Part-B provider utilization data with specific metrics (services, beneficiaries, amounts). It distinguishes itself from generic CMS data tools by naming the exact dataset and emphasizing provider-level aggregates. 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 gives explicit input requirements (npi or state required, providerType/hcpcsCode alone insufficient) and clarifies what the tool is not (fraud/quality/fitness determination). However, it does not explicitly name alternative tools or state when to prefer this over siblings like cms_query_dataset, leaving some selection inference to the agent.

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?

In addition to readOnlyHint=true, it discloses error semantics (400/404/HTML/5xx/timeout → THROW), the exact-count vs page-length-lower-bound guarantee, the 500 hard cap, no silent filter drops, SSRF validation of UUID, and the 2000-offset PII reach cap. This far exceeds what annotations alone convey.

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, with caveats grouped under ★ markers and bolded labels. It is long, but the length is earned: each sentence covers a distinct behavioral guarantee or safety policy needed for correct 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 supplies the return shape ({datasetId, index, results, fields, rows, _meta}), explains both modes, covers errors, pagination, and policy caps, and disambiguates count semantics. The only minor omission is a detailed _meta field breakdown, which is not essential for calling 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?

Despite 100% schema coverage, the description enriches every key parameter: datasetId's UUID grammar is framed as the SSRF guard, offset is tied to the PII reach cap, limit to the hard API cap, results to a discovery mode, and conditions to server-side self-policing with bad-column errors. This goes well beyond the schema descriptions.

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

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

The first sentence names a specific verb ('Query'), a resource ('CMS Open Payments DKAN datastore distribution'), and the key identifiers ('datasetId + index'), and names the data source (keyless; openpaymentsdata.cms.gov). It clearly distinguishes this from discovery siblings like cms_search_datasets and socrata_query by being a datastore-level query, not a dataset 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?

The description asserts when it is appropriate ('targeted vetting') and explicitly what it is NOT ('NO enrichment', 'NOT a conflict-of-interest / fitness / exclusion determination'), directing users to 'cross-check SAM + OFAC + OIG-LEIE'. It does not explicitly name a sibling discovery tool for finding datasetId, so it misses the explicit-alternative bar.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description richly discloses behavior: totalAvailable comes from a separate stats sub-query and never the returned-rows length, name coalesces ORG_NAME over FIRST_NAME+LAST_NAME, NPI/reasons/dates are null-never-empty, no-match returns an honest empty result, 4xx/5xx/200-non-array cases are mapped, and the tool is keyless. This goes far beyond 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?

Although dense, the description is well-structured and front-loaded: purpose, source, parameter semantics, return shape, honesty guarantees, and error behavior each earn their place. No filler is present, and the detail is justified by the absence of an output schema and the need to convey non-obvious pagination and null-handling 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?

With no output schema, the description fully compensates by specifying the exact returned fields, the _meta behavior, error handling conventions, paging semantics, and data source. An agent has everything needed to select and invoke the tool correctly without consulting external documentation.

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 schema already documents all five parameters, but the description adds operational meaning: all inputs are optional, the small row count makes unfiltered paging safe, state and lastName are exact matches, and offset pagination is tied to _meta.pagination.nextOffset. This adds actionable guidance beyond bare schema descriptions.

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

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

The description opens with the specific verb 'Search' and names the exact resource: CMS's public 'Revoked Medicare Providers & Suppliers' list. It further distinguishes the tool from adjacent vetting sources by calling it 'a vetting lane in the same class as OFAC / SAM-exclusions lists' and clarifying it is CMS's public revocation register.

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 clear use context: this is for CMS revocation vetting, is keyless, and is safe to page unfiltered because the full list is only ~7,059 rows. It also sets a boundary by stating it is 'NOT a current-eligibility, guilt, or fitness determination,' which helps agents avoid overinterpreting results, though it stops short of explicitly naming when to choose it over specific 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?

The description adds significant behavioral details beyond readOnlyHint annotation: the DKAN metastore ignores server pagination, applies client-side, throws on errors, and never fabricates empty results. This honesty adds value.

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 verbose but well-structured, front-loading purpose and return format, then usage, then caveats. It could be slightly more concise but every sentence adds necessary info.

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 no output schema, the description adequately covers return structure, behavior, edge cases, and links to cms_query_dataset. It also explains the honesty mechanism, making it complete for the task.

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 documented in the input schema (100% coverage). The description adds context about client-side application and the exactness of totalAvailable, enhancing understanding.

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 discovers CMS Open Payments datasets on the DKAN metastore, specifies the return format, and distinguishes from cms_query_dataset by explaining how to use 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?

The description provides usage guidance, such as feeding datasetId and distribution index to cms_query_dataset, and notes the client-side pagination behavior. However, it lacks explicit when-not-to-use or comparison with other 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?

Annotations already provide readOnlyHint=true and openWorldHint=true. The description adds valuable context: it specifies the exact API endpoint, the requirement for an API key, the return structure ('{ bill:{…} } + single-record _meta'), and that nonexistent bills result in 'not_found' without fabrication. 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 three sentences. First sentence states the core action and endpoint. Second lists the parameters. Third describes the return shape and error behavior. No unnecessary words, front-loaded, 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 the tool's simplicity (3 required params, no output schema), the description covers everything needed: what it does, how to call it, parameter names, return structure, error case, and auth requirement. It is fully sufficient for an AI agent to select and 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?

Input schema covers all parameters with full descriptions (enum values for billType, examples for congress and billNumber). Description restates parameter types and connects them to the URL pattern, but does not add new semantics beyond the schema. Baseline score for 100% coverage 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 'Fetch ONE Congress.gov bill by id via /v3/bill/{congress}/{billType}/{billNumber}'. It specifies the action (Fetch), the resource (Congress.gov bill), and the exact endpoint. This distinguishes it from sibling tools like congress_search_bills, which is for searching.

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 the API key requirement ('DATA_GOV_API_KEY or DEMO_KEY') and the error behavior for nonexistent bills. It does not explicitly state when to use this vs. alternatives, but the context of fetching by ID vs. searching in congress_search_bills is clear. No exclusions or when-not-to-use are given, but it's sufficient.

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

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

Beyond annotations (readOnlyHint, openWorldHint), the description adds key behavioral details: API key requirement, that outages/4xx throw errors (never fake empty), and that query parameter is dropped. No contradictions with annotations.

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

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

The description is dense with information but remains single-paragraph and front-loaded with the main purpose. While efficient, a bit more structure (e.g., bullet points) could improve readability, but it is not overly long.

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 no output schema, the description thoroughly details the return format (bills array with fields + meta with totalAvailable) and error behavior (throws on outage/4xx). Also covers all parameters, key requirement, and pagination. Complete for a search tool.

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

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

Schema coverage is 100%, but the description adds significant value beyond schema: explains query is not applied, billType requires congress, ISO-8601 date format examples, limit max 250, default 20, and return structure. This fully compensates and enhances understanding.

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 is for searching Congress.gov BILLS/legislation, specifying the resource (bills) and action (search). It also distinguishes from potential siblings (like congress_get_bill) by focusing on list/search functionality and noting limitations like no keyword 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?

The description provides guidance on parameter usage, such as requiring congress for billType, explaining that query is not applied and suggesting alternatives (congress/billType/date filters). However, it does not explicitly mention when to use sibling tools like congress_get_bill for single bills.

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?

Extremely rich behavioral disclosure well beyond annotations: opaque cursor pagination semantics (nextCursor:null/hasMore:false = last page), count stopping on deep pages with honest null disclosure, dateFiled as string, citation flattening, null handling for absent fields, error mapping (400→invalid_input, 429→rate_limited with Retry-After, 5xx throws, schema_drift on 200 non-JSON), and SSRF refusal for off-host 'next'. Annotations (readOnlyHint=true) are consistent and the description adds far more 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 long but every section earns its place: purpose, provenance, filter list, return shape, and honesty guarantees. It is front-loaded with the purpose and provenance before technical details. The density of unique information justifies the length, though it could be trimmed slightly without losing value.

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

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

Exceptionally complete for a complex 7-param, cursor-paginated tool with no output schema. The description explicitly defines the return object shape ({ opinions:[...] } with all fields), the _meta structure, error semantics, and rate limiting. An agent has everything needed to call it correctly and interpret results without opening external docs.

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 schema already documents all 7 parameters. The description adds value by explaining the mapping of natureOfSuit being folded into q (no verified dedicated filter), cursor as opaque continuation tied to _meta.nextCursor, and order defaulting to 'dateFiled desc' — meaning beyond bare schema descriptions. Minor deduction because some param detail repeats schema content.

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 ('Search US federal court opinions via CourtListener') with a URL, endpoint, and type. The provenance disclosure (Free Law Project, non-profit, NOT .gov, PACER paywalled) clearly differentiates it from any other search tool and from government API siblings.

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

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

Provides clear context on when this is appropriate: it covers US federal court opinions, discloses that the primary .gov source (PACER) is paywalled and that CourtListener is the keyless alternative. It explains token usage raises the rate limit. It doesn't name a specific sibling alternative for exclusion, but given no sibling does the same job, the guidance is sufficient.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses an exceptional behavioral contract: the CPSC response is a bare array with no count field and no pagination, so totalAvailable always equals the number of returned recalls and complete:true is never fabricated; a default ~90-day window applies when no filter is given; empty results are honest empties not errors; 4xx maps to invalid_input, 5xx/timeout throws, and 200 non-JSON/non-array maps to schema_drift; normalization rules (flattened arrays, NumberOfUnits as string, null-never-empty-string) are specified. This fully arms an agent against misinterpreting the response.

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

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

The description is dense (~200 words) but every sentence carries information: purpose, auth stance, sibling routing, inputs, return shape, honesty contract, error mappings, and normalization. The ALL-CAPS markers (KEYLESS, HONESTY) break the wall of text into scannable segments. It loses one point because the HONESTY sentence is a long run-on packing several distinct behaviors into one clause chain, but nothing is wasted.

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

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

With no output schema, the description fully specifies the return shape including every recall field and the honest _meta object. It also covers the quirky API contract (no pagination, no count, default window, error taxonomy, input validation rules) that an agent could not infer otherwise. The read-only safety profile is handled by annotations. Nothing an agent needs to call this tool correctly or interpret its result is left unsaid.

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% — every parameter already carries a description, example, and validation regex, so the schema does the heavy lifting. The description adds only marginal value: the 'ALL optional' note and a prose restatement of the date/substring filter semantics already present in the schema. Baseline 3 is appropriate under 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?

The description opens with a specific verb-resource pair, 'Look up U.S. CPSC consumer-product RECALLS', and enumerates the exact content covered (hazard description, remedy, affected products, manufacturers, retailers, injuries, country of manufacture). It also names the nearest confusable siblings (nhtsa_recalls for vehicles, openfda_enforcement) so an agent can distinguish this tool without opening their schemas.

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

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

The sibling list with parenthetical scopes ('nhtsa_recalls (vehicles)', 'openfda_enforcement') gives a clear routing signal: consumer-product recalls go here, vehicle recalls and FDA enforcement go to the named alternatives. It also states that all inputs are optional and discloses the default 90-day window when no filter is given. The exclusions are implied through sibling hints rather than explicit 'use X instead when...' prose, which keeps this just shy 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?

Annotations only say readOnlyHint=true and openWorldHint=true; the description carries a huge amount of behavioral disclosure: CVSS version-conflation rules, primaryCvss fallback behavior, KEV degradation to null, kevOnly throwing during KEV outage, NVD-exact pagination, honest found:false, rate-limit/403/429 throws, and API-key header behavior. This far exceeds what annotations provide and never contradicts them.

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

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

Although long, the description is extremely dense and structured: purpose and modes first, then return shape, then explicit honesty guarantees, pagination, errors, and auth. Every sentence conveys a distinct operational fact; the length is justified by the tool's 11-parameter complexity and no output schema.

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

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

For a tool with no output schema, the description is exceptionally complete: it specifies the full return object, error behavior, rate-limit handling, degraded KEV semantics, pagination source, and auth protocol. An agent has enough context to select the tool, construct valid parameters, and anticipate 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?

Schema coverage is 100%, which sets a baseline of 3, but the description adds substantial semantics beyond the schema: kevOnly's throw-on-outage behavior, resultsPerPage over-cap refusal rather than clamping, startIndex pagination from NVD exact totalResults, date-window pairing/clamping, keyword sanitization, and cveId validation. These are meaningful behavioral additions to all major parameters.

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

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

The description opens with a specific verb and resource: 'Look up NIST NVD CVE records' via the NVD CVE API 2.0. It clearly narrows the scope to exact-by-cveId or search-by-keyword/cpeName/severity/date-range modes, and emphasizes the distinct CISA KEV join, which separates it from the sibling cisa_kev_lookup.

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 strong usage context: exact lookup versus keyword/CPE/severity/date-range search, plus optional kevOnly and pagination. It does not explicitly name alternative sibling tools or say when NOT to use this tool versus cisa_kev_lookup, so it falls just short of the 5-level explicit when/when-not guidance.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that totalAvailable is always NULL, pagination is opaque cursor, error cases (429, 5xx, non-JSON) throw specific errors, and the API key is sent only in headers. This provides deep behavioral transparency.

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 well-structured with clear sections (e.g., HONESTY, error conditions). It is front-loaded with the main purpose. While verbose, the length is justified by the complexity and transparency needs.

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 no output schema, the description thoroughly documents return values, error behaviors, pagination details, and authentication. It covers all necessary context for an agent to use the tool correctly without additional information.

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

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

Schema coverage is 100%, but the description adds valuable context: for 'query' it confirms the mapping to 'q' and notes that '_q' is ignored; for 'cursor' it explains opaque token usage; for 'organization' it describes slug filtering. This exceeds what the schema alone 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?

The description clearly states the tool searches the data.gov DATASET CATALOG for federal open datasets. It specifies the verb 'search', the resource 'data.gov', and distinguishes it from sibling tools like ckan_discover_datasets by noting it is the replacement for the retired CKAN endpoint.

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 this tool (as the successor to the retired CKAN endpoint) and provides context on API key limits (DEMO_KEY vs. dedicated key). It does not explicitly list exclusions, but the 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?

Annotations only declare readOnlyHint=true and openWorldHint=true, so the description carries the behavioral burden — and it delivers richly: full error taxonomy (401/403→invalid_input with key guidance, 429→rate_limited THROWS honoring Retry-After, 5xx→upstream_unavailable, 200 non-JSON→schema_drift), the verbatim-data honesty policy (genuine 0 stays 0, missing stays null), and the guarantee that `returned` is never passed off as `totalAvailable`. It even specifies key transport (X-API-KEY header only, never URL/_meta).

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 it is front-loaded (purpose first, then the critical auth requirement) and every sentence carries operational information — error mapping, pagination semantics, honesty guarantees — rather than filler. The repeated 'honest/honesty' emphasis is stylistically redundant across several sentences, which costs it the top score, but nothing here is wasted.

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

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

With no output schema, the description fully specifies the return contract: { records: […] verbatim rows }, honest _meta with the totalAvailable-null-if-unknown rule, and hasMore semantics for paging forward. All failure modes, the auth requirement, and the keyless alternative are covered. Given the tool's complexity (7 params, external API, auth, multiple error classes), nothing an agent needs to call it correctly is left to guesswork.

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 input schema already documents all 7 parameters, including the paired filterField/filterValue constraint and the regex validation. The description adds marginal value beyond this — mainly that parameters 'ride the PATH' and that inputs derive from dol_list_datasets fields — but most of its parameter text mirrors what the schema already states, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource pair — 'Fetch records from ONE US DOL dataset' — and pinpoints the endpoint shape (/v4/get/{agency}/{endpoint}/json). It also names the keyless sibling dol_list_datasets inside the description, so an agent can immediately tell this is the data-fetching tool as opposed to the dataset-discovery one.

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 key precondition is stated explicitly and without ambiguity: 'REQUIRES a free DOL_API_KEY... the DOL DATA endpoint has NO keyless tier,' with a registration URL and the note that 'dol_list_datasets stays keyless.' It also tells the agent exactly where its inputs come from (agencyAbbr and apiUrl from dol_list_datasets), giving clear when-to-use and dependency 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?

Discloses client-side filtering, throws on 5xx, handles schema drift, explains pagination and totalAvailable behavior. Adds value beyond readOnlyHint and openWorldHint annotations with honest verification.

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-organized with core purpose first, then details, return format, and error handling. Slightly verbose but every sentence provides unique value; minor redundancy possible.

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?

Covers all essential aspects: input, filtering behavior, return structure, pagination, error modes, and connection to sibling tool. No output schema, but return format is documented inline.

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?

Enriches every parameter beyond schema descriptions: default/max for limit, examples for query, client-side nature for agency, pagination hint for offset. Coverage is 100% and description adds concrete, actionable detail.

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 it lists the DOL Data API v4 dataset catalog, identifies it as the machine inventory of enforcement/statistics datasets, and distinguishes itself from dol_get_dataset by noting keyless access.

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

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

Explicitly describes when to use (catalog listing) and how to connect results to dol_get_dataset. Implicitly excludes other tools through sibling context, but lacks explicit 'when not to use' statements.

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?

Discloses data source authenticity (de-XMLed, no fabrication), error modes (not_found, invalid_input, throws on outage), and issue date disclosure. Annotations already provide readOnly and openWorld hints, but description adds valuable 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?

Description is front-loaded with core purpose but contains multiple examples and error conditions. A bit lengthy but every sentence adds value. Slightly above average conciseness.

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, but description explicitly states return fields (citation, alternateReference, heading, fullText, issueDate, ecfrUrl). Covers error cases. Complete for a single-section retrieval 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 has 100% description coverage, and description adds examples (e.g., '200.1' for grants, '52.204-21' for FAR), context for titleNumber (2=grants, 29=Labor), and date format validation. Adds meaning beyond schema.

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

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

The description uses specific verb 'Get' and resource 'FULL in-force text of ONE CFR section by citation.' It distinguishes itself from siblings ecfr_search (snippets) and far_clause_lookup (title 48).

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

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

Explicitly states when to use (other 49 titles) and when not (FAR/DFARS prefer far_clause_lookup). Also explains optional date parameter default behavior.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, which cover the safety profile. The description adds that the tool returns names and last_amended_on dates, providing modest context beyond the annotations, but no additional behavioral traits like rate limits or data freshness.

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

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

Two sentences that front-load the purpose and efficiently convey the value. Every word earns its place, with no 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?

Despite having no output schema, the description explicitly states the return fields (name and last_amended_on). For a simple list-all tool, this is sufficient context. The tool's behavior is straightforward and the description covers the essentials.

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 with 100% schema coverage. Baseline for no parameters is 4, and the description does not need to add parameter details. It correctly omits any parameter explanations.

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 ('List'), resource ('all 50 CFR titles'), and includes the data fields returned (name + last_amended_on date). It clearly distinguishes from sibling tools like ecfr_search and ecfr_get_section by focusing on listing titles rather than searching within them.

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

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

The description explicitly says 'Use to discover what's in each title' and provides examples, indicating the tool is for initial exploration. It does not explicitly state when not to use it, but the context excludes the need for deeper search, which is handled by siblings.

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

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

Annotations already indicate readOnlyHint and openWorldHint. The description adds useful behavioral context: it returns a ranked EXCERPT (not full text), section path, and ecfrUrl. It does not contradict annotations and provides additional details about the output format.

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, front-loaded with the main purpose, and each sentence adds value. 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?

Given no output schema, the description explains the return structure (excerpt, section path, ecfrUrl). It also links to sibling tools for next steps. However, it does not mention pagination or perPage behavior, which is a minor gap.

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

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

Schema description coverage is 33% (only titleNumber has a description). The description adds value by explaining titleNumber usage with examples (48 for FAR, 2 for financial assistance), but for query and perPage it provides no additional meaning beyond the schema's property definitions.

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

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

The description clearly states 'Full-text search across the entire CFR' with specific examples (titleNumber=48 for FAR, titleNumber=2 for financial assistance). It distinguishes itself from sibling tools like far_clause_lookup and ecfr_get_section by emphasizing it returns excerpts for discovery.

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

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

The description explicitly says 'Use for DISCOVERY' and provides clear instructions for what to do after getting a hit: use far_clause_lookup for FAR/DFARS clauses, ecfr_get_section for other titles, or open the ecfrUrl. This gives excellent guidance on when to use this tool versus alternatives.

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

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

Annotations already signal readOnlyHint=true and openWorldHint=true, and the description adds meaningful behavioral detail: keyless access, accepted ID formats, exact return shape (registryId + report + _meta with complete:true and no pagination), and a clear not_found error guarantee with no fabricated reports. This goes well beyond structured fields.

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

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

The description is dense but well-structured: purpose, input requirement, return shape, and error behavior are covered in four purposeful sentences. Every sentence earns its place, and the most decision-relevant details (single facility, RegistryID, not_found guarantee) are front-loaded.

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

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

Despite no output schema, the description specifies the return envelope, the verbatim report content, metadata behavior, pagination absence, and error semantics. For a single-parameter tool with full schema coverage enough context is provided for an agent to invoke it correctly 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?

Schema description coverage is 100%, so the baseline is 3. The parameter semantics are fully captured in the schema, and the description repeats the same format constraints and error behavior without adding materially new information about the parameter beyond what the schema already 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?

The description uses a specific verb ('Fetch') and resource ('EPA ECHO Detailed Facility Report') for exactly one facility by RegistryID. It clearly frames the report as a compliance/enforcement/inspection/permit deep-dive, distinguishing it from the sibling echo_search_facilities which is for discovery rather than report retrieval.

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

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

It states the tool is for one facility and explicitly ties the input to values 'exactly as returned by echo_search_facilities rows', which implies search-then-report workflow. It does not name an alternative explicitly, but the sibling relationship and one-facility scope provide adequate usage context.

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

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

Beyond annotations (readOnlyHint, openWorldHint), the description discloses many behavioral traits: two-step pagination with ephemeral QueryID, honest totalAvailable (not page size), error handling (invalid inputs throw, outages throw, never fake empty), and the fact that naics filter is dropped upstream. 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 quite long but densely packed with useful information. It is front-loaded with the main purpose. Could be slightly more structured (e.g., bullet points for parameters) but remains clear and efficient given the complexity.

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 (8 params, one required, special pagination, error modes, relationship to another tool), the description is remarkably complete. It covers return structure (state, facilities, summary, _meta), honesty guarantees, and all edge cases. No output schema, but description compensates by outlining the response fields.

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

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

Schema coverage is 100%, but description adds significant context: state enum is also SSRF/silent-zero guard; offset must be multiple of limit; facilityName typo silent zero; naics is best-effort and dropped; majorOnly/federalOnly are straightforward. Description enriches understanding far beyond 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?

The description clearly states the tool's function: searching EPA-regulated facilities by US state with compliance/enforcement fields. It specifies the main resource (facilities) and action (search), and distinguishes it from sibling echo_facility_report by mentioning that tool as a follow-up.

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 guidance: state is required and also serves as SSRF guard; sic is a real filter while naics is best-effort and may be dropped; facilityName typos silently return 0; pagination details (limit/offset multiples, max 1000); and mentions feeding results to echo_facility_report for more detail.

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 only declare readOnlyHint and openWorldHint; the description carries a heavy load and exceeds it. It discloses the (start,end)-pair period identity rule, the canonicalOnly dedupe that is 'fully disclosed, never a silent drop', 'val is null-never-0', 'NEVER fabricated val:0' on 404, throw-on-shape-drift, and the CIK-not-SAM-UEI caveat. This is model-grade transparency about failure modes and data semantics.

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?

Dense but justified for a 9-parameter tool with no output schema; the return shape is compactly inlined and the honesty notes are organized under a labeled 'HONESTY M1' marker. It front-loads purpose and differentiators before details. Slightly over-stuffed — the error-semantics section could be trimmed — but every sentence earns its place given the complexity.

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?

Remarkably complete for a tool with no output schema: it inlines the full return object shape, enumerates error classes (404 vs 5xx vs non-JSON/shape-drift vs missing unit), documents pagination semantics (limit/offset are client-side over a fully-fetched series; SEC does not paginate), and warns about the CIK↔UEI gap. Nothing an agent needs to call it correctly or interpret results is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description genuinely adds meaning: it flags which parameters are CLIENT-SIDE versus path segments (unit, form, fy, limit/offset), explains canonicalOnly's dedupe key (unit,start,end), and links unit semantics to the disclosed-units behavior. The description reinforces and extends the schema rather than merely repeating it — though the schema itself is already unusually rich, so the marginal gain is modest.

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 crisp triple: 'One filer × one XBRL concept × complete reported time-series' — a specific verb-less but precisely scoped resource statement. It then names both sibling tools and the exact axis that differentiates them ('Sits between edgar_company_facts (many concepts, one filer) and edgar_xbrl_frames (one concept, all filers)'). An agent can disambiguate immediately without opening 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?

Explicitly positions the tool relative to its two nearest siblings and enumerates the input contract (cikOrTicker, concept, optional taxonomy/unit/canonicalOnly/limit/offset). It also states when NOT to expect success — bad CIK/taxonomy/concept yields 404→found:false, unit-not-present yields honest empty — which tells the agent how to interpret outcomes and when to route elsewhere.

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 annotations (readOnlyHint, openWorldHint), the description adds critical behavioral details: missing concepts are omitted (never 0), and concepts available only in non-default units are reported under wrongUnit with a note. Also notes keyless access.

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

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

Two sentences, front-loaded with purpose and key parameters, then edge-case behaviors. No redundant information, making it highly efficient.

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

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

Covers inputs, defaults, and edge cases well. Missing explicit description of output structure (though openWorldHint implies flexible response). With no output schema, a brief note on return format would improve completeness.

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

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

Schema coverage is 100%, but the description adds value by listing the default 6 curated concepts and explaining edge cases for unit mismatches and absent concepts, which are not in the schema. This goes beyond the schema descriptions.

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

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

The description clearly states it provides curated XBRL financial facts for a filer, specifying the data source (data.sec.gov companyfacts) and key parameters. It distinguishes from sibling tools like edgar_company_concept (single concept) and edgar_xbrl_frames (aggregated frames) by focusing on multiple concepts with defaults.

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

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

The description implies usage for retrieving multiple financial facts with optional customization, but does not explicitly compare to sibling tools like edgar_company_concept or edgar_company_filings. No guidance on when not to use it or prerequisites, leaving the agent to infer use 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?

The description goes well beyond the annotations (readOnlyHint, openWorldHint) by detailing the fullHistory mechanics, shard fetching, honesty in totalAvailable (recent + all shard counts), cap/failure disclosure (PARTIAL-BY-CAP, PARTIAL-BY-FAILURE), and the shared EDGAR throttle gate. No contradictions with annotations.

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

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

The description is dense but efficient, with no wasted words. It front-loads the purpose and input summary, then adds behavioral notes. However, it could benefit from minor structuring (e.g., listing parameters) to improve scanability for an agent.