LiveDataLink

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description is free to add higher-value context — and it does: the two source sets are not silently property-matched because FHA's workbook lacks a street-address key, and results make no refinance/contact/valuation/affordability-expiration claims. That is unusually candid about analytical limitations and non-claims.

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 dense sentences with the deliverable front-loaded and the caveats second; nothing is filler. Slightly heavy clause packing, but every clause carries distinct 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 five-parameter, no-output-schema composite tool, the description covers scope, source composition, and explicit non-claims. It leaves pagination/limit behavior and the shape of the returned pack unstated, but the core decision inputs are present.

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 60% (start_date, end_date, response_format documented; state and limit bare). The description reinforces the state-level and date-window framing but adds no syntax, default, or meaning for the undocumented 'limit' parameter or any new detail beyond the schema. Baseline 3 fits.

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

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

States a specific verb and composite resource ('return a source-linked, state-level evidence pack') and names both underlying source sets (HUD FHA maturity records, HUD LIHTC year-15 signals) plus the scope (one date window). An agent can distinguish this composite pack from the sibling single-source tools hud_fha_maturity_search and hud_lihtc_year15_radar without opening the schema.

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

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

'Use this for affordable-housing debt or timing diligence' gives an intended use case, which is more than nothing. However it never names the narrower siblings (hud_fha_maturity_search, hud_lihtc_year15_radar) or states when to prefer them over this combined pack, so the routing decision is left implicit.

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

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

Annotations already establish this as read-only, idempotent, open-world, and non-destructive. The description adds behavioral detail by stating the response includes a health category rating and specific pollutant levels, which helps the agent set expectations about live, current measurements.

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

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

The description is front-loaded with the tool's purpose and return data, then gives a practical set of example queries. The list of query phrasings is slightly redundant near the end, but overall it is crisp and useful.

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

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

For a single-parameter read-only tool with strong annotations and a complete schema, the description covers what data is returned and the kinds of questions it answers. It does not discuss data freshness, units, or coverage limitations, but these are minor gaps given the tool's simplicity.

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

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

The input schema already fully documents the single 'location' parameter as 'City, zip code, or place name' with 100% coverage. The description's examples reinforce that location can be a place name like Los Angeles, but it does not add meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Get'), a clear resource ('current air quality data'), and enumerates the exact data returned (US AQI, PM2.5, PM10, ozone, NO2, SO2, CO, health category). It is immediately distinguishable from weather, health, or pollution-related sibling 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 natural-language triggers ('what's the air quality?', 'is it safe to go outside?', 'AQI in Los Angeles') and states to use it for 'any air quality or pollution question.' It does not name alternatives or exclusion cases, but the guidance is clear enough for an agent to select this tool confidently.

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

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

With readOnly/idempotent annotations already covering safety, the description adds behavioral nuance beyond structured data: 'FDIC is the primary signal; CFPB complaint data is best-effort and degrades gracefully if the bank's complaint records cannot be matched,' plus the explicit 'not a rating or advice' boundary.

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 front-loaded with the core purpose, and each sentence pulls weight (data sources, output, fallback, use cases). It loses a point for restating parameter guidance already present in the schema, making it slightly longer than necessary.

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

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

With no output schema, the description still communicates the returned read's contents: the category label, underlying financial metrics, complaint volume/products, and graceful degradation. The use-case and disclaimer sentences close the remaining selection and invocation questions.

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

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

Schema coverage is 100%, so the schema already documents both params and the full-legal-name matching tip. The description's 'bank name or FDIC certificate (CERT) number' reinforces the one-of relationship but adds little beyond what the schema states.

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

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

The description names a specific action ('financial-health read'), a specific resource ('US bank or savings institution'), and concrete output categories (HEALTHY/STABLE/WATCH/FAILED). The explicit FDIC + CFPB join distinguishes it from sibling FDIC-only and CFPB-only 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?

It gives concrete use cases (sponsor/partner bank selection, treasury counterparty checks, deposit-safety questions) and frames the tool as a one-call read, which implies when it is appropriate. However, it never names alternatives or says when-not-to-use it, so the guidance is clear but not fully exclusionary.

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 readOnly/idempotent/openWorld, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: output is sorted high-to-low, includes exact unit, missing-value evidence, GeoFIPS, source hash, and attribution. It does not disclose rate limits or the 2–8 boundary's behavior at the edges, but it goes well beyond what annotations provide.

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

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

Four sentences, front-loaded with the core action before examples and the scope caveat. Each sentence earns its place, though the enumeration of return fields is slightly list-like rather than tightly worded.

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?

There is no output schema, so the description carries the return-value burden and it does list key output fields (sorted values, unit, missing-value evidence, GeoFIPS, source hash, attribution). Combined with full schema coverage and read-only annotations, an agent has what it needs; only edge-case parameter behavior (e.g., duplicate/over-8 selectors) is left unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents year, indicator (with example slugs), geographies, and response_format. The description restates the 2–8 state constraint and names example indicators, adding marginal value but no new syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb (Compare) and resource (one official BEA SASUMMARY annual indicator across 2–8 requested states) for an exact year, and it bounds scope with 'It does not rank all states unless they are explicitly supplied.' This differentiates it from trend/profile siblings without needing to open any schema.

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

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

Three concrete usage examples ('compare 2024 Texas and California GDP', 'which of these states had higher 2023 per-capita income?', 'compare regional price levels') make the intended call pattern obvious, and the closing sentence defines a scope limit. However, it never names an alternative sibling (e.g., bea_state_economic_trend) or states when to prefer one, so it falls short of explicit when/when-not routing.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds real value beyond them by enumerating the returned payload (canonical names, definitions, units, coverage, pagination, evidence hash, attribution) and pinning the data scope to a compact annual snapshot of 15 indicators. It does not mention auth or rate limits, so not a 5.

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

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

Three sentences, front-loaded with the resource and scope, followed by concrete use cases and the boundary statement. Dense but every clause carries information; the first sentence is long yet not padded.

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

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

There is no output schema, so the description carries the burden of explaining returns, and it does list the payload fields. Scope boundaries are explicit. It falls short of a 5 only because pagination mechanics and the meaning of the 'evidence hash' are not explained.

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% with all four parameters documented (limit, query, offset, response_format), so the baseline is 3. The description adds only marginal meaning beyond the schema, hinting that the query matches names/definitions/units and that pagination exists, but gives no syntax or format guidance.

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

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

States a specific verb (search) and resource (the 15 indicators in LiveDataLink's self-hosted official BEA SASUMMARY annual state snapshot), and the second half of the description explicitly bounds the scope against the full BEA API and industry detail. This lets an agent distinguish it from siblings like bea_state_economic_history or bea_compare_states without opening a schema.

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

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

Gives explicit trigger questions ('what BEA state measures are hosted?', 'find regional price parity') and names the downstream workflow it feeds ('resolve an indicator before a history call'). It also states when not to use it ('not the full BEA API or industry detail'), which is rare and useful.

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

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

Annotations already cover the read-only/idempotent/open-world profile, so the bar is lower, and the description adds real value: it enumerates returned fields (value, unit, GeoFIPS, pagination, source update date, evidence hash, attribution) and discloses the revision caveat ('BEA can revise prior vintages'). That revision behavior is a genuine behavioral trait beyond the annotations.

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

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

Front-loaded with the core purpose, followed by return contents and then three illustrative examples. Every sentence carries information; only minor tightening is possible around the example list.

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

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

For a tool with no output schema, the description does well to list return fields and revision behavior. It is incomplete on two points an agent needs: how to choose this over bea_state_economic_trend, and how the year-range filters relate to the limit/offset pagination.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only light framing ('bounded', 'state GeoFIPS', 'unit') that the schema already carries, and it does not clarify how limit/offset interact with start_year/end_year.

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

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

States a specific verb ("Return") and resource ("bounded annual history for one official BEA SASUMMARY state or U.S. indicator"), making the operation clear. It does not differentiate from sibling BEA tools such as bea_state_economic_trend, which reads as an overlapping concept, so an agent cannot disambiguate by description alone.

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

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

The concrete example queries ("Texas real GDP since 2018", "US employment by year") give implied usage context, and the scope note ('Published aggregate annual estimates only') bounds the domain. However, no when-not guidance or named alternatives are given, so the split against bea_state_economic_trend, bea_state_economic_profile, and bea_compare_states is left to inference.

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

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

Annotations already establish readOnly/idempotent/openWorld/non-destructive, so the bar is lower. The description still adds genuinely useful conduct: mixed vintages ('Each value carries its own year and unit because source update calendars differ') and the scope disclaimer ('Aggregate estimates only; not a forecast or investment recommendation'). It does not explain response payload shape, but that is a minor omission here.

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, front-loaded with purpose and scope, then the vintage caveat, then usage examples and disclaimers. Every sentence carries information, though the indicator enumeration is somewhat list-heavy.

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

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

No output schema exists, so the description must carry the return-value burden and does so at a useful level (15 indicators, per-value year/unit, aggregate-only). The main missing element is explicit routing against its BEA siblings, which prevents a 5.

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

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

Schema description coverage is 100%, so geography, as_of_year, and response_format are already documented in the schema. The description corroborates the geography scope ('one state or the United States') but adds no format or constraint detail beyond what the schema already provides, so the baseline 3 applies.

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

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

Specific verb ('Build') plus resource ('official BEA annual economic profile') and an explicit scope ('one state or the United States across all 15 hosted SASUMMARY indicators'). It is clear what the tool returns, but it never names or distinguishes itself from the four sibling BEA tools (bea_state_economic_history, bea_state_economic_trend, bea_compare_states, bea_search_state_indicators), so an agent must infer which BEA tool applies.

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

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

Gives concrete trigger phrases ('BEA profile for North Carolina', 'state GDP income jobs packet') and positions the tool as a component of a regional market brief alongside Census/BLS/SBA/FDIC data. It stops short of stating when NOT to use it or which BEA sibling to prefer for time-series or comparison needs.

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

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

Annotations already establish the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower; the description still adds real context by disclosing the return payload (component observations, absolute/percent changes, CAGR, units, vintage evidence, caveats) and the temporal-safety role of as_of_year. This goes beyond what the annotations convey.

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

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

Three sentences, front-loaded with the core verb and resource, then returns, then use cases and the as-of caveat. Every sentence carries distinct information with no filler.

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

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

With no output schema, the description usefully enumerates what comes back, covers all four parameters, and supplies invocation examples, making it largely self-sufficient. The one gap is sibling routing: an agent choosing between this and bea_state_economic_history gets no explicit guidance.

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 earns an extra point by explaining the semantic intent of as_of_year ('prevents future observations from entering a historical calculation'), which the schema only weakly hints at. It adds no syntax beyond the schema for the other three parameters.

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

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

States a specific verb+resource ('Calculate prior-observation and exact five-year changes for one official BEA SASUMMARY state indicator') and enumerates the returned components, so the agent knows exactly what computation this performs. It does not name the adjacent siblings (bea_state_economic_history, bea_state_economic_profile, bea_compare_states), so differentiation is left to inference from the 'trend/change' framing.

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?

Three concrete invocation examples ('five-year Florida GDP trend', 'how has Ohio employment changed?', 'California real per-capita income growth') give clear context for when this tool applies. It stops short of stating when NOT to use it or naming an alternative sibling for profile/history lookups.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations: it discloses the GLEIF mapping approach, the ~15 entity cap, the sanctions sources screened, best-effort failure behavior, that only self-reported GLEIF relationships are shown, and that name matches are not proof of identity. 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?

Though long, the description is dense with non-redundant information and every sentence earns its place: purpose, method, scope, failure behavior, return contents, and caveats. The core value proposition is front-loaded in the first sentence.

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

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

With no output schema, the description still explains what the tool returns: mapped ownership structure, per-entity CLEAR/HIT results with matched list entry/source/score, and an overall verdict. It also covers edge cases like GLEIF failure and unavailable sanctions binding, making it practically complete for an 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 description coverage is 100%, so the schema documents both parameters. The description adds meaningful semantics on top: the LEI must be 20 characters, an LEI can be supplied via either field, and the lei parameter overrides a name search. This helps the agent disambiguate 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 states a specific verb and resource: a one-call KYB/AML ownership-chain sanctions screen. It clearly frames the real question being answered and distinguishes itself from a simple top-level-name list check, which separates it from related screening and lookup 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 explains when this tool is valuable: when ownership-chain exposure must be caught beyond screening only the counterparty name. It references the same matcher as company_trust_check and notes GLEIF-based mapping, giving useful context, though it does not explicitly enumerate sibling alternatives or state hard 'do not use when' conditions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds real value beyond that: it discloses the return shape (a monthly time series) and the authentication posture (keyless, official BLS data), both of which the annotations do not convey.

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

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

Three short, front-loaded sentences with no filler; the capability statement comes first and the operational details (indicator list, return shape, keyless access) follow compactly. Minor redundancy between the indicator list here and in the schema.

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

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

With no output schema, the description carries the return-value burden and does state that a monthly time series is returned, plus that no key is required. It omits units/seasonal-adjustment conventions, which would be helpful for a statistics tool, but nothing critical to calling it is missing.

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

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

Schema description coverage is 100%, so the indicator list and the start/end year defaults are already documented in the schema. The description repeats the indicator enumeration but adds no syntax, unit, or frequency detail beyond it, so the baseline of 3 applies.

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

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

States a specific verb+resource (US labor & price statistics from BLS) and enumerates the nine friendly indicator names, making the scope concrete. It does not explicitly name the nearest sibling (bls_series) or explain how the friendly-name lookup differs from a series-ID lookup, so sibling differentiation is only implied.

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

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

There is no explicit when-to-use or when-not guidance and no named alternative, despite several overlapping siblings (bls_series, fred_quick_indicator, fred_observations) that an agent must choose between. The indicator list implies usage but does not help the agent route 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the safety profile is well covered. The description adds only that the series ID is raw and gives examples; it omits behavior such as default date ranges, return format, or how start_year/end_year affect the fetched time series.

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 two tightly written sentences with no wasted words. The core capability and usage condition are front-loaded, making it easy for an agent to parse quickly.

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

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

For a simple lookup tool with rich annotations, the description covers what the tool does and when to use it. However, because there is no output schema, it should ideally explain what the fetched time series returns or how start_year/end_year defaults work, leaving a moderate completeness 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 100%, so the schema already documents all three parameters. The description's mention of 'raw series ID' and example IDs adds slight meaning beyond the schema, but it does not elaborate on start_year or end_year semantics, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: 'Fetch any BLS time series by its raw series ID.' It distinguishes the tool's input mode from likely siblings by emphasizing exact 'raw series ID' usage and provides concrete examples such as 'LNS14000000'.

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

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

It clearly states when to use the tool: 'For when you know the exact BLS series ID.' However, it does not name an alternative for when the exact ID is unknown, such as a search or indicator-based 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 establish readOnly, idempotent, openWorld, and non-destructive behavior, so the safety profile is covered. The description adds real value by enumerating what is returned (title, authors, subjects, languages, copyright, download count, full-text index status), which matters since there is no output schema.

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

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

A single front-loaded sentence with an enumerated parenthetical; every clause earns its place and nothing is repeated or padded.

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

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

For a read-only single-record lookup with annotations covering safety and a description enumerating the return fields, an agent has what it needs despite the absence of an output schema. Only the lack of sibling routing keeps it from the top band.

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

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

Schema description coverage is 100% and the schema already names and exemplifies the id ('84 (Frankenstein)'). The description's 'Project Gutenberg id' adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Get full catalog metadata') and resource ('a single book by its Project Gutenberg id'), and enumerates the returned fields, which implicitly separates it from the search and full-text siblings. It does not explicitly name a sibling it is not, so it falls just short of the top band.

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

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

The phrase 'single book by its Project Gutenberg id' conveys the usage context (a known-id metadata lookup) but offers no explicit when-to-use/no-use guidance and never points to book_search or book_get_text as alternatives. Minimum viable context only.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds that results are snippets (passages) rather than full books and describes the returned fields, which is useful, but doesn't discuss ranking, matching mode, or corpus size.

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 tight sentences, front-loaded with the core action and result format. The phrase 'This is the headline feature' is slightly promotional but still informative about prominence. No wasted words overall.

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 3-param read-only search with full schema coverage and no output schema, the description covers purpose, scope, result shape, and the one optional filter. It stops short of explaining matching behaviour or ranking, which would have made it fully self-sufficient, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents query, limit (with default/max), and gutenberg_id. The description repeats the gutenberg_id restriction without adding syntax or semantics beyond the schema, matching the baseline for fully documented params.

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

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

States a specific verb (search), scope (inside indexed public-domain corpus), and resource (books), plus the return shape (matching passages with title, author, snippet). Distinguishes itself from siblings like book_search (metadata) and book_get_text (full text of one book) by emphasizing in-text phrase 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?

Explains that it finds where a passage appears across great books and that gutenberg_id optionally restricts to one book. It doesn't explicitly name book_search or book_get_text as alternatives, but the search-vs-fetch distinction is clear enough to route the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds real behavioral value beyond them: it is paginated by passage and falls back to returning a public URL for un-indexed books. However it never says what a 'passage' is, whether a total count is returned, or how the agent knows paging is exhausted.

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, zero filler, front-loaded with the core action before the paging instruction and the fallback caveat. Every sentence carries distinct 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?

With no output schema, the description does explain the two possible return shapes (paginated passage text or a gutenberg.org URL), which is the critical thing an agent needs. It stops short of explaining pagination termination or passage granularity, a minor gap for a paged-text tool.

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

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

Schema description coverage is 100%, with defaults and min/max bounds documented for all three parameters, so the schema does the heavy lifting and a 3 is the baseline. The description reinforces the paging contract (from_seq + max_passages) but adds no syntax or semantic detail the schema lacks.

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

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

States a specific verb and resource ('Return the full text of an indexed book by Gutenberg id') and carves out the indexed-vs-catalog scope. It does not name the closely related siblings (book_fulltext_search, book_details) that an agent might otherwise pick, so differentiation is implicit rather than explicit.

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 says to use from_seq + max_passages to page through the text, which is parameter usage rather than tool selection. It does give one genuine routing condition ('for books NOT indexed locally, returns the gutenberg.org URL'), but never says when to prefer this over book_fulltext_search or book_search.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered. The description adds genuinely useful context beyond that: it is a live external call against Gutendex, results are ranked by keyword relevance then download popularity, and it discloses the returned fields. It stops short of mentioning rate limits or pagination 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?

Three sentences, each earning its place: scope, ranking/return behavior, and the sibling routing. Front-loaded with the core action and the discriminating alternative placed last, which is the right order.

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

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

No output schema exists, yet the description enumerates the returned fields (Gutenberg id, title, author(s), language, download count), and covers source, ranking, and sibling disambiguation. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so all five parameters (including limit's default/max) are already documented in the schema. The description's mention of title/author/subject keyword and the optional author/subject/language filters largely restates that. Baseline 3 is appropriate when the schema carries the semantics.

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

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

States a specific verb and resource ('Search the full Project Gutenberg catalog ... by title / author / subject keyword') with scope (~78,500 books) and source (Gutendex). It explicitly distinguishes itself from the sibling book_fulltext_search, so an agent can route correctly without opening either schema.

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

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

Names the alternative (book_fulltext_search) and the condition that selects it ('to search inside the locally indexed top books'). This is an explicit when/when-not split, so the agent knows which of the two book tools to pick.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations by clarifying that the catalog is served live via Gutendex and that the D1 counts are local indexed-corpus statistics, including the last refresh timestamp. This helps the agent understand what data source and freshness semantics to expect.

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

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

The description is a single, well-structured sentence that front-loads the core purpose ('Report the books store status') before listing the key data components. Every element adds value: data source, scale, indexed-corpus metrics, and refresh timestamp. There is no filler or redundant restatement of the tool name.

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 zero-parameter status-reporting tool, the description is complete. It tells the agent what to expect in the response: live catalog availability, indexed corpus counts, total passages, and last refresh timestamp. No output schema is present, but the description compensates well by outlining the return categories. No additional context seems necessary for correct invocation.

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

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

The tool has zero parameters, so the baseline is 4. There are no parameter semantics to explain, and the description appropriately focuses on the output content instead. Because there is no input schema burden, the description does not need to compensate for undocumented parameters.

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

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

The description uses a specific verb ('Report') and a clear resource ('books store status'), then enumerates exactly what the status contains: live Gutendex catalog, local D1 indexed-corpus counts, and last refresh timestamp. This clearly distinguishes it from sibling book tools like book_search, book_details, and book_fulltext_search, which operate on individual books or search results rather than the store's health.

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

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

The description implies this is the tool to use when an agent needs a high-level status or health summary of the books store, rather than specific book content. However, there is no explicit when-to-use guidance, no mention of when not to use it, and no reference to alternative sibling tools. The usage intent is clear enough but left implicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds real value beyond them: it declares the signal is a heuristic for research rather than advice, discloses that it runs on daily bars, and enumerates the returned fields (score 0-100, reasons, etc.) in the absence of an output schema. It does not mention data-source freshness or rate limits, keeping it short of a 5.

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

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

Front-loaded with the screening purpose, followed by the criteria, return shape, tunability, and disclaimer in four tight sentences. The parenthetical list of tunable params is mildly redundant with the schema, but every sentence carries information and nothing is padded.

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

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

With no output schema, the description compensates by naming the per-symbol return fields. It covers purpose, criteria, tunable inputs, output shape, and the heuristic caveat, and annotations handle the safety profile. An agent has everything needed to decide and call correctly.

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

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

Schema description coverage is 100%, so a baseline of 3 applies. The description goes further by framing all four threshold inputs (rsi_threshold, ma_period, proximity_pct, lookback_days) as the tuning surface, telling the agent that calibration is achieved by parameter change rather than implying fixed behavior. It does not restate defaults or ranges, which the schema already supplies.

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

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

States a specific verb (screen) and resource (US tickers on daily bars) and enumerates the exact conditions defining a 'bounce' (proximity to support/MA, oversold turning-up RSI, bullish candle, above-average volume). This is distinguishable from siblings like candlestick_signals or support_resistance_levels, which surface raw components rather than a combined screen.

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 ('Screen one or more US tickers', 'HEURISTIC signal for research, not investment advice') and the criteria make clear when a symbol would qualify, but it never states when to prefer this tool over candlestick_signals, support_resistance_levels, or stock_quote. No explicit alternatives or exclusions are named.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds real context beyond that: measures are kept separate by mode, output includes window totals, completeness, and percent change, and it guarantees it never fabricates a total across incompatible measures.

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 earning its place: the first defines the output, the second defines the composition and metrics, the third gives usage triggers and boundaries. The core purpose is front-loaded with no filler.

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

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

With no output schema, the description carries return-value burden and does so reasonably (window totals, completeness, percent change, per-mode separation). Minor gaps remain on the exact shape of the pack and how prior-window defaults resolve, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents port, response_format, and trailing_months with types, bounds, and defaults. The description adds no parameter-level detail (e.g., how trailing_months interacts with the current/prior windows), so the baseline 3 applies.

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

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

States a specific verb (combine) and resource (every available official BTS crossing measure for one land-border port) and names the deliverable (a provenance-backed current-versus-prior activity evidence pack). The 'for one land-border port' scope and the aggregate-measures framing distinguish it from the sibling search/compare/trend tools without needing to name 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?

Gives explicit triggering examples ('build a border activity pack for Laredo', 'what changed at Otay Mesa?', logistics/corridor briefing) and a negative boundary ('not a congestion or wait-time measure'). It does not explicitly route to the sibling alternatives (bts_transport_search_ports, bts_transport_compare_ports, bts_transport_border_trend), so the when-not-this guidance is incomplete.

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 readOnly/idempotent/non-destructive, so safety is covered; the description adds real behavioral detail beyond that — data comes from a 'self-hosted snapshot', results are bounded and paginated, and each row carries a source hash and provenance for reproducibility. The most valuable addition is the unit caveat: counts are inbound crossing events, not unique vehicles or people, which prevents a common misinterpretation.

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

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

Three sentences, front-loaded with the core operation before the examples and the unit caveat. Every sentence contributes, though the example list is slightly long relative to the amount of new information it conveys.

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

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

With no output schema, the description carries the return-shape burden and does so: exact month, crossing count, stable port identity, pagination, source hash, provenance. Combined with the usage examples and the counting-semantics caveat, an agent has everything needed to call this 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%, including enum and format notes for measure, month patterns, and pagination bounds, so the schema does the heavy lifting and a 3 is the baseline. The description adds only the consistency constraint ('one consistent crossing measure') and the notion of a bounded window, which is marginally useful but largely restates 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 names a specific verb and resource ('Return a bounded monthly history for one official BTS land-border port and one consistent crossing measure') and scopes it tightly to a single port plus a single measure. That scoping implicitly contrasts with compare_ports and search_ports, but no sibling is named outright, so it stops short of a 5.

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

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

It gives concrete invocation contexts ('monthly truck crossings at Laredo', 'pedestrian crossings at San Ysidro since 2023', a reproducible port-volume chart), which tells the agent when this tool fits. It never states when to prefer bts_transport_compare_ports or bts_transport_border_activity_pack instead, so there is context but no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses ranking behavior, that a prior-window count and reported-month completeness are returned, and that port codes are stable and provenance is included — meaningful for a tool with no output schema.

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

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

Three sentences, each earning its place: action and scope first, then returned fields, then usage examples and exclusions. Front-loaded and free of 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?

With no output schema, the description correctly compensates by enumerating the return contents (prior-window count, completeness, percent change, window, codes, provenance). Scope, usage, and exclusions are all present, leaving nothing essential missing for a correct call.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema already spells out the ports count bounds, the measure enum, and the trailing_months window. The description adds conceptual meaning beyond the schema by framing the window as a shared rolling current/prior comparison, tying trailing_months and end_month to a concrete comparison model.

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

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

States a specific verb (compare), resource (U.S. land-border ports), and scope (two to eight ports, one BTS measure, shared rolling window). Clear and unambiguous, but it never names its closest siblings (bts_transport_border_trend, bts_transport_search_ports), so sibling differentiation is left implicit.

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 two concrete invocation examples ('compare truck crossings at Laredo, El Paso, and Otay Mesa') and explicit exclusions ('does not compare wait times, outbound flows, or cargo value'). Strong when/when-not guidance, though it does not point to the alternative tool to use instead for those excluded cases.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world. The description goes beyond them by disclosing the returned fields (port codes, coordinates, measures, coverage, pagination, provenance) and the inbound-only scope constraint. It doesn't cover rate limits or auth given the self-hosted snapshot, but it adds meaningful context over the structured hints.

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

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

Three front-loaded sentences: purpose/source, return payload, and use cases with exclusions. The return-field enumeration is a touch long but each element is informative. Overall tight with no filler.

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

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

There is no output schema, so the description usefully compensates by listing the return fields, coverage, pagination, and provenance. Combined with annotations covering the safety profile and a fully documented input schema, an agent has nearly everything needed; only filter-combination semantics are left unstated.

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

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

Schema description coverage is 100% with per-field descriptions (limit, query, state, border, offset, response_format), so the schema already carries parameter meaning. The description adds only indirect hints via examples ('Laredo', 'Arizona') and doesn't specify query format or how filters combine. Baseline 3 is appropriate.

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

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

States a specific verb (Search) and resource (U.S. land-border ports) with the exact data source, and distinguishes scope with 'Inbound land ports only; not wait times or outbound traffic.' An agent can separate it from the sibling border tools (trend, compare_ports, activity_pack) without opening any schema.

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

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

Offers concrete when-to-use triggers in quotes ('find the Laredo border port code', 'which Arizona ports have truck crossings?') and wraps the workflow ('resolve a port before a trend call'), plus an explicit exclusion for wait times and outbound traffic. It stops short of naming the actual sibling alternatives (e.g., bts_transport_compare_ports), so routing is implied rather than fully explicit.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower; the description adds genuinely new context by disclosing that detection is HEURISTIC with conservative default thresholds and that output is not investment advice. It also spells out the returned fields (pattern, date, direction, barIndex), which goes beyond the annotations. Rate limits or latency are not mentioned, keeping it below 5.

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

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

Front-loaded with the verb and scope, then return shape, then caveat. The pattern enumeration is long but useful for matching a user's request; nothing is padded, though the sentence is dense.

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

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

No output schema exists, but the description compensates by naming the returned fields, and it discloses the heuristic nature and disclaimer. With annotations covering the safety profile and the schema covering both parameters, the definition is complete enough to invoke correctly; only the absence of usage routing against siblings is a gap.

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

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

Schema coverage is 100%, so symbol and lookback_days are already fully documented in the schema (including the default of 60 and the 5-400 range). The description adds only the vague phrase 'recent daily bars', so baseline 3 is correct.

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

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

States a specific verb (detect) and resource (classic candlestick patterns) scoped to a ticker's recent daily bars, and enumerates the exact patterns covered. This clearly separates it from sibling tools like support_resistance_levels, iv_analytics, or stock_history, which do different technical work on the same instrument.

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

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

Usage context is implied by 'on a ticker's recent daily bars' and the research disclaimer, but no explicit when-to-use, when-not, or alternative is named (e.g., no routing versus other technical-analysis siblings). An agent can infer intent but gets no explicit guidance.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds 'Keyless' to clarify that no authentication is required, which is valuable operational context. It also lists the response content, partially compensating for the absence of an output schema.

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

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

The description is two short sentences with no wasted words. The lookup target and returned fields are front-loaded, and the 'Keyless' note is a concise, useful addition.

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

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

For a simple one-parameter, read-only lookup with no output schema, this description is complete: it identifies the source platform, the input semantics, the returned fields, and the authentication requirement. Nothing critical is missing for an agent to invoke it correctly.

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

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

The input schema already documents the single 'name' parameter with an example. Schema description coverage is 100%, so the baseline is 3. The description adds context by specifying 'Rust crate' and 'crates.io', but it does not materially deepen parameter semantics beyond the schema.

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

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

The description uses a specific verb and resource: 'Look up a Rust crate on crates.io', which clearly distinguishes it from sibling package lookup tools like npm_package and pypi_package. It also enumerates the exact returned fields, so an agent knows what this tool provides.

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

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

The description clearly establishes the context for use: any time a Rust crate's metadata from crates.io is needed. It does not explicitly name alternatives or exclusions, but the platform and language are explicit enough to guide selection among package-oriented 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured behavior: it discloses that LiveDataLink does not retain customer watchlists, so the caller must persist the snapshot and drive the schedule itself — important state-management 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?

Three sentences, front-loaded with purpose, then comparison scope, then operational guidance. Every sentence carries distinct load with no repetition or filler.

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

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

With no output schema, the description fully covers return values (unchanged/changed status, severity, field-level changes, next reviewer action) and the persistence/scheduling workflow. Nothing an agent needs to invoke or chain this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by clarifying the snapshot lifecycle: DOT/MC/name are the lookup inputs and previous_snapshot is the prior carrier_vetting result or JSON snapshot returned by an earlier call, which explains how the param relates to the tool's output.

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

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

States a specific verb+resource ('Recheck an existing carrier snapshot') and the exact comparison intent ('identify meaningful changes since the previous check'). This distinguishes it from the initial-vetting siblings like carrier_vetting_score by framing it as a diff against a prior snapshot, and it enumerates the compared fields, so an agent knows precisely 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?

Gives concrete when-to-use context ('call this on a schedule' after storing a snapshot) and implies the prerequisite that a prior result must exist as previous_snapshot. It does not explicitly name a sibling as the alternative for initial vetting, but the operating context is clear.

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

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

Annotations already cover readOnly, idempotent, non-destructive, and openWorld, so the bar is lower; the description still adds real value by disclosing the per-carrier verdict scheme, source coverage and failure reporting, and the analytical-aid disclaimer. It doesn't describe rate limits or latency, but the added context is meaningful.

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

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

Four sentences, front-loaded with purpose, then returns, then usage, then disclaimer. Each sentence carries distinct information and none is filler.

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

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

With no output schema, the description carries the return-value burden and does so fully (per-carrier verdict, coverage, failures, signals, export formats). Parameters are covered by the schema and safety by annotations, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, and both parameters are fully documented there ('1-10 USDOT numbers,' format enum with default). The description merely restates the 10-carrier cap and the format options, adding no syntax or format detail beyond the schema.

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

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

States a specific verb (Vet), resource (batch of up to 10 US motor carriers by USDOT number), and outcome (GO/CAUTION/NO-GO). The 'batch' and 'in one workflow call' framing implicitly distinguishes it from single-carrier siblings like carrier_vetting_score, but no sibling is named explicitly.

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

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

Gives clear usage context: 'screen a broker's candidate list or lane roster,' plus a useful caveat that each carrier is evaluated independently so one failure doesn't hide others. It does not name an alternative tool or state explicit when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuine value beyond them: it discloses that source coverage and failures are surfaced, that a retrieval timestamp is included, and that the output is advisory rather than authoritative. It does not detail pagination or size limits, but for a read-only pack tool this is strong.

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

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

Purpose and scope are front-loaded in the first sentence, with the alternative-tool routing at the end. The middle output enumeration is a dense comma-separated list, but each item is substantive and none is filler.

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

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

With no output schema and no required parameters, the description carries the burden of explaining what comes back - and it does: verdict, evidence, sanctions/court/federal-award checks, source coverage and failures, timestamp, primary-source links, and a follow-up checklist. It also flags the authority limitation. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100% and the schema already documents mc, dot and name, including that dot is the 'preferred exact identifier'. The description's 'Resolve a US motor carrier by USDOT, MC, or legal name' merely restates those fields, adding no format or precedence detail beyond what the schema provides.

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

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

States a specific verb+resource ('Produce an auditable Carrier Vetting Pack for a freight broker'), names the resolution keys, and enumerates the concrete outputs (GO/CAUTION/NO-GO verdict, FMCSA evidence, sanctions checks). It explicitly differentiates itself from sibling carrier_vetting_score as the 'evidence-first companion'.

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?

Names the alternative (carrier_vetting_score) and the exact condition that selects this tool: 'use it when a human reviewer needs to save or forward the record.' It also states the exclusions - it is 'an analytical aid, not a substitute for direct FMCSA insurance and authority 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?

Annotations only cover the safety profile (readOnly/idempotent/openWorld), while the description adds substantial behavioral detail: the exact NO-GO and CAUTION trigger conditions, how unavailable sources are handled, and an explicit 'analytical aid, not a substitute' disclaimer. This is rich disclosure well beyond what the structured fields provide.

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

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

The description is a single dense paragraph, but it is front-loaded (purpose, then inputs, then data sources, then decision rules, then disclaimer) and every sentence carries information. It is on the longer side but the length is justified by the tool's complexity.

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

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

With no output schema, the description fully explains the return shape (GO/CAUTION/NO-GO plus reasons and underlying fields) and enumerates the contributing data sources. For a multi-source analytical tool with annotations already covering safety, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents dot, mc, and name with precedence rules. The description only restates that any of the three identifiers may be given and adds no syntax or precedence detail beyond the schema, so baseline 3 applies.

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

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

States a precise verb+resource+scope: 'Vet a US motor carrier (trucking company) for a freight-brokerage review, in one call.' This clearly distinguishes it from sibling aggregators like carrier_vetting_evidence_pack and carrier_vetting_batch, and from raw-data tools like fmcsa_carrier_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?

Gives clear context (freight-brokerage carrier onboarding) and notes it accepts DOT, MC, or name, plus 'in one call' implying it consolidates several lookups. It does not, however, explicitly name when to prefer siblings such as carrier_vetting_batch or the raw fmcsa_* lookups over this one.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description usefully signals that only metadata plus a source URL is returned (full text lives elsewhere), but it says nothing about not-found behavior, rate limits, or auth requirements.

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

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

One front-loaded sentence with the verb, key, and return fields; the parenthetical field list is compact and every element earns its place. No preamble or filler.

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

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

With no output schema, the description compensates by enumerating the returned metadata fields, including the full-text source URL. It is nearly complete for a single-entity lookup; only edge-case behavior (invalid/unknown id) is unaddressed.

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

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

Single parameter with 100% schema description coverage, including a worked example (11301409, Brown v. Board of Education), so the schema carries the semantics. The description only restates 'by its CAP id' and adds no format or validation detail beyond the schema.

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

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

States a specific verb (Get) and resource (full metadata for a single case) and enumerates exactly which fields are returned, so the agent knows the payload shape before calling. It does not explicitly name or contrast the caselaw_search / caselaw_opinion_text siblings, which is the only thing keeping it from a 5.

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

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

Usage is implied rather than stated: use this when you already hold a CAP id and need the case's metadata. There is no explicit 'when not to use', no pointer to caselaw_search for finding an id or caselaw_opinion_text for the body, and no prerequisite that a CAP id must first be resolved.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior, so the description only needs to add value beyond that. It adds useful behavioral detail: it matches official and parallel citations, tolerates citation variants like '347 U. S. 483', and returns metadata including the CAP id. 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?

Two sentences carry the full necessary meaning: purpose, input examples, matching behavior, output, and downstream use. There is no filler, and the core action 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?

For a one-parameter, read-only lookup with no output schema, the description is complete: it says what input is expected, what matching behavior occurs, what the return value contains, and how the result connects to caselaw_opinion_text. Nothing essential for correct invocation is missing.

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

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

The schema already documents the single citation parameter with an example, and coverage is 100%. The description enriches the parameter meaning by providing additional format examples and explicitly stating that official and parallel citations are matched, which helps the agent understand acceptable 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 opens with a specific verb and resource: 'Resolve a reporter citation ... to the case it identifies.' It also clarifies that it matches official and parallel citations and returns metadata with a CAP id. It does not explicitly distinguish itself from similar siblings like court_citation_resolver or caselaw_search, though the downstream link to caselaw_opinion_text helps.

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

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

The description clearly implies the intended use case: when an agent has a reporter citation and needs the case identity and CAP id for further caselaw operations. It names the downstream sibling caselaw_opinion_text but does not state when-not-to-use alternatives such as caselaw_search, so it stops short of a 5.

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

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

Annotations already cover readOnly, idempotent, openWorld and non-destructive, so the bar is lower, and the description adds real value beyond them: text is fetched live from the public-domain CAP static mirror and is not stored, and the return includes per-opinion authorship. It stops short of noting any rate limits or pagination/truncation behavior beyond max_chars.

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

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

Three sentences with the core purpose front-loaded and no filler; the source-of-data and max_chars details are usefully appended. Tight and well-ordered, though the id-source note partially duplicates the schema.

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

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

With no output schema, the description carries return-shape burden and does so by describing the opinion set and authorship, plus the live-fetch/not-stored nature of the data. For a simple two-param read tool this is nearly complete, missing only explicit truncation behavior when max_chars is exceeded.

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

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

Schema coverage is 100%, so the schema already documents both params (id source, max_chars default 50000 / max 500000). The description's 'Use max_chars to bound the response' and id-origin mention are consistent but add little beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch the full opinion text of a case') keyed to the CAP id, and clarifies it returns each opinion (majority, dissent, concurrence) with author. The 'full text' framing implicitly distinguishes it from caselaw_case_details/caselaw_search, but it never names a sibling explicitly.

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

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

'On demand' and the id-source note (from caselaw_search / caselaw_citation_lookup) hint at the workflow, and 'Use max_chars to bound the response' gives a practical cue. However, there is no explicit when-to-use-vs-alternative guidance for choosing this over caselaw_case_details, so usage is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-structured context: the v1 index only covers the U.S. Reports reporter, a material scope limitation, plus a summary of what is returned (metadata with CAP ids and citations).

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 tight sentences, front-loaded with purpose and filters, then the follow-up action, then the scope caveat. No filler or redundancy.

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

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

No output schema exists, and the description compensates by stating the return shape (case metadata with CAP ids and citations) and the critical index-coverage limitation. Combined with annotations and a fully documented schema, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so all six parameters are documented with examples and bounds in the schema itself. The description names the filter dimensions but adds no syntax, format, or combination rules beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb and resource (search US court opinions) and enumerates the filterable dimensions (case name/keyword, court, jurisdiction, date range). It also distinguishes itself from the sibling caselaw_opinion_text, so an agent can route without opening the schema.

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

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

Explicitly names the alternative and the condition for using it: 'Use caselaw_opinion_text with a returned id to read the full opinion.' That is clear routing, though there is no explicit when-not-to-use guidance or mention of the other caselaw siblings (case_details, citation_lookup).

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety and network profile is covered. The description adds the SoQL reference link and the pass-through nature, but says nothing about rate limits, error behavior on invalid dataset IDs, or result shape beyond the schema's limit cap.

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

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

Three short sentences, front-loaded with the core purpose, then the usage condition, then the reference link. Efficient, though the SoQL URL sentence is a mild redundancy given the schema already names SoQL clauses.

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 generic fallback query tool, the description plus 100%-covered schema and read-only annotations give an agent everything needed to invoke it correctly. No output schema exists, and the description needn't explain return values for a raw SoQL pass-through.

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 all five parameters (including limit default/cap and example clauses) are already documented in the schema. The description only restates that a 4x4 Socrata ID and a where-clause are accepted, adding essentially nothing beyond the structured 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?

States a specific verb (query) and resource (any data.cdc.gov dataset) and explicitly positions itself as the generic fallback against the many curated cdc_* siblings. An agent can tell it apart from the curated tools without opening any schema.

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

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

"Use this when none of the curated tools fit" gives a clear conditional that routes the agent here only as a fallback. It stops short of naming specific curated alternatives, but the alternative category is explicit and unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered externally. The description adds genuine context by disclosing the 12-month rolling aggregation and the underlying dataset, but says nothing about whether counts are provisional/final, coverage limits, or result volume 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?

Three short fragments, purpose and source first, dataset ID second, use case last. There is no filler, though the closing research-framing sentence is the weakest-earning element rather than core invocation 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?

A read-only query tool with a four-hint annotation block, fully described parameters, and no output schema to explain. The description supplies the dataset, the aggregation window, and the analytic niche, which is everything an agent needs to select and call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents limit, indicator, and state_name, including an indicator value example. The description's mention of 'by state and indicator' confirms the slicing dimensions but adds no syntax or accepted-value detail beyond the schema, so the baseline 3 applies.

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

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

Names a specific resource (CDC drug overdose deaths), the two dimensions it is sliced by (state and indicator), the source dataset ID (9j2v-jamp), and the metric form (12-month rolling counts). It does not explicitly distinguish itself from close siblings such as cdc_weekly_deaths_by_state or the generic cdc_dataset_query, which keeps it out of 5 territory.

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?

'Useful for opioid/fentanyl/stimulant policy research and treatment-program siting' gives an audience and a downstream use, implying when the tool applies. However, it never states when NOT to use it, nor points to the sibling that should be used instead (e.g. cdc_dataset_query or cdc_weekly_deaths_by_state), so the routing guidance is only implied.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so safety is covered. The description adds genuinely useful context beyond that: the data is modeled (not raw counts) and comes from a specific CDC dataset id, which matters when interpreting the numbers.

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 tight sentences, front-loaded with the resource and its scope, with no filler or repetition.

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

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

For a read-only query tool with full schema coverage and no output schema, the description covers source, granularity (state and week), and interpretation caveat (modeled estimates). Only the return shape/columns are left unstated, 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 100%, with limit, state, and outcome all documented in-schema including examples. The description adds nothing about parameter semantics, so the baseline 3 is appropriate.

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

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

Names a specific dataset (CDC excess deaths, dataset id xkkf-xrst) and its scope: modeled expected vs observed deaths by state and week. That is enough to separate it from cdc_weekly_deaths_by_state and cdc_leading_causes_of_death, though it never names those siblings explicitly.

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

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

The closing sentence ('Used to estimate true pandemic impact beyond reported COVID deaths') implies an analytical use case, but there is no explicit when-to-use guidance, no prerequisites, and no named alternative for raw death counts versus excess-death estimates.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the upstream dataset identifier (vh55-3he6) and the grain of the return data, but says nothing about default result size, filtering defaults, or rate/coverage caveats beyond what the annotations provide.

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

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

Two tight sentences with the source and the interpretation of ILI both front-loaded; nothing is wasted. It is merely brief rather than richly informative.

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

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

For a three-optional-parameter read-only lookup, the description names the source, the grain, and the returned metric, and the annotations cover safety while the schema covers inputs. Since no output schema exists, the one-line return summary is doing the necessary work; only seasonal or geographic coverage limits are unstated.

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

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

Schema description coverage is 100%, so limit, season, and statename are already documented in the schema. The description restates the state-level grain but adds no syntax, format, or default guidance beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific source (CDC FluView), a specific scope (state-level), and the specific returned metric (weekly ILI activity levels per state), which lets an agent distinguish it from siblings like cdc_weekly_deaths_by_state or cdc_vaccination_coverage. It stops short of explicitly naming those alternatives, so not a 5.

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

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

No when-to-use guidance, no prerequisites, and no routing to or away from sibling CDC tools. The agent must infer applicability purely from the topical subject matter.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds the return shape ('total deaths and age-adjusted death rates per cause per state per year'), which is genuinely useful given there is no output schema, but it says nothing about pagination, defaults, or coverage limits.

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

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

Two tight sentences with the resource and scope front-loaded and no filler. The dataset ID parenthetical is compact and useful rather than wasteful.

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

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

With no output schema, the description does the right thing by sketching the returned measures, and all four parameters are documented in the schema. It is nearly complete; the main gap is any note on row limits or how age-adjusted rates should be interpreted.

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 all four parameters (year, limit, state, cause_name) are already documented with examples. The description only echoes the filtering dimensions ('per cause per state per year') and adds no syntax, allowed-value, or default detail beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb and resource ('NCHS leading causes of death by state') and even cites the source dataset ID (bi63-dtpu), which clearly distinguishes it from cdc_drug_overdose_deaths, cdc_flu_surveillance, and cdc_weekly_deaths_by_state. It stops short of explicitly naming which sibling to prefer for adjacent mortality questions, so it is clear but not sibling-routing.

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 closing phrase 'Useful for chronic disease + injury mortality research' implies a use case but gives no when-to-use vs when-not guidance and names no alternative. For a query tool with several CDC siblings, the routing burden is left entirely to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered without the description. The description adds real value by enumerating the returned fields, which matters since no output schema exists. It does not mention pagination, row limits, or coverage/recency of the underlying dataset, so it stays at minimum-viable on behavior.

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

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

Two sentences, no filler: the first identifies the dataset and covered report categories, the second lists return fields. Everything is front-loaded and each clause carries information an agent would otherwise have to open the schema or a data dictionary to obtain.

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

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

With no output schema, the second sentence's field list is exactly the compensating detail needed, and the annotations cover mutability and idempotency. For a simple read-only filterable dataset query with fully documented parameters, this is close to complete; only dataset coverage/recency and pagination behavior are unaddressed.

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

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

Schema description coverage is 100%, and the schema documents all four parameters (year, limit with default 50 and 1-1000 bounds, state as full name, etiology with examples). The description's mention of date, state, etiology and exposure adds naming color but no semantics beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description names a specific resource (CDC NORS foodborne/waterborne/enteric outbreak reports) with a dataset identifier, which distinguishes it from the generic cdc_dataset_query and from unrelated cdc_* siblings like cdc_flu_surveillance or cdc_drug_overdose_deaths. It also enumerates the returned columns, so the agent knows exactly what the tool yields. The only weakness is that no sibling is named explicitly as an alternative.

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

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

There is no statement of when to use this tool versus alternatives such as cdc_dataset_query or the other cdc_* tools, and no prerequisites or exclusions are given. Usage can only be inferred from the resource name. The agent is left to guess whether this is the canonical path for outbreak data or a fallback to a generic CDC query 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. With no output schema, the description earns credit by disclosing return content (booster + primary series percentages over time), which the structured fields do not provide. It stops short of mentioning pagination or rate limits.

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 tight sentences, front-loaded with the resource and scope, then the return content and a use case. Little waste; the cryptic dataset id is the only slightly opaque element.

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 small read-only query tool with full parameter coverage, safe annotations and no output schema, the description supplies enough return-content context to call it competently. Only the absence of guidance on choosing it over sibling CDC tools leaves 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 100%, so limit, recip_state and recip_county are already fully documented in the schema. The description mentions 'US county' but adds no format or filtering semantics beyond what the schema states, so the baseline of 3 applies.

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

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

States a specific resource (COVID-19 vaccination coverage) and scope (by US county), which clearly separates it from CDC siblings like cdc_flu_surveillance or cdc_drug_overdose_deaths. The unexplained dataset id '(8xkx-amqh)' and noun-phrase phrasing keep it just short of ideal, but an agent knows exactly what data this returns.

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

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

'Useful for public-health gap analysis' implies a use case but gives no explicit when-to-use, when-not-to-use, or comparison against the many sibling CDC/health tools or the generic cdc_dataset_query. Usage must be inferred.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds meaningful context beyond them: the data is 'provisional' (subject to revision) and reported at ISO-week granularity, plus what the response contains. It stops short of noting pagination/row-limit 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?

Three tight sentences, front-loaded with the resource and source dataset, then return shape, then use case. No filler or repetition; each sentence earns its place.

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

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

With no output schema, the description correctly summarizes the return values and notes provisional status. Given rich annotations and full schema coverage, it is nearly complete; the main gap is lack of differentiation from the crowded set of CDC death/cause siblings.

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

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

Schema coverage is 100%, so year, cause, limit, and state are all documented in the schema itself. The description adds only that counts are per state and per ISO week, which is marginal value over the structured fields. Baseline 3 is appropriate.

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

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

Names a specific resource ('CDC weekly provisional deaths by state and cause'), identifies the source dataset (NCHS muzy-jte6), and states the return shape. It is clear, but does not differentiate itself from close siblings like cdc_excess_deaths_covid or cdc_leading_causes_of_death, which an agent would need help distinguishing.

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 offers a use case ('excess-mortality and respiratory-disease seasonality analysis'), which implies when the tool is relevant. However, it gives no explicit when-not-to-use guidance and does not route the agent to any of the many overlapping CDC siblings, leaving selection largely to inference.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint) already declare this is a safe, repeatable, read-only remote lookup, so the description needn't restate safety. The description adds that NAICS filtering is optional, but does not disclose return format, pagination, data vintage beyond the year param, or any CBP-specific caveats. With annotations carrying the safety profile, this is adequate.

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 tight clauses: data source, optional filter, use cases. No filler, no repeated schema content, and the core resource is front-loaded. Every sentence earns its place.

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

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

For a 9-parameter geographic data tool with 100% schema coverage and no output schema, the description covers what the data is but is thin on return shape and level/param interplay. An agent can probably call it correctly from the schema alone, but the description doesn't add much beyond the source name and use cases.

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

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

Schema description coverage is 100%, so every parameter (msa, year, zcta, level, naics, place, state, tract, county) is fully documented in the schema. The description only reinforces that the NAICS filter is optional, adding no syntax, format, or level-dependency detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

Clear verb-less but specific resource statement: 'Business establishments, employment, and annual payroll from County Business Patterns.' An agent knows exactly what data is returned. It does not name a sibling tool (e.g., census_commute_employment or census_income_housing) to differentiate the dataset, but the CBP source naming is specific enough to distinguish it from generic census 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 three use-case tags ('industry research, competitive intel, supply chain analysis') imply when this tool is applicable. However, there is no explicit guidance on when to choose this over census_commute_employment, census_demographics, or cost_of_doing_business_index, and no exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, covering the entire safety profile. The description adds no behavioral context beyond that – nothing about defaults, return shape, or the conditional geography requirements. It contributes only metric scope, which is purpose rather than behavior.

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

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

Two compact sentences, front-loaded with the metric list, no filler. It could be tighter still since the second sentence is effectively a use-case list, but overall it reads efficiently.

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

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

With 8 parameters, only one required, and no output schema, the description is adequate but thin: it does not explain the level-dependent parameter requirements or what the returned figures look like. The rich schema compensates for parameter gaps, but a data-returning tool with no output schema leaves the agent guessing about response structure.

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 all 8 parameters (level enum, state/county/tract/msa/place/zcta codes, year default) are fully documented in the schema itself. The description references 'a US geography' but adds no syntax, hierarchy, or dependency detail beyond what the schema already provides, so the baseline 3 holds.

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

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

The description names the specific data families (labor force, unemployment, commute times, transit usage, work-from-home) and the resource (US geography), so an agent understands it retrieves ACS commute/employment metrics. However, it never distinguishes itself from close siblings like census_demographics or census_income_housing, leaving the agent to infer the split.

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?

Three use cases (site selection, workforce analysis, commercial real estate) imply when the tool is relevant, but no alternatives are named and no when-not guidance is given. The agent must infer routing among the many census_* 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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower. The description adds value beyond them by disclosing the data provenance ('Source: ACS 5-year'), which tells the agent these are 5-year estimates, and by enumerating the returned demographic fields since no output schema exists.

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

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

Two tight sentences, front-loaded with the subject/scope statement, followed by the concrete returned fields and the source. No filler or repetition.

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

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

With no output schema, the prose enumeration of returned counts and median age is genuinely necessary and present, and the source/vintage is disclosed. The main gap is that the hierarchical geography-level mechanics (which level pairs with which code parameter) are left entirely to the 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 description coverage is 100%, so all eight parameters (level, state, county, tract, place, msa, zcta, year) are already documented in the schema, including which are required per level. The description adds no parameter-level detail beyond that, so the baseline 3 is correct.

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

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

States a specific resource (race, ethnicity, age breakdown) and scope (US geography), plus the data source, so an agent can tell it apart from census_population or census_income_housing by subject matter. It does not, however, explicitly name or contrast any sibling tool.

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

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

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as census_population for total counts or census_geography_lookup for resolving place names. The requirement to supply a geography level is only implicit in the phrase 'for a US geography'.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds some behavior (substring matching applies only to state) but says nothing about return format or match ranking, so it adds modest value on top of the structured data.

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

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

Two tight sentences with zero waste; the core action is front-loaded and the usage routing comes second. Every clause earns its place.

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

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

For a simple, annotation-covered lookup with no output schema, the description is nearly sufficient: it conveys what is returned (FIPS codes) and how to supply input. The only gap is lack of detail on output shape, which is minor given the tool's narrow scope.

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

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

Schema description coverage is 100%, so the schema already documents query, level, and limit. The description restates the accepted query formats (state name, 2-letter code, 5-digit ZIP) and adds that substring matching is state-only, which is marginal beyond what the schema already conveys.

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

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

States a specific verb and resource ('Look up Census FIPS codes by name') and clearly positions itself against the many census_* data siblings by framing itself as the code-resolution prerequisite. An agent can tell what it does and where it sits in the family without opening the schema.

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

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

Explicitly says when to reach for it: 'Use this to find the FIPS codes needed by other census_* tools,' which gives a clear call condition and dependency role. It stops short of naming exclusions or when-not-to-use, but the intended context is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds practical value by enumerating the returned measures, but says nothing about data vintage/ACS coverage caveats, rate limits, or suppression of small geographies.

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

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

Front-loaded with the actual data measures in the first sentence, which is the most useful part. The trailing sentence about 'real estate AI' is weakly informational but short enough not to bloat the definition.

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

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

There is no output schema, so the description carrying the enumerated metric list is valuable for telling the agent what it will receive. With 8 parameters and a geography-hierarchy requirement, and annotations covering the safety semantics, this is reasonably complete, though geography-level prerequisites and data vintage are left entirely to the 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 description coverage is 100% with per-parameter docs and an enum for 'level', so the schema already carries parameter semantics. The description adds no parameter-level detail (e.g. how level conditions the required msa/zcta/place/county params), so the baseline 3 applies.

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

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

The description names a concrete resource set (median household income, per capita income, housing units, occupancy, home value, rents) for 'a US geography', so an agent knows exactly what data comes back. It does not, however, name or distinguish itself from overlapping siblings such as realestate_home_values, realestate_rents, or census_demographics, which an agent would have to resolve by trial.

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?

'Used for real estate AI, market analysis, location-based pricing' implies a usage context, so the intent is inferable. But it gives no when-to-use/when-not guidance and never mentions the closely overlapping census and realestate siblings, leaving selection ambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds useful return-field information (total, male, female, median age) but omits behavioral caveats important for census data, such as ACS vintage or margin-of-error limitations.

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

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

Three short sentences with zero waste; the key capability and return fields are front-loaded and easy to scan.

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

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

Given eight parameters, no output schema, and annotations that cover read-only semantics, the description does a good job of stating purpose and return fields. It leaves some gaps on data vintage and limitations, but the schema handles parameter-level detail adequately.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters, including the level enum and required identifiers. The description lists geography types that map to the enum but adds no syntax or format detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Get total population for a US geography') and enumerates supported geography levels. It clearly describes what it returns (total, male, female, median age), but does not differentiate itself from closely related siblings such as census_demographics or census_business.

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

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

The phrase 'Used for market sizing, location intelligence, demographic analysis' implies usage contexts, but there is no explicit when-to-use / when-not-to-use guidance and no named alternative to route between this and the other census_* 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 declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds that results are aggregate counts by a single facet, but it does not disclose output structure, limits, sorting, or other behavioral nuances. There is no contradiction 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 two sentences with no filler: it opens with a precise statement of what the tool does, enumerates the facet options, and closes with relevant use cases. Every sentence contributes useful information.

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

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

For a two-parameter read-only aggregation tool with a complete schema and safety annotations, the description is largely sufficient: it names the facets, describes the output concept (aggregate counts), and gives practical use cases. Since there is no output schema, a slightly more explicit description of the response shape or ordering would make it fully complete, but this is a minor gap.

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

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

The input schema already documents both parameters fully, including an enum for facet and a description for company, so schema coverage is 100%. The description reinforces the meaning of the facet parameter by listing valid values and stating the use cases, but it does not add substantial semantic detail beyond the schema.

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

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

The description states a specific verb and resource ('Aggregate complaint counts') and enumerates the exact allowed facets, making the tool's function immediately clear. It is clearly distinguishable from sibling tools like cfpb_complaint_detail, cfpb_search_complaints, and cfpb_complaint_trends because it focuses on single-facet aggregation rather than individual records, search, or time trends.

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

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

The description provides concrete use cases ('ranking companies by complaint volume' and 'finding the most common issue categories'), which gives useful context for when to invoke it. However, it does not explicitly mention alternatives or exclusion conditions, such as when to prefer cfpb_complaint_trends or cfpb_search_complaints instead.

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, idempotentHint, and non-destructive behavior. The description adds useful context beyond annotations by disclosing that the full record includes the narrative only 'if consented,' which is a meaningful behavioral caveat for a complaint detail endpoint.

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 two short sentences with no filler. The main action and resource are front-loaded, and the conditional narrative detail is stated efficiently in the second sentence.

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

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

For a simple single-ID lookup tool with safe annotations, the description is largely complete: it names the required parameter, the return type ('full record'), and a key conditional field ('narrative if consented'). It does not describe error/not-found behavior, but that is a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100% and the single parameter is already described as 'CFPB complaint ID.' The tool description adds no additional format, source, or lookup semantics beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description clearly states a specific verb ('Fetch'), a specific resource ('a single CFPB complaint'), and the lookup key ('complaint_id'). It also distinguishes itself from sibling search/aggregation tools by emphasizing 'single' and 'full record'.

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 conveys clear usage context: use this when you have a complaint_id and need the full individual record. It does not explicitly name alternatives or when-not-to-use conditions, so it falls short of a 5, but the intended use is evident.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds no behavioral context such as data freshness or rate limits, which is acceptable given the annotation coverage but leaves the definition at a minimum viable level.

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 that are front-loaded with purpose and then enumerate lens and interval options. Every sentence earns its place with no redundant or filler text.

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

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

For a 7-parameter tool with no output schema and rich schema descriptions, the description covers the core lens semantics and interval choices. It omits details about date-range filters and trend_depth, but those are documented in the schema, so the description is adequately complete.

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

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

Schema coverage is 100%, so all parameters are documented. The description goes beyond the schema by explaining what each lens value shows (overview, product, company, issue), which adds meaningful semantic context for the required parameter.

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

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

The description states a specific verb and resource: 'Time-series trends of complaint volume.' It clearly distinguishes the tool's purpose, but does not differentiate it from siblings such as cfpb_complaint_aggregations or cfpb_state_complaints.

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 lens options and interval choices, but gives no guidance on when to use this tool versus alternatives. There is no mention of appropriate contexts, exclusions, or sibling tools to prefer.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: the dataset scope (4M+ complaints since 2011) and the return content (metadata plus public narratives when available), which helps the agent anticipate partial narrative coverage.

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

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

Two tight sentences with zero waste: purpose and dataset scope first, filter dimensions and return content second. Front-loaded and appropriately sized for a search 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?

With no output schema, the description carries the burden of return-value explanation and does so adequately ('complaint metadata plus public narratives when available'). Combined with 100% schema coverage of all 9 parameters, an agent has what it needs; only pagination semantics are left entirely to the 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 description coverage is 100%, so every parameter is already documented in the schema. The description echoes the filter dimensions (free-text, company, product, state, date range, narrative-presence) without adding syntax, format, or default details beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Search) and resource (CFPB Consumer Complaint Database) with scale context (4M+ complaints since 2011). It does not differentiate itself from close siblings like cfpb_complaint_aggregations, cfpb_complaint_trends, or cfpb_complaint_detail, so an agent must infer the distinction.

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 enumerates the filterable dimensions, which implies how the tool is used, but gives no explicit when-to-use or when-not guidance and names no alternative for aggregation, trend, or single-complaint retrieval. Usage is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds that the output consists of counts and percentages per state, but it does not clarify what the percentages are relative to, how missing states are handled, or how date-range bounds behave. This is acceptable but minimal.

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 two sentences with no filler. The first sentence states the core function and output, and the second provides a concrete use case. Every phrase earns its place and the most important information is front-loaded.

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

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

For a tool with no required parameters and no output schema, the description gives a reasonable high-level understanding of return values and filters. However, it does not specify the output structure, whether all states are always returned, or how this tool differs from nearby CFPB siblings, leaving some ambiguity for an agent navigating a large tool catalog.

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

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

Schema description coverage is 100%, so the schema already documents product, date_received_max, and date_received_min. The description only restates that there is an optional product filter and date range without adding deeper semantics such as allowed product values or date-format constraints beyond what the schema already says.

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 returning complaint counts and percentages per US state, with optional product and date filters. This is specific enough to distinguish it from generic complaint search tools, though it doesn't explicitly name or differentiate from sibling aggregation tools like cfpb_complaint_aggregations or cfpb_complaint_trends.

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 offers a clear use case ('state-level financial-consumer risk maps'), which implies when this tool is appropriate. However, it gives no explicit guidance on when not to use it or which sibling tool to prefer for other aggregation styles, such as national or time-series breakdowns.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral details beyond that: it returns up to 10 suggestions, matches partial input, and produces values suitable for a specific sibling parameter. This is useful context, though it does not reveal ordering, matching rules, or empty-result behavior.

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

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

Two sentences with no wasted words. The core behavior and result limit are front-loaded, and the downstream usage note is concise and actionable.

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

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

For a one-parameter autocomplete tool with strong safety annotations and no output schema, the description provides the essential return-value information (up to 10 suggestions) and integration guidance. It is nearly complete; minor details like whether suggestions are full names or formatted strings could be added, but nothing critical is missing.

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

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

The schema already documents the only parameter 'text' as 'Partial company name' with 100% coverage. The description reinforces the partial-input concept but adds little meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific action ('auto-complete company names') and resource ('company names'), and specifies the output behavior (up to 10 suggestions matching partial input). It also distinguishes itself by pointing to its intended downstream consumer, cfpb_search_complaints, so an agent can tell it apart from complaint-search siblings.

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

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

The description gives explicit context: use this tool to generate exact values for cfpb_search_complaints' company parameter. This effectively tells the agent when and why to use the tool, though it does not explicitly state when not to use it or name alternative suggestion/fuzzy-match 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 establish read-only, idempotent, non-destructive, open-world behavior. The description adds a genuine boundary the annotations cannot express: it compares published aggregates only and does not recommend trades, plus it enumerates returned fields (codes, dates, long/short/net, open interest, ranking, provenance) since no output schema exists.

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

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

Front-loads the verb, resource, and cardinality in the first sentence, then use cases, then the boundary. Four sentences with no filler; the return-field enumeration is justified because no output schema is provided, though it is the longest and least critical clause.

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 scope, cardinality, cross-parameter coupling, example intents, return contents, and an advisory boundary. With no output schema, the description takes on the job of describing results and does so; nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic coupling beyond the schema: all compared markets must share one consistent report family, scope, and trader category, which explains why report_type/category are single scalars applied across the array rather than per-market. It also restates the 2-8 bound as a hard constraint.

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

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

States a specific verb (compare) and resource (latest reported CFTC COT position) with an explicit cardinality bound (two to eight contract markets). This cleanly separates it from the sibling cftc_cot_latest (single market) and cftc_cot_history (time series) without needing to name 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?

Gives two concrete triggering scenarios ('compare managed-money positioning in oil, gold, and copper', 'which selected market has the largest commercial net position?'), which tells the agent exactly what class of question this answers. It does not, however, explicitly name alternative tools or state when not to use it (e.g. for a single market, use cftc_cot_latest).

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 readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses that all hosted views are aggregated together, that incompatible family classifications are explicitly preserved, that output is provenance-backed, and that the data is not real-time. No misleading claims.

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, front-loaded with the core operation and followed by output contents, usage examples, and caveats. Every sentence carries information, though the middle sentence about preservation of family classifications is dense and could be tightened.

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

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

With no output schema, the description does the work of describing the pack's contents and its provenance framing, plus a clear data-freshness caveat. It is nearly complete for a two-parameter read-only aggregation tool; only explicit routing versus sibling COT tools is missing.

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

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

Schema description coverage is 100% and both parameters (market, response_format) are fully documented with constraints and enum values. The description only implies the single-market scope but adds no syntax or format guidance beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb (combine) and resource (all hosted official CFTC COT report-family and scope views) scoped to one contract market, and describes the output contents (open interest, largest absolute category net, preserved family classifications). It distinguishes itself from single-view siblings by emphasizing aggregation of 'all ... views,' but never names the concrete alternatives (cftc_cot_latest, cftc_cot_history, cftc_cot_compare), so differentiation is inferred rather than explicit.

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

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

Provides concrete invocation examples ('build a COT evidence pack for gold', 'show every CFTC positioning lens for crude oil') and states the framing ('designed for research synthesis') plus exclusions ('not real-time data, a forecast, or trading advice'). It gives clear context for use but does not explicitly say when to prefer this over the sibling single-view tools.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real context beyond that: the payload fields returned (long, short, spreading, net, changes, percentages, open interest, source ids, provenance), the bounded nature of the history, the enforcement of report-family categories, and a 'not trading advice' caveat. No auth or rate-limit detail, but that is a minor gap given annotation coverage.

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

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

Three sentences, front-loaded with the core verb and resource, then payload contents, then usage examples. The middle field-list is somewhat dense but each item is informative. No filler or repetition of the title.

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

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

With no output schema, the description correctly takes on the burden of describing the return payload (net, open interest, provenance, pagination). Combined with 100% schema coverage and annotations covering safety, an agent has nearly everything needed; only explicit sibling routing is missing.

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

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

Schema description coverage is 100% across 9 parameters, so the schema already documents market, report_type, category, scope, limit/offset, dates and response_format in detail. The description restates the filtering dimensions in prose ('report family, scope, and trader category') without adding syntax or format guidance beyond the schema, so the baseline of 3 is appropriate.

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

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

The description gives a specific verb and resource: 'Return a bounded weekly history for one CFTC contract market, report family, scope, and trader category.' The time-series framing implicitly separates it from cftc_cot_latest and cftc_cot_compare, but neither sibling is named, so an agent must infer the boundary from the tool names alone.

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

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

Concrete use cases are supplied ('managed money net positions in crude oil over time', 'commercial gold COT history', 'a reproducible positioning chart'), which clearly signals when this tool applies. However, there is no explicit when-not or routing statement toward cftc_cot_latest/compare/search, so the agent gets context but no exclusions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely useful behavioral context beyond that: it enumerates the returned content (open interest, long/short/spreading, net arithmetic, percentages, trader counts, report date, provenance) and warns that these are delayed aggregate positions, not a trade signal. This exceeds the annotation burden.

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

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

Front-loaded with the core action, followed by a compact enumeration of returned fields and a closing caveat. Every sentence carries weight, though the returned-field list is fairly dense and could be trimmed, keeping it just short of optimal.

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

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

With no output schema, the description usefully enumerates what is returned, and annotations cover the safety profile, so an agent has enough to invoke correctly. The main gap is the absence of explicit routing among the four cftc_cot_* siblings, which would round out 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 description coverage is 100% and the response_format enum is fully documented in the schema, so the description need not carry parameter detail. It adds no further param syntax or format nuance, which is the correct baseline-3 situation when the schema does the heavy lifting.

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

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

States a specific verb (Return) and resource (latest official CFTC COT position snapshot for one contract market), with the word 'latest' implicitly distinguishing it from the cftc_cot_history sibling. It does not explicitly name or contrast with the sibling tools (compare, history, evidence_pack), so it stops short of full differentiation.

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

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

Two concrete usage examples ('latest managed-money positioning in crude oil', 'show current COT categories for gold') give clear positive context for when to call it. However, with four closely related cftc_cot_* siblings, there is no explicit when-not-to-use or routing to the alternative (e.g., history vs compare). Usage is implied rather than fully guided.

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 readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description contributes real context beyond that: it identifies the source as a self-hosted official CFTC snapshot, mentions snapshot provenance and pagination in the return, and states the scope restriction. It stops short of detail on how the snapshot is refreshed or how provenance is exposed.

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, front-loaded with the verb and scope, then the return inventory, then usage examples and the boundary clause. The return list is long but each item is informative, so little is wasted.

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

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

No output schema exists, so the description must describe returns, and it does so thoroughly (codes, names, commodity/exchange labels, report families, scopes, latest date, pagination, provenance). Combined with a fully documented 6-param schema and complete annotations, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, including enum values and defaults, so the schema carries the parameter burden and the baseline is 3. The description adds only thematic context ('available report families and scopes'), not syntax or format guidance beyond what is already documented.

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

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

States a specific verb (search) and resource (CFTC contract markets) bounded to a self-hosted official COT snapshot, and enumerates exactly what is returned (codes, names, labels, report families, scopes, latest date). It also carves out the boundary ('aggregate US futures and options markets only; not quotes or prices'), separating it from price/quote siblings.

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

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

Gives concrete when-to-use examples ('find the CFTC code for gold', 'which COT markets cover crude oil?') and names the workflow position ('resolve an identifier before a history call'), routing the agent toward cftc_cot_history. The 'not quotes or prices' clause functions as an explicit when-not.

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 readOnly, idempotent, non-destructive; description adds data source, keyless access, graceful missing-data behavior, and a caveat that results are not an SDS. This complements the annotations 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?

Three sentences, each containing only necessary information: what it returns, how missing data is handled, and a safety caveat. No filler or redundancy.

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

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

For a single-parameter, read-only lookup, the description covers input format, output content, missing-data behavior, and usage caveat. No important operational detail is missing.

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