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?

Goes far beyond the readOnlyHint and openWorldHint annotations by detailing honesty measures (count behavior, date epoch handling, no-match responses, error surfacing, schema drift detection, SSRF protection). Comprehensive 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?

Well-structured with sections and front-loaded with purpose. Somewhat verbose but every sentence adds value; could be slightly 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?

Given 6 parameters, 23 services, pagination, and no output schema, the description is remarkably complete: covers return structure, pagination mechanics, date field caveats, error cases, and SSRF protections. No 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?

Adds substantial meaning beyond the 100% schema coverage: explains service enum values in detail, provides example where clauses, clarifies pagination with limit/offset and _meta field, and describes output format.

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

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

Clearly states 'Query rows from a curated US-government ArcGIS REST feature layer' and distinguishes itself as the QUERY companion to arcgis_hub_discover_datasets. Provides specific layer examples and context.

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 names the sibling tool arcgis_hub_discover_datasets and frames this tool as its query counterpart. Describes the data domain (SLED procurement/GIS) but does not provide explicit when-not-to-use scenarios or other 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 provide readOnlyHint and openWorldHint. The description adds extensive behavioral details: provenance (global, non-governmental), honesty about pagination, null handling, error conditions (429, 5xx, non-JSON). 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 and well-structured with sections (provenance, honesty), but it is verbose. However, given the complexity of the tool and the need for trust posture clarification, the depth is justified. Could be slightly trimmed 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?

Despite lacking an output schema, the description fully documents the return structure (datasets fields, _meta) and covers error handling, pagination, and trust posture. This provides complete guidance for agent invocation and interpretation.

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

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

Schema coverage is 100%. The description adds significant value beyond the schema by explaining the query constraint (≥2 chars), default behavior for openDataOnly, limit range, offset mapping to page[start], and the meaning of each parameter in API terms (→ q, filter[openData]).

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: 'Discover ArcGIS Hub datasets by keyword' and distinguishes it from sibling tools like Socrata and CKAN by specifying the coverage gap. It provides a specific verb and resource, making it easy for an agent to understand what it 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 defines when to use this tool (for ArcGIS Hub data not covered by others) and when not (global platform, not curated; mentions a planned row-query tool). It contrasts with socrata_query and gives clear prerequisites (query required, min length).

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

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

The description is exceptionally transparent: it discloses that missing/invalid keys produce HTTP 200 with Error object (not HTTP error), explains data parsing of comma-formatted strings, maps suppression codes to null, and clarifies that unitMult is not applied. All this goes well beyond the readOnlyHint and openWorldHint annotations.

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

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

The description is dense and informative, but slightly long. It is front-loaded with purpose and key requirement. A more structured format (e.g., bullet points for parameters) could improve readability, but the current prose is efficient and every sentence adds 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?

Despite lacking an output schema, the description fully specifies the return format ({ rows:[...], notes:[...] }) and edge cases (empty result, 5xx, non-JSON response). It covers authentication, error handling, and data interpretation, making it complete for a complex API 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%, and the description adds significant meaning: examples of tableName ('CAGDP2', 'SAGDP2N'), geoFips ('STATE', '06075'), lineCode (integer or 'ALL'), year ('LAST5', '2022'), frequency ('A', 'Q'). It also explains the response fields, which is not present in the schema.

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

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

The description clearly states the tool returns regional economic data (GDP, personal income) from the BEA. It distinguishes itself from sibling tools by specifying the exact data source and API. Even without explicit comparison, the purpose is unambiguous and complete.

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

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

The description provides explicit usage context: requires BEA_API_KEY, explains key requirement, parameter details, and error handling. It does not explicitly state when not to use the tool, but the specificity of the domain (BEA regional data) makes misuse unlikely.

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 indicate readOnlyHint and openWorldHint, but the description goes far beyond with a HONESTY section (H1-H4) detailing yearly snapshots, null handling for missing/suppressed data, no fabricated zeros, proper unit labeling, and error handling. This fully discloses the tool's behavioral traits.

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

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

The description is well-structured with clear sections (purpose, input details, HONESTY), but is quite lengthy. Some redundancy exists (e.g., area validation mentioned in both description and schema). However, every sentence adds value and the key info is front-loaded.

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

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

Given the tool's complexity (4 params, no output schema), the description covers all necessary context: input validation, batch behavior, caps, error handling, output format, and relationship to siblings. It leaves no significant gaps for an AI agent.

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

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

Schema coverage is 100%, but the description adds critical semantics: the curated occupation enum with SOC mappings, SOC hyphen constraint, area formats (national/state/metro), datatype meanings, batch processing, and caps. This greatly enriches 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 benchmarks US occupational wages and employment from BLS OEWS, distinguishing it from sibling tools like gsa_benchmark_labor_rates and bls_timeseries. It specifies the data source, methodology, and purpose.

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

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

The description provides explicit guidance on when to use the tool (labor-rate benchmarking), names alternatives (gsa_benchmark_labor_rates, etc.), explains input requirements (at least one of occupation/soc), batch behavior, and caps. It also warns against common mistakes like using hyphens in SOC codes.

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 and openWorldHint annotations, detailing disclosure-suppression behavior (null vs 0), honesty measures (totalAvailable, HTTP 404 handling, schema drift protection), and the mixing of aggregation levels. 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 very long (multiple paragraphs) and includes extensive detail. While well-structured with bullet points and sections, it could be more concise for an AI agent. The length is justified by the API complexity but still reduces 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?

Given the tool's complexity (10 parameters, no output schema), the description is highly complete. It explains the output structure, disclosure codes, error handling, and client-side pagination, leaving no critical gaps in understanding.

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

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

Schema coverage is 100% and the description adds substantial context: format constraints (regex for area_fips, digit-only NAICS), that mode is a literal path segment, client-side pagination semantics for limit/offset, and the effect of hyphenated NAICS. This clarifies usage 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 retrieves BLS QCEW data (market size, employment, wages, location quotient) and distinguishes it from the rate-limited bls_timeseries API. It specifies the resource and the unique value proposition (un-rate-limited, keyless).

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 provides when to use this tool (market-size/competition-density questions) and contrasts it with alternatives. It details required parameters (mode, year, quarter) and conditional parameters (area/industry), warns about hyphenated NAICS causing 404s, and explains client-side filters.

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 readOnlyHint and openWorldHint annotations: it details the API method (POST/JSON batch), keyless vs. keyed access, rate limits (v1 ~25/day, v2 ~500/day), data gap handling (null for unavailable, never 0), error throwing for non-success statuses, and tier disclosure. 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 thorough and well-structured, with purpose front-loaded. While slightly verbose, every sentence serves a purpose (explaining usage, nuances, error handling). Minor redundancy could be trimmed, but overall high 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?

Given no output schema, the description fully explains the return format (series array with fields, observations with valueUnavailable, footnotes, etc.), covers edge cases (empty data, ambiguous raw IDs, error scenarios), and discloses tier information. It is complete for the tool's complexity.

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

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

With 100% schema description coverage, the description adds significant meaning: it explains each enum value's meaning and units, warns that eci_total_comp/eci_wages are 12-month percent changes (not indices), clarifies raw seriesId charclass and behavior, and details startYear/endYear defaults and clamping.

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

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

The description clearly states the tool fetches BLS time series for pricing/escalation, with specific examples like CPI-U, PPI, ECI. It distinguishes from sibling tools such as gsa_benchmark_labor_rates and sam wage determinations, providing clear context for use.

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

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

The description provides explicit when-to-use guidance: for federal contract escalation, EPA clauses, materials pricing, labor-rate context. It names alternatives (gsa_benchmark_labor_rates, sam wage determinations) and specifies input requirements (at least one of series/seriesId required, both combinable).

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

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

The description goes beyond annotations (readOnlyHint, openWorldHint) by disclosing that the data is a curated, partial seed of 187 orgs, that the authoritative directory is auth-gated, and that the seed may be incomplete. It also describes the output format and pagination mechanism, providing full transparency about limitations and 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 moderately concise, front-loading the purpose and then providing necessary detail. It could be slightly shorter, but every sentence serves a purpose (context, filtering, output, honesty note). Structure is logical with use cases and limitations clearly separated.

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

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

Given there is no output schema, the description thoroughly defines the output format including the fields and pagination metadata. It also addresses the tool's limitations and provides instructions for extending the seed. The 4 parameters are fully explained in context. The description is complete for effective agent use.

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

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

While the schema already describes each parameter (100% coverage), the description adds usage semantics: it clarifies that filters are applied client-side on the curated seed, specifies the range for limit, and mentions offset's relationship with pagination metadata. This adds practical meaning beyond the structural 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 explicitly states the tool lists US governments on the Bonfire platform and identifies itself as the directory for bonfire_search_opportunities. It uses a specific verb ('List'), a clear resource ('US governments on Bonfire'), and distinguishes from the sibling tool bonfire_search_opportunities by explaining the relationship.

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

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

The description provides clear usage context: 'Feed a result's `org` to bonfire_search_opportunities' indicates when to use this tool first. It also explains that Bonfire has no keyless API, so this curated seed is the recommended starting point, and suggests an alternative method to extend the seed. This covers when to use and when not to rely solely on the tool.

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

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

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?

The description goes far beyond the annotations (readOnly, openWorld) by detailing suppressed data handling (negative sentinels map to null), error behavior (missing key → invalid_input, 5xx → throws), return format, and pagination (complete results). This adds substantial context for safe usage.

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 well-structured: purpose first, then key requirement, parameters, return format, honesty notes, error cases. While slightly long, every sentence contributes value. Front-loading the main purpose makes it 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?

Given the complexity (5 params, no output schema), the description is remarkably complete. It covers return structure, suppression behavior, error modes, key requirement, and pagination. Nothing essential is missing for a data query tool with readOnly and openWorld hints.

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 5 parameters have schema descriptions (100% coverage), and the description adds significant extra meaning: explains defaults (year='2023'), validations (naics ^\d{2,6}$), required combinations (state for county), and the client-side nature of limit. This enhances the schema's information.

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

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

The description clearly states the tool's purpose: 'Market sizing by NAICS × geography — establishments, employment, and annual payroll from the US Census County Business Patterns (CBP) API'. It identifies the specific resource, verb, and dimensions, distinguishing it from sibling tools like geocoding or FRED queries.

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?

Explicit guidance is provided: requires a free CENSUS_API_KEY, parameters are explained (naics, geography, state, year, limit), and it instructs users to call api_key_status to check key requirements. It also clarifies when not to use (e.g., no key throws error) and mentions alternatives implicitly by focusing on this dataset.

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 details genuine empty returns, multiple matches, historical vintage behavior, HTTP 400 throws, and mandatory caveats. 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?

Well-structured with front-loaded purpose, parameter details, return shape, edge cases, and caveats. Slightly long but every sentence adds value; could be slightly more organized.

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

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

No output schema, but description fully covers return structure (matches with fields) and all behavioral aspects. Thoroughly compensates for missing schema given tool complexity.

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

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

Adds meaning beyond schema: examples for address, explains default/compatibility matrix for vintage and benchmark, behavior for incompatible pairs. Schema coverage is 100% but description enriches 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 resolves a one-line US address to matched addresses and Census geographies for set-aside/place-of-performance analysis. It specifies the domain and distinguishes itself from siblings, none of which are geocoding 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?

Explicitly tells when to use (resolving addresses for geographies) and when not (not authoritative for HUBZone/OZ determinations, requires SBA map/Treasury list). Provides guidance on handling empty results, multiple matches, and invalid inputs.

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?

The description goes far beyond the annotations (readOnlyHint, openWorldHint) by detailing honesty checks (typeof validation, schema drift), the truncated invariant, overlapping behavior for Phase, missingStudiesCount caveat, error handling (invalid_input pre-fetch, throws for 4xx/5xx), and mandatory caveats. All disclosed behaviors are consistent with the annotations.

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

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

The description is comprehensive but long (over 500 words), making it somewhat verbose. However, it is well-structured with a clear hierarchy: purpose, input/output, honesty, error handling, caveats. The front-loading of the main purpose and key distinctions helps agents quickly grasp the tool's role.

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 the tool and the lack of an output schema, the description provides a complete picture: input constraints, exact output structure (facets array and _meta), error scenarios, and caveats about data interpretation. It references the sibling tool for filtered counts, ensuring agents understand the broader context.

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

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

The description adds significant meaning beyond the schema by explaining deduping, module-built comma-joining, the unique semantics of LeadSponsorClass (distinct from the search tool's funderType), and the effect of unlisted fields (invalid_input). It also clarifies that fields must be from the whitelisted ENUM list, complementing the schema's enum definition.

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

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

The description clearly defines the tool as an aggregate/statistical view providing exact per-value study counts over the entire ClinicalTrials.gov registry for whitelisted ENUM fields. It distinguishes itself from the sibling tool clinicaltrials_search_studies by calling itself the "DISTRIBUTION sibling" that gives whole-registry counts versus filtered totals.

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 distributions) versus the search tool (for filtered totals) and notes that these counts are not filterable. It cross-links the search tool for filtered counts, providing clear guidance on 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?

Beyond the annotations (readOnlyHint, openWorldHint), the description discloses many behaviors: honesty with countTotal=true, opaque cursor pagination, error handling (bad token throws 400, funderType invalid silently returns 0 but is rejected pre-fetch), AND-conjunctive multi-word queries, and the fact that leadSponsor.name is free text. 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 very long (approximately 500 words) and covers many details. While well-structured and front-loaded with the main purpose, it could be more concise without losing essential information. Some repetition (e.g., 'LIVE-CONFIRMED to narrow' appears multiple times) increases length.

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

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

The description is highly complete for a complex search tool with 8 parameters and no output schema. It includes a pseudo-return schema, explains pagination behavior, error cases, and the honesty mechanism. It also references related tools (clinicaltrials_get_study, clinicaltrials_facet_counts) to complete the context.

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

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

Schema description coverage is 100%, yet the description adds significant value: for 'sponsor,' it clarifies it's a fuzzy full-text name search (not a UEI); for 'funderType,' it explains the overlapping facet and the trap; for 'query.term,' it states AND-conjunctive behavior. These details are beyond the schema and aid correct parameter usage.

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 searches federally-registered clinical-research studies with entity enrichment, distinguishing it from clinicaltrials_get_study which returns full records. It specifies the resource (clinicaltrials.gov/api/v2/studies) and the scope (trial-registration axis). The verb 'search' and resource 'studies' are explicit, and it differentiates from related tools like clinicaltrials_get_study.

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

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

The description provides explicit guidance on when to use this tool versus alternatives, e.g., 'Feed a row's nctId to clinicaltrials_get_study for the full record + briefSummary.' It also states that the tool is for narrowing filters ('LIVE-CONFIRMED-narrowing filters ONLY') and explains that it is not for federal award data ('A registered trial is NOT a federal award'). This helps the agent choose 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?

Discloses honest count behavior, error handling for 4xx, 5xx, and schema drift, pagination details, numeric-string conversion, naming conventions, and vintage. 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?

Well-organized with clear sections and front-loaded key info; slightly long but every sentence adds value given 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?

Covers return structure, _meta , error handling, data source limitations, and all aspects needed for agent usage despite no output schema.

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

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

Schema coverage is 100%, and description adds clarity on required combination, validation patterns, defaults, and pagination behavior beyond schema 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 'Look up Medicare DMEPOS SUPPLIERS' with specific verb and resource, and distinguishes itself from sibling cms_medicare_provider_services.

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 specifies required parameters (at least one of npi or state), optional size/offset, and provides context on when to use (supplier-level aggregate figures) and when not (no patient identifiers, not fraud determination). References sibling tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds extensive behavioral details: honest pagination with totalAvailable from count, coalescing of column names across four datasets, handling of missing fields (null, never empty string), error responses (no-match → empty, invalid input → invalid_input, 4xx/5xx behavior), server-side AND filtering, and keyless access. 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 quite verbose (multiple paragraphs with technical details like URL path behavior and column coalescing). While well-structured and front-loaded with core purpose, it could be more concise for quick scanning. Every sentence adds value, but length may hinder readability.

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

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

Given the tool's complexity (multi-dataset, pagination, coalescing), the description is remarkably complete. It covers return format, honest pagination, error handling, field behavior, and keyless access. No output schema exists, so the description compensates fully.

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%, baseline 3. The description adds value beyond schema: provides counts for each facilityType enum, explains that the value selects a dataset id via constant map, describes state validation regex, and clarifies facilityName as case-insensitive substring match. This enhances parameter 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's purpose: to look up Medicare/Medicaid-certified healthcare facilities by type, returning name, address, city, state, zip, and ownership. It distinguishes itself from siblings by noting it generalizes cms_hospital_compare beyond hospitals.

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 requirements (facilityType required, optional state, facilityName, size, offset) and states that it is a facility directory, not a clinical-quality tool. It hints at alternatives by mentioning it generalizes cms_hospital_compare, but does not explicitly contrast with sibling tools like nppes_lookup_provider.

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 disclosed all behavioral traits: pagination with honest count, null handling for ratings and emergency services, error handling (4xx, 5xx, schema drift), server-side filtering, and keyless operation. Annotations only provide readOnlyHint and openWorldHint; the description goes far beyond with concrete details.

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: a concise opening sentence, followed by parameter details, return format, honest behaviors, and error handling. It is front-loaded with the core purpose and uses bullet-like formatting for clarity. While it could be slightly trimmed, every sentence adds necessary detail for a complex tool.

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

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

Given the tool's complexity (5 parameters, no output schema but return details described, pagination, null handling), the description is remarkably complete. It covers input constraints, output structure, edge cases, and error conditions, leaving no gap for an agent to misinterpret usage. The absence of an output schema is fully compensated.

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

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

The input schema already describes all five parameters with detailed descriptions, achieving 100% coverage. The description adds value by clarifying match semantics (EXACT vs. substring), allowed characters, validation rules, and default values, enhancing agent 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?

The description clearly states the tool looks up Medicare-certified hospitals by state and/or facility name, detailing the specific fields returned (location, type, ownership, emergency services, star rating). It defines the resource and action precisely, and the scope is well-delineated, making it distinct from sibling CMS tools.

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

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

The description provides explicit constraints: at least one of state or facilityName is required, hospitalType alone is insufficient, and pagination parameters are specified. It does not directly state when not to use the tool or list alternatives, but the constraints are clear enough for effective selection.

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

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

Annotations provide readOnlyHint and openWorldHint. Description adds significant context: keyless API, honest counts (never faked), null handling, error categories, data vintage, aggregate nature. 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?

Description is detailed but well-structured with sections, bullet points, and examples. While lengthy, it is front-loaded with essential info and each sentence adds value. Small gains in conciseness 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?

For a complex tool with 6 parameters, no output schema, but rich constraints, the description covers input requirements, output format, pagination, edge cases, honesty policy, and dataset limitations comprehensively.

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

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

Schema covers 100% of parameters with descriptions. Description adds validation patterns (\d{10}, ^[A-Za-z]{2}), reinforces at least one required, default size, and pagination details. Exceeds baseline 3.

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

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

The description clearly defines the tool as looking up Medicare Part B provider utilization by NPI or state, listing specific fields and the CMS dataset. It distinguishes from sibling 'nppes_lookup_provider' as the demand-side complement. Verb+resource+scope are precise.

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?

Explicit guidance: when to use (provider billing data, demand-side complement), constraints (at least one of npi/state required; providerType/hcpcsCode alone not enough), pagination, and honest error handling. Clearly differentiates from 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 goes far beyond the readOnlyHint and openWorldHint annotations, detailing exact behavior of count (exact grand total), conditions (server-side, self-policing, no silent drop), limit (hard cap 500, error on exceed), error handling (400, 404, HTML, 5xx, timeout, throw), the results mode, SSRF validation, PII disclosure, and the reach cap. 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 long but well-structured with clear sections (main purpose, honesty details, results mode, error handling, SSRF, PII, caveat). Bold and emoji highlights aid readability. Every sentence provides unique, essential information, but could be slightly more concise 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?

Given the complexity (7 parameters, no output schema), the description is fully complete. It covers all return fields (datasetid, index, results mode, fields, rows, _meta), error modes, constraints, security, disclaimers, and provides a concrete example. It leaves no behavioral gaps for an AI agent to infer.

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, the baseline is 3, but the description adds substantial context: index default 0 and path interpolation, limit hard cap and rejection, offset policy cap, results mode explanation, datasetId SSRF validation and example, conditions limit and error behavior, properties optional. These details significantly enhance 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?

The description explicitly states the tool queries a CMS Open Payments DKAN datastore distribution by datasetId and index, specifies the exact API endpoint, and gives a concrete example dataset. It clearly distinguishes itself from sibling tools like 'treasury_query_dataset' by naming the specific data source and use case (healthcare financial relationships, conflict-of-interest vetting).

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 when-to-use context (healthcare industry-financial-relationship, COI-vetting, market intelligence not answerable by NPPES) and when-not-to (not a conflict-of-interest finding, fitness determination, exclusion determination). It recommends cross-checking with SAM, OFAC, OIG-LEIE, and states the reach cap of offset≤2000 as a deliberate targeted-lookup boundary, offering clear 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?

Provides extensive behavioral details beyond annotations: honest totalAvailable from separate query, no key required, pagination behavior, null handling, error responses. Complements readOnlyHint and openWorldHint with concrete specifics.

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

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

Front-loaded with purpose and source, then detailed sections. Though lengthy, each sentence adds value. Well-structured for quick scanning.

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 aspects: source, return format, pagination, error handling, data honesty, and use case. No output schema needed; description fully equips agent.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaningful context: explains pagination, notes optionality and safe unfiltered usage, and clarifies exact match for state/lastName.

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 'Search CMS's PUBLIC Revoked Medicare Providers & Suppliers list' with specific fields returned. Distinguishes from siblings by noting it's in the same class as OFAC/SAM-exclusions lists for vetting/due diligence.

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 says 'for screening a counterparty before teaming or subcontracting' and notes input is optional with safe unfiltered paging. While it doesn't state when not to use, the context and sibling list make its niche 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 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?

Annotations provide readOnlyHint and openWorldHint. The description goes far beyond by disclosing data provenance, the non-.gov nature, keyless access, honest pagination (cursor instead of offset), handling of missing fields (null vs ''), error responses (400, 429, 5xx), and SSRF protection. 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?

Despite being long, every sentence is meaningful. The structure is logical: purpose, provenance, parameter details, honesty disclosures, error handling. Information is front-loaded and uses formatting (bold, capitalization) for emphasis.

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 the description compensates by specifying the return structure (`{ opinions: [...] }`) and explaining error cases. It covers all 7 parameters, behavior, and edge cases, making it fully informative for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value: explains mapping to API fields (e.g., `query` → q), validation rules, defaults (order: 'dateFiled desc'), usage of cursor as opaque token, and clarifies that natureOfSuit is not a dedicated filter.

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 'Search US FEDERAL COURT OPINIONS (case law / litigation)' and specifies the resource (CourtListener). It provides a specific verb (search) and resource (opinions), with enough detail to distinguish from sibling tools like usas_search_awards or gao_protest_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 extensive context: provenance, keyless access, optional token for rate limits, detailed parameter examples (e.g., court='uscfc' for contract claims), and notes on limitations (natureOfSuit folded into query). However, it does not explicitly state when not to use this tool or compare it to 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 indicate readOnlyHint and openWorldHint. Description adds extensive behavioral context: returns complete matching set, no fabricated totals, default date window, honest empty, data flattening, validation (date, recallNumber), and fixed host. 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 thorough, covering purpose, parameters, return structure, error cases, and data handling. While lengthy, it is well-organized with sections (KEYLESS, HONESTY) and formatting (★). Every sentence adds necessary detail; 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?

Given 5 optional parameters, 100% schema coverage, no output schema, the description fully explains return structure, default behavior, error modes, and data processing. It is comprehensive and leaves no significant gaps for an agent to infer.

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% (all 5 parameters documented). The description adds value by explaining CPSC field mapping (e.g., RecallDateStart), substring matching, and validation patterns beyond the schema. It goes beyond bare schema documentation.

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 looks up CPSC consumer-product recalls, listing specific data fields (title, hazard, remedy, etc.) and sources. It distinguishes itself from sibling tools like nhtsa_recalls (vehicles) and openfda (medical), establishing its unique domain.

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 when-to-use: consumer product recalls. Highlights keyless access, optional inputs, default 90-day window without filters, honest empty results, and error handling (invalid_input, schema_drift). Clearly distinguishes from 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 provides extensive behavioral details: CVSS metrics handling, KEV honesty with caveats, pagination from NVD's exact totalResults, error handling for rate limits and HTTP errors, and API key usage. Annotations give readOnlyHint and openWorldHint, and the description adds significant context without contradiction.

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

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

The description is very long (multiple paragraphs) and covers many details. It is front-loaded with the main purpose, but the verbosity impacts conciseness. For a complex tool, it is acceptable, but could be more concise.

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 extremely complete: it explains input parameters, output structure (including nested objects), error states, rate limiting, and honesty policies. No output schema is provided, but the description compensates fully. It covers all necessary aspects for an agent to 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?

Schema description coverage is 100%, so baseline is 3. The description adds extra context beyond schema: validation details (cveId format, date pairing, max pages), edge cases (kevOnly throwing on KEV catalog failure, over-cap refused, date span clamping), and honesty policies. This adds meaningful 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 explicitly states the tool does CVE lookup via cveId or search parameters, with KEV join. It is specific about the resource (NIST NVD CVE records) and the verb (look up/search). The sibling tools are in completely different domains (USAS, SAM, etc.), so this tool is clearly distinguished.

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 tool is for FedRAMP/CMMC/SBOM IT-compliance and includes CVSS severity and CISA KEV status. It does not explicitly say when NOT to use it or list alternatives, but given the sibling tools are unrelated, the usage context is clear.

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

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

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?

The description provides extensive behavioral details beyond annotations: key requirement, error handling for various status codes (401/403, 400, empty, 429, 5xx, 200 non-JSON), pagination (offset, hasMore, nextOffset), honesty about totalAvailable, and verbatim data return. Annotations only provide 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 lengthy but every sentence adds value. It uses bold for emphasis and organizes information logically (purpose, key requirement, parameters, error handling). Could be slightly more concise but justified given 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 no output schema, the description explains return format, pagination, error responses, and dependency on dol_list_datasets. Complete for a data-fetching 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%, and the description adds meaningful context: required fields from dol_list_datasets, regex validation, paired filterField/filterValue as equality filter, default and max for limit, best-effort column selection for fields.

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 records from ONE US DOL dataset', specifying the verb and resource. It distinguishes from sibling tools by noting the dependency on dol_list_datasets for discovering datasets and agencies.

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 says when to use: to fetch records from a DOL dataset. Details prerequisites (requires DOL_API_KEY) and that without the key it throws an error. Also notes that dol_list_datasets and agency list stay keyless, providing guidance on 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?

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 declare readOnlyHint=true, and the description adds valuable context: 'never a fabricated report', output structure including _meta, and error behavior on bad RegistryID. 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?

Three sentences, each with a clear role: purpose, input, output/behavior. No unnecessary words, front-loaded with the most critical 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 single-parameter read-only tool, the description covers purpose, input, output format, error behavior, and usage scenario. No missing elements given the simplicity.

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

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

Schema coverage is 100% with a detailed description of registryId. The tool description adds context about source (echo_search_facilities rows), validation (all-digit, 9–12 digits), and error behavior, going 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 explicitly states 'Fetch the EPA ECHO Detailed Facility Report (DFR) for ONE facility by its FRS RegistryID', providing a specific verb, resource, and scope. It distinguishes from the sibling tool echo_search_facilities which is for searching facilities. No 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 explains when to use: 'for competitor or acquisition-target due diligence', and clarifies input source: 'from echo_search_facilities rows'. It also describes behavior on bad input but does not explicitly state when not to use, though the unique purpose makes it 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?

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 declare readOnlyHint and openWorldHint. The description goes far beyond by detailing period identity, revision detection, null vs. 0 handling, error behaviors (404 vs. 5xx vs. throw), validation, injection prevention, and the 'canonicalOnly' dedup logic. 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 comprehensive but verbose. It is front-loaded with purpose and relationship, then dives into extensive 'HONESTY' details. While every sentence adds value, the length could be slightly reduced for quicker parsing. However, given complexity, the structure is logical.

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

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

The description covers the full return structure, error handling, client-side filtering, period identity, and revision semantics. It addresses edge cases and provides sufficient detail for an agent to invoke the tool correctly, even without an output schema. All 9 parameters are well-documented in context.

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

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

Schema coverage is 100%, but the description adds substantial context: explains how each parameter interacts with the upstream API (e.g., 'unit' as client-side filter, 'canonicalOnly' deduplication), clarifies edge cases (unit not present yields empty result with note), and enriches understanding of parameters like 'fy' and 'form' as client-side filters.

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

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

The description clearly identifies the tool as fetching a complete time-series for one filer and one XBRL concept. It explicitly distinguishes itself from siblings `edgar_company_facts` and `edgar_xbrl_frames` by positioning as a focused primitive for tracking trends and revisions.

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

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

The description provides explicit usage context: 'track THIS filer's Assets/Revenues/NetIncomeLoss OVER TIME, and was it ever revised?' It also clarifies the middle position between its two sibling tools, implying when to use this vs. the others. It includes detailed behavioral notes that serve as guidelines for interpreting results.

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.

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 (6 parameters, shard logic, throttle gate, completeness guarantees) and no output schema, the description covers all essential aspects: input, behavior, edge cases (partial responses), and return format (filings with archive URL). It provides sufficient detail for correct invocation and interpretation.

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

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

All 6 parameters have schema descriptions, but the tool description adds substantial value: explains the default for limit (20), maxShards (10), fullHistory (false), clarifies that offset applies to recent window, and describes the interplay between fullHistory and maxShards. It also defines keyless access and the source URL.

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

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

The description clearly states it returns a company's SEC filings from data.sec.gov, specifying inputs (cikOrTicker, forms, limit, offset, fullHistory, maxShards) and output (filings with real primary-document URL). It distinguishes itself from siblings like edgar_company_facts or edgar_full_text_search by focusing on filings retrieval.

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

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

The description provides explicit guidance on when to use fullHistory (for complete history vs. recent window), how pagination works (offset vs. maxShards), and what to do if capped (raise maxShards). It also notes the EDGAR throttle gate and that CIK is used, not SAM UEI/DUNS. While it doesn't name alternative tools explicitly, the context is clear enough for an agent to decide.

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 details important behavioral traits: full-scan behavior, honesty about totalAvailable (exact match count, not page-limited), handling of 403 errors with multiple fallback scenarios (not-yet-disseminated vs genuine absence vs rate-limited), date validation pre-fetch, and normalization of dateFiled. 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 well-structured with clear paragraphs and bullet-like lists (e.g., the HONESTY section and date handling). It is relatively verbose but every sentence provides useful context. It could be slightly more succinct, but it earns its length through valuable detail.

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

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

Given the complexity (6 parameters, no output schema, integration with EDGAR's quirks), the description covers all essential aspects: data source, filtering, pagination behavior, error handling (403 scenarios), date validation, honesty about results, and normalization. It leaves no major gaps for an agent to misuse 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?

All six parameters are described in the input schema with 100% coverage. The description adds value by explaining how filters are applied (CLIENT-SIDE), that limit does not reduce download size, and that date validation occurs pre-fetch. While the schema already provides adequate descriptions, the tool description enhances understanding of behavior beyond syntax.

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 a per-day cross-filer SEC filing index, distinguishing itself from the sibling tool 'edgar_filing_index' by specifying it is ~30× smaller and reads one calendar day's index. It uses specific verbs like 'reads', 'FULL-SCANS', and 'returns' to clearly define the action and result.

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

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

The description explicitly contrasts with the quarterly tool, stating it answers 'the monitoring/alerting question the quarterly tool cannot' and provides concrete examples like 'every 8-K filed on 2024-01-03' and 'watch a CIK day-by-day'. This gives clear 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.