LiveDataLink

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 cover the read-only/idempotent/non-destructive safety profile, so the description's added value is its disclosure of return behavior: sorted high-to-low, exact unit, missing-value evidence, GeoFIPS, source hash, and attribution. With no output schema, this materially helps the agent understand what it will receive.

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?

Core action is front-loaded in the first sentence, followed by return details and example queries. It is slightly long with three quoted examples, but each sentence carries distinct information (capability, returns, routing/exclusion).

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 compare tool with no output schema, the description enumerates the return payload (sorted values, unit, missing-value evidence, GeoFIPS, source hash, attribution) and clarifies the multi-state scope. 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 all four parameters are documented, and the description's '2–8 states' and 'one indicator' clauses are consistent with the schema rather than adding new syntax. Baseline 3 is appropriate when the schema already 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 (compare) plus the resource (one official BEA SASUMMARY annual indicator) and scope (2–8 states or the United States, exact year). The multi-state comparison framing clearly distinguishes it from the single-state profile/history/trend BEA siblings 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?

Provides concrete when-to-use examples ('compare 2024 Texas and California GDP', 'which of these states had higher 2023 per-capita income?') and an explicit exclusion ('does not rank all states unless they are explicitly supplied'). It does not name the alternative BEA siblings (e.g. bea_state_economic_history/trend), so routing relies on 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the description focuses on disclosure of output shape: canonical names, definitions, units, coverage, pagination, evidence hash, and attribution. That adds real context beyond the annotations, though it says nothing about rate limits or result-size 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, front-loaded with what is searched, then returns, then usage, then scope — logical and waste-free. The return-field enumeration is long but justified given there is no output schema, though it slightly buries the routing guidance.

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

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

With no output schema, the description carries the return-value explanation and does so thoroughly, plus it delineates data coverage boundaries and the downstream hand-off to a history call. An agent has enough to decide and invoke correctly.

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

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

Schema description coverage is 100% and all four parameters are documented there, so the baseline is 3. The description adds no syntax, default, or format guidance for limit/offset/query/response_format 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 (Search) and resource (the 15 indicators in the BEA SASUMMARY annual state snapshot), and explicitly bounds scope. It differentiates from siblings by noting this resolves an indicator for a later 'history call', pointing at bea_state_economic_history rather than the compare/profile/trend 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 trigger phrases ('what BEA state measures are hosted?', 'find regional price parity') and a clear sequential use case (resolve an indicator before a history call). It also states an exclusion ('not the full BEA API or industry detail'), though it names no sibling tool explicitly, so routing is guided but not fully explicit.

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

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

Annotations already cover read-only, idempotent, open-world and non-destructive traits. The description adds real value beyond them: it discloses that only published aggregate annual estimates are returned and that 'BEA can revise prior vintages', which is a meaningful data-stability caveat an agent should know.

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 dense sentences, front-loaded with what is returned, then examples, then the estimate/revision caveat. No filler, though the returned-field enumeration is somewhat list-like.

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, and the description compensates by enumerating expected return fields (exact value, unit, state GeoFIPS, pagination, source update date, evidence hash, attribution) plus the revision caveat. Together with full schema coverage this is largely complete for a history-query 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 each of the 7 parameters documented inline (limit, offset, year bounds, geography formats, indicator slugs). The description adds little parameter-level syntax beyond the 'one geography/one indicator' framing and a mention of pagination, so the schema does the heavy lifting — baseline 3.

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

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

The first sentence states a specific verb and resource ('Return bounded annual history') scoped to exactly one official BEA SASUMMARY state or U.S. indicator. The scoping ('one ... indicator', 'annual') implicitly separates it from siblings like bea_compare_states and bea_state_economic_trend without needing to open 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?

Concrete user-query examples ('Texas real GDP since 2018', 'California per-capita income history', 'US employment by year') give a strong sense of the intended invocation context. There is no explicit when-not guidance or named alternative tool, so it falls 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 non-destructive, so safety is covered. The description adds genuine behavioral context beyond that: values carry heterogeneous years and units because source update calendars differ, and results are aggregate estimates, not forecasts or investment advice — a useful scope caveat an agent would not get from annotations alone.

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

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

Front-loaded with the core action and indicator coverage, then trigger examples, then caveats; every sentence contributes something. It is a dense three-sentence block, but nothing is redundant with the schema or annotations.

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, three-parameter tool with full schema coverage, no output schema, and complete annotations, the description supplies everything left: indicator coverage, the heterogeneous year/unit behavior, intended use cases, cross-source composition, and the estimate/not-advice disclaimer.

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 formats (name, USPS abbreviation, GeoFIPS, US) and the as_of_year semantics are already documented in the schema; the description only restates the 'one state or the United States' scope. Baseline 3 applies when the schema carries parameter meaning.

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

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

States a specific verb and resource — 'Build a compact official BEA annual economic profile' — and scopes it to one state or the US across all 15 hosted SASUMMARY indicators. The 'across all 15 indicators' framing implicitly separates it from the search/history/trend BEA siblings, but no sibling is ever named, so the differentiation is inferred rather than stated.

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 a composition scenario with Census, BLS, SBA, FDIC, and housing data, which is strong context for selecting it. However, it never states when NOT to use it or names bea_state_economic_trend / bea_state_economic_history / bea_compare_states as the alternatives for those 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 declare the safe read-only/idempotent profile, so the bar is lower; the description still adds real context by disclosing the returned evidence (vintage, caveats, CAGR-only-when-meaningful) and the point-in-time semantics of as_of_year excluding future observations from a historical calculation.

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: operation first, outputs second, usage examples third. The output enumeration is slightly listy but each clause carries information; little waste.

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

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

No output schema exists, so the description appropriately enumerates the return components (observations, changes, CAGR, units, vintage, caveats) and covers indicator, geography, and as-of-year intent. Complete enough to call correctly, though it is silent on source coverage limits beyond the as_of_year note.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema for as_of_year, explaining its purpose (preventing future observations from entering a historical calculation), which the schema only describes as a four-digit 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 precise operation ('Calculate prior-observation and exact five-year changes') on a well-scoped resource ('one official BEA SASUMMARY state indicator'). The single-indicator scope plus the enumerated outputs (component observations, absolute/percent changes, CAGR, units, vintage) make it distinguishable from multi-state siblings like bea_compare_states.

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 trigger examples ('five-year Florida GDP trend', 'how has Ohio employment changed?', 'California real per-capita income growth') make the intended use clear. It does not, however, state when to prefer the sibling tools (e.g. bea_state_economic_history or bea_state_economic_profile) or any 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?

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 establish read-only, idempotent, and non-destructive behavior. The description adds useful context beyond those annotations: no API key is needed and the result is a monthly time series. It does not mention possible data revisions or lags, but the annotation-covered safety profile lowers the burden and the added details are 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?

The description is three focused sentences: a scoped subject, a concise indicator list, and a useful return/auth note. Every sentence earns its place and the most important identifying 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 simple read-only tool with three optional parameters and no output schema, the description conveys the domain, supported indicators, monthly frequency, and keyless access. It could specify the exact time-series shape or units, but it is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with all three parameters already documented including defaults and the full indicator enumeration. The description restates the indicator list but adds no extra semantics such as date formats, units, or interactions between start_year and 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?

The description clearly identifies the data source (Bureau of Labor Statistics), the domain (US labor and price statistics), and the supported friendly-name indicators. It lacks an explicit action verb like 'get' or 'fetch' and does not explicitly distinguish itself from the sibling bls_series tool, so it falls just 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?

There is no explicit guidance about when to use this tool versus alternatives like bls_series or FRED tools. The phrase 'by friendly name' and the indicator list imply the use case, but the description never states when not to use it or what to use instead for raw BLS series or different datasets.

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 and idempotentHint, and the description's 'Fetch' aligns as a safe read operation. The description adds no behavioral caveats such as output format, rate limits, or year-range constraints, so it only mildly extends what annotations already 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 sentences with the action and example front-loaded, followed by the exact-ID selection criterion. No filler, fluff, or redundant restatement of schema fields.

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 fetch with one required parameter and clearly documented optional years, selection and invocation are well covered. With no output schema, the response shape is left unstated, but the description still provides enough for correct tool usage.

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

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

Schema description coverage is 100%, with series_id, start_year, and end_year already described. The description repeats an example ID also found in the schema and does not clarify year range behavior, so it meets the baseline without adding meaningful parameter insight.

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 'Fetch any BLS time series by its raw series ID', which is a specific verb, resource, and exact input. The examples and the 'when you know the exact BLS series ID' clause distinguish it from lookup or 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?

It explicitly identifies the right condition: use when the exact BLS series ID is known. It does not name sibling alternatives or provide a when-not, so exclusions are 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 that the tool is read-only, idempotent, and non-destructive. The description adds value by disclosing the concrete return fields, including the notable 'whether its full text is indexed here' behavior, which is not inferable from the input schema. It does not cover not-found or error behavior, but the annotation coverage lowers that burden.

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

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

The description is a single front-loaded sentence with the field list in a parenthetical. There is no filler, no repetition of schema details, and every phrase contributes to understanding what the tool returns.

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-parameter lookup with strong annotations, the description is complete: it identifies the required input and the full set of returned metadata fields. Since there is no output schema, the description appropriately carries the return-value information needed by the 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?

The input schema already documents gutenberg_id with 100% coverage and a concrete example ('84 (Frankenstein)'). The description only restates that the parameter is a Project Gutenberg id and adds no additional syntax or format details, so the baseline score 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 states a specific verb and resource: 'Get full catalog metadata for a single book by its Project Gutenberg id.' It enumerates the exact metadata fields, making it clearly distinguishable from sibling tools like book_search, book_get_text, and book_fulltext_search.

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

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

The description makes the usage context clear: use this when you already have a Gutenberg id and need catalog metadata for one book. It does not explicitly name alternatives or exclusions, but the 'single book by id' framing is sufficient to differentiate it from search and text-retrieval 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 establish read-only, idempotent, non-destructive behavior. The description adds useful context beyond annotations: the corpus is indexed public-domain books, results include title/author/snippet, and search can be narrowed to one book. 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?

Three sentences with the action verb front-loaded ('Search INSIDE...'). The phrase 'headline feature' adds minor positioning context, but every sentence otherwise earns its place without redundancy.

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

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

With no output schema, the description covers the return shape (matching passages with title, author, snippet) and the scope of the corpus. It does not mention no-results behavior or pagination, but limit defaults are documented in the schema and the overall behavior is clear.

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

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

Schema description coverage is 100%, and each parameter already has a clear description, including examples for query. The description only restates the gutenberg_id restriction role and adds little semantic value beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Search INSIDE the indexed corpus of top public-domain books') and the exact output ('matching passages, each with the book title, author, and a snippet'). It clearly distinguishes itself from siblings like book_search and book_get_text by emphasizing passage-level full-text search.

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

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

The description makes the use case explicit: find where a passage or phrase appears across books, with optional restriction to a single book via gutenberg_id. It does not name alternative sibling tools or state when not to use it, but the context is clear enough for an agent to select appropriately.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds meaningful behavioral context beyond those annotations: results are paginated by passage, and non-indexed books return a gutenberg.org URL instead of text, which is an important non-obvious fallback 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 concise sentences: the first states the core operation, the second gives the pagination pattern, and the third covers the fallback case. No filler or repetition of schema details.

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

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

Without an output schema, the description still explains both return modes: paginated text passages for indexed books and a plain-text URL for non-indexed books. It is sufficient for correct invocation, though a bit more detail about what constitutes a 'passage' would make it fully self-contained.

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 all three parameters at 100% coverage, so baseline is 3. The description adds value by explaining the pagination relationship between from_seq and max_passages and by tying gutenberg_id to the indexed-versus-URL fallback behavior, which the schema alone does not convey.

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

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

The description names a specific verb and resource: 'Return the full text of an indexed book by Gutenberg id'. It also clarifies the pagination model and the fallback behavior for non-indexed books, which distinguishes it from search-oriented siblings like book_fulltext_search and book_details.

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 direct usage guidance: 'Use from_seq + max_passages to page through it' and explains the alternate path for unindexed books by returning a URL. It does not explicitly name sibling alternatives or state when not to use this tool, but the context is clear for this retrieval action.

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 read-only, idempotent, and non-destructive behavior, so the description adds useful behavioral context beyond them: live Gutendex source, ranking by keyword relevance then download popularity, and the exact fields returned. This gives the agent a strong sense of what the tool will do and what to expect.

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

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

The description is three dense sentences with no filler. The core search scope and filters come first, followed by ranking behavior, return fields, and the sibling-tool routing at the end. 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?

There is no output schema, so the description compensates by listing the returned fields. It also explains scope, source, ranking behavior, and the relevant alternative tool. For a search tool with optional filters and safety annotations, this is complete enough for an agent to select and 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?

Schema description coverage is 100%, with each parameter already documented with examples and defaults. The description mostly restates that query accepts title/author/subject keywords and that author, subject, and language are optional filters, without adding significant new parameter-level meaning beyond the schema.

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

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

The description states a specific action ('Search the full Project Gutenberg catalog') with a clear resource, scope, and method (Gutendex). It explicitly distinguishes itself from book_fulltext_search by naming that sibling and clarifying the different search domain (metadata vs full text).

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

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

The description explicitly tells the agent to use book_fulltext_search when the task is to search inside book text, providing a clear routing rule. It also characterizes book_search as a live catalog search, so an agent can infer when this tool is appropriate versus sibling tools.

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

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

Annotations already 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: it is a heuristic research signal, not investment advice; all thresholds are tunable parameters; and the per-symbol return fields are enumerated. No contradiction with annotations 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?

The description is three sentences with zero filler: strategy conditions, output format, tunability, and disclaimer all fit naturally. The core action is front-loaded, and every sentence carries distinctive information. This is appropriately dense rather than bloated.

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?

Even though there is no output schema, the description lists the exact return fields and explains the strategy criteria, threshold tunability, and heuristic nature. All six parameters are documented in the input schema, and the intended ticker scope (US, daily bars) is explicit. An agent has enough information to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 because the schema already documents each parameter. The description adds extra meaning by explicitly labeling rsi_threshold, ma_period, proximity_pct, and lookback_days as tunable thresholds and explaining that calibration is achieved through parameter changes. This links the parameters directly to the strategy logic 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 states a specific action ('Screen one or more US tickers') and a clearly defined resource/strategy: a mean-reversion 'bounce' setup with explicit conditions (near support/MA, RSI oversold and turning up, bullish latest candle, volume at/above average). It also specifies the exact output shape, which leaves no ambiguity about what the tool does. The definition is distinctive enough to be separated from siblings like candlestick_signals or support_resistance_levels without reading their schemas.

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

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

The description gives clear context for when to use the tool: when screening US tickers for daily-bar mean-reversion bounce setups. It does not explicitly name alternative tools or state when not to use it, but the strategy-specific wording makes the intended use obvious. It stops short of a 5 because no explicit 'use X instead when...' guidance is provided.

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 behavior心的的，但描述 adds valuable context: provenance-backed results, separation of modes, and a guarantee that incompatible measures are never summed ('never fabricates a total'). It also clarifies completeness reporting and percent change, which the agent could not infer from annotations alone.

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

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

Three sentences with zero waste: the first states the core deliverable, the second details the output composition, and the third gives runtime examples and an exclusion. It is front-loaded with the main purpose and 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 no-output-schema tool, the description covers the key semantic ground: what it returns (evidence pack with totals, completeness, percent change), how data is kept separate, provenance, and what it deliberately does not do. It gives the agent enough to decide on invocation, interpret results, and set expectations about data integrity.

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% because all three parameters (port, response_format, trailing_months) have descriptions. The description adds no new parameter-level detail beyond schema descriptions—for example, 'trailing_months' is mentioned as a default but not elaborated. The baseline 3 is appropriate since the schema already does the heavy lifting.

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

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

The description uses a specific verb ('Combine'), resource ('every available official BTS crossing measure'), and scope ('one land-border port'), making it clear this is an aggregation pack. It distinguishes itself from BTS siblings by emphasizing a single port with current-versus-prior comparison dashboards and explicitly excludes congestion/wait-time measures.

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 like 'build a border activity pack for Laredo' and 'what changed at Otay Mesa?', plus a clear exclusion ('not a congestion or wait-time measure'). However, it does not explicitly name sibling tools like bts_transport_compare_ports or bts_transport_border_trend and explain when to choose them instead, leaving some inference required.

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

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

The description goes beyond annotations by disclosing the source (self-hosted snapshot), the output contents (exact month, crossing count, stable port identity, pagination, source hash, provenance), and the counting semantics (inbound events). The annotations already establish read-only/idempotent/destructive false, and the description adds practical expectations without contradicting them.

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

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

Three sentences – a precise purpose, a usage trigger phrase, and a clarification of the measure unit. All high-signal, no filler; the most important capabilities are front-loaded.

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

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

The tool has 7 parameters and no output schema, but the description enumerates all key output fields (exact month, crossing count, stable port identity, pagination, source hash, provenance) and gives concrete invocation examples. It doesn't specify error/runtime behavior, but the annotations plus open-world hint make it sufficiently complete for an agent to invoke correctly.

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

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

With 100% schema coverage, the schema already documents every parameter. The description adds contextual meaning: 'bounded monthly history' implies limit/offset behavior, and 'one consistent crossing measure' clarifies that measure parameters must not be combined. It doesn't repeat schema descriptions but gives agent interpretation 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 ('Return'), resource ('bounded monthly history'), and scope ('one port', 'one consistent crossing measure'), and clarifies the counting unit ('inbound crossing events, not unique vehicles or people'). The examples of Laredo and San Ysidro anchor it visually. It clearly differentiates from the sibling comparison/search/pack tools.

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

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

Explicitly tells the agent when to use it: monthly truck/pedestrian crossing queries and reproducible port-volume charts. It doesn't name sibling alternatives or exclusions, but the use cases are concrete and the scope constraints ('one port, one measure') imply it's not for comparisons (use compare_ports) or discovery (use search_ports).

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 behavioral context: it explains the shared rolling window, ranking by current count, and lists the return fields (prior-window count, completeness, percent change, exact window, stable port codes, provenance). It also explicitly states what it does not compare, clarifying scope beyond 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 deliver the core action, output composition, usage examples, and exclusions with no filler. Key information 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 compensates by enumerating the returned data: rankings, prior-window count, completeness, percent change, exact window, port codes, and provenance. It also gives concrete usage examples and exclusions, making the tool's behavior predictable. Given its read-only, idempotent nature and five well-described parameters, the description is complete enough for an agent 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 descriptions cover all 5 parameters at 100%, so the baseline is 3. The description adds context about the comparison window and measures ('one consistent official BTS crossing measure', 'shared rolling window') that maps to the measure and trailing_months parameters, but it doesn't add syntax or format details beyond the schema. Thus it remains at baseline.

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

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

The description opens with a specific verb and resource: 'Compare two to eight U.S. land-border ports on one consistent official BTS crossing measure over a shared rolling window.' It also differentiates itself by stating what it does not compare (wait times, outbound flows, cargo value), making its purpose unambiguous relative to 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 use-case examples ('Use this for compare truck crossings at Laredo, El Paso, and Otay Mesa') and a negative constraint ('It does not compare wait times, outbound flows, or cargo value'). While it does not name sibling tools, the examples and exclusions give clear guidance on when to select this tool.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and non-destructive, so the description does not need to repeat safety. It adds value by clarifying the tool is a lookup (inbound only) and that it returns metadata (coverage, provenance) rather than time-series data. This context helps set expectations beyond the annotations.

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

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

The description is two sentences, front-loading the core purpose and output. It efficiently includes usage examples and exclusions. It is concise without being under-specified, although it could be slightly trimmed (e.g., 'available crossing measures, coverage' is dense but not 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?

Given the simple lookup nature, no output schema, and 6 parameters fully documented in the schema, the description covers the tool's purpose, scope, and usage adequately. It doesn't specify response structure in detail, but that is less critical for a search tool, and the output fields are mentioned. It is complete enough for an agent to call correctly.

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

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

The schema covers 100% of parameters with descriptions (e.g., limit, query, state, border, offset, response_format). The description mentions that query can be a port name, state, or exact code, but that info is already in the schema. It adds minimal nuance, such as the 'border' using official BTS labels, which is already in the enum. Baseline 3 for high coverage is appropriate.

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

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

The description explicitly states the action ('Search U.S. land-border ports'), the resource (LiveDataLink's BTS Border Crossing Entry snapshot), and the output (four-digit port codes, state, border, coordinates, crossing measures, coverage, pagination, provenance). It clearly distinguishes the tool from siblings like bts_transport_compare_ports or bts_transport_border_trend, which likely focus on analysis rather than lookup.

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

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

The description provides concrete example queries ('find the Laredo border port code', 'which Arizona ports have truck crossings?') and explicitly states when to use it (before a trend call) and what it is NOT for ('not wait times or outbound traffic'). Although it doesn't name specific sibling tools, the practical usage context is sufficient.

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

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

Annotations already cover the read-only, idempotent, non-destructive nature, lowering the bar. The description adds important behavioral context by flagging HEURISTIC detection with conservative default thresholds and stating the tool is for research, not investment advice. This helps the agent temper expectations about precision.

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 tightly written sentences: the first delivers the core action, pattern list, and return shape; the second adds a necessary heuristic caveat. No filler, and the most important identifying 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?

With no output schema, the description's explicit return-field list ({pattern, date, direction, barIndex}) is valuable. It covers the essentials for a simple read-only scanner, though it could mention edge cases or the meaning of barIndex more explicitly. Overall, it is sufficiently complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents symbol and lookback_days. The description does not add substantial parameter-level detail beyond reaffirming the daily-bar scope, 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 states a specific action ('Detect'), a specific resource ('classic candlestick patterns on a ticker's recent daily bars'), and enumerates the exact patterns covered. It also specifies the return fields, making the tool's purpose unambiguous and clearly distinct from siblings like stock_history or support_resistance_levels.

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

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

The description implies usage context (recent daily bars, research-oriented) and adds a 'not investment advice' caveat, but it does not explicitly say when to prefer this tool over similar technical-analysis siblings like support_resistance_levels or bounce_scanner. No 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 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 readOnly, idempotent, non-destructive. The description adds significant behavioral context: it compares specific fields (authority, identity, insurance, etc.), returns status, severity, field-level changes, and next action. It also discloses that the tool does not silently store data, requiring the agent to persist snapshots. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with purpose. It packs essential details (fields compared, output contents, storage requirement) without fluff. Every sentence earns its place, and the warning about watchlists is critical for correct usage.

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

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

For a tool with no output schema, the description thoroughly explains what the tool returns (status, severity, changes, next action) and the essential workflow (store snapshot, schedule calls). It covers the stateful nature and data handling, making it complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds little beyond the schema: it repeats that previous_snapshot is a prior result and mentions accepting a DOT/MC/name (already in schema). It does tie the parameters together by explaining the tool's acceptance of an identifier and prior snapshot, but this is minor added value.

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

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

The description clearly states the tool's purpose: 'Recheck an existing carrier snapshot and identify meaningful changes since the previous check.' It specifies verb (recheck), resource (carrier snapshot), and the core function (identify changes). This distinguishes it from sibling tools like carrier_vetting_score (initial scoring) or fmcsa_carrier_lookup (basic lookup).

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

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

The description provides explicit usage guidance: 'Store the returned current_snapshot in your own system and call this on a schedule.' It also warns that LiveDataLink does not retain watchlists, implying the agent must manage snapshots. This makes it clear when to use this tool (for ongoing monitoring) and what to do with its output, effectively guiding agent behavior.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable context: it mentions the tool returns source coverage and failures, and that one missing record does not hide others. It also clarifies the tool is an analytical aid, not a substitute for direct verification, which is useful behavioral context beyond the annotations.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose, then details the output, usage context, and caveats. Every sentence adds value: the batch limit, output components, export formats, use case, independence of evaluations, and the analytical-aid disclaimer. No wasted words.

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

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

Given the tool's moderate complexity (batch processing, multiple output formats, independent evaluations), the description covers all essential aspects: input constraints, output structure, export options, use case, and limitations. The annotations provide the safety profile, and the schema covers parameters, so the description is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds the batch limit (up to 10) and the accepted comma-separated string format for dot_numbers, which is helpful for agent convenience. It also mentions the default format (markdown) and the available export formats, reinforcing the enum values.

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

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

The description clearly states the tool vets a batch of up to 10 US motor carriers by USDOT number, returns one GO/CAUTION/NO-GO result per carrier, and lists the output components. It distinguishes itself from siblings like carrier_vetting_score and carrier_vetting_evidence_pack by focusing on batch processing and the specific output format.

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

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

The description explicitly states when to use this tool: 'Use this to screen a broker's candidate list or lane roster.' It also explains the batch behavior (each carrier evaluated independently) and notes it is an analytical aid, not a substitute for direct FMCSA verification, which helps the agent decide when not to rely on it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds valuable context beyond those: it is auditable, includes source coverage and failures, retrieval timestamp, primary-source links, and a broker follow-up checklist. The 'analytical aid, not a substitute' caveat further clarifies 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?

The description is dense but every sentence earns its place: it states the deliverable, enumerates the output, gives usage guidance, and adds a safety caveat. It is front-loaded with the core purpose and contains 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?

Given the tool's complexity and lack of an output schema, the description thoroughly covers what the agent can expect: verdict, FMCSA evidence, sanctions/court/federal-award checks, source coverage/failures, timestamp, links, and a checklist. It is complete enough for an agent to decide when to invoke it and what it will return.

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 mc, dot, and name. The description restates that resolution can happen by 'USDOT, MC, or legal name' but adds little beyond what the schema provides. This meets the baseline but does not elevate it.

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

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

The description uses a specific verb and resource: 'Produce an auditable Carrier Vetting Pack for a freight broker.' It clearly enumerates the deliverable contents and explicitly distinguishes itself from the 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?

The description gives explicit when-to-use guidance: 'use it when a human reviewer needs to save or forward the record.' It also names the related alternative (carrier_vetting_score) and adds a caution that it is '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?

The description explains the decision logic: what triggers NO-GO (sanctions match or lack of active operating authority), CAUTION (BASIC alerts, fatal crashes, missing insurance, high out-of-service rates, litigation, unavailable source), and GO (implicitly). It also discloses that it joins multiple data sources and adds a disclaimer that it's analytical aid, not a substitute for own checks. The annotations already indicate readOnlyHint=true, so no contradiction. It doesn't discuss rate limits or performance, but the decision logic is well covered.

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

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

The description is well-structured and front-loads the purpose in the first sentence. It is concise but dense with useful information: input requirements, data sources, decision categories, triggers, and disclaimer. Every sentence earns its place, with no redundant or filler content. It effectively balances thoroughness and brevity.

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

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

Given the tool's complexity (aggregating multiple data sources with decision logic), the description is highly complete. It covers all key aspects: what inputs to provide, what data is joined, what outputs (GO/CAUTION/NO-GO with reasons), and critical triggers. It also provides a disclaimer about its use as analytical aid. No output schema exists, but the description sufficiently explains the returned result's nature. No gaps are apparent for an agent to call it correctly.

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

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

The schema description coverage is 100%, so each parameter already has a description. The tool description adds context: it explains that DOT is most preciseions, MC is used if no DOT, and name is less precise with top match vetted. This enhances the parameter semantics by clarifying preference order and fallback behavior, but it doesn't add extensive new meaning beyond schema. Baseline 3 is appropriate because schema fully covers parameters and description adds limited extra 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?

The description explicitly states the purpose: 'Vet a US motor carrier (trucking company) for a freight-brokerage review, in one call.' It specifies the resource (US motor carrier) and the action (vet), and distinguishes it from siblings like carrier_vetting_batch and carrier_vetting_evidence_pack by noting it returns a decision-support result in one call, while siblings imply batch or evidence pack functions.

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 defines when to use the tool for a single carrier vetting, and it implicitly differentiates from siblings: 'in one call' suggests the batch version for multiple carriers. It also provides guidance on parameter selection: 'Give a USDOT number, MC number, or carrier name' and notes that DOT is most precise, MC is used if no DOT, and name is last resort with top match vetted. This is explicit usage context.

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

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

Annotations already establish that this is read-only, idempotent, non-destructive, and open-world. The description adds behavioral clarity by specifying the exact payload fields (name, citations, court, jurisdiction, decision date, reporter location, source URL) and indicating that the full text itself is not returned. No contradiction exists between description and 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?

A single front-loaded sentence gets straight to the action and resource, with the field list in parentheses. There is no filler or repetition; 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 one-parameter, read-only, idempotent lookup with no output schema, the description is complete: it identifies the input and enumerates the expected return fields. An agent can select and invoke the tool correctly without additional context.

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

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

With 100% schema coverage for the single required id parameter, the baseline is 3. The description merely repeats that the lookup is by CAP id and adds no extra format, range, or semantics beyond the schema's example and type.

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 action and resource: 'Get full metadata for a single case by its CAP id.' It enumerates the exact metadata fields returned and clarifies that the full text is only referenced by URL, which distinguishes it from sibling tools like caselaw_opinion_text, caselaw_search, and caselaw_citation_lookup.

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

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

The phrase 'single case by its CAP id' gives a clear context for use: an agent should call this when it already has a CAP id and needs the case metadata record. The mention of the source URL for full text implicitly signals that full-opinion retrieval is out of scope, though no sibling tool is explicitly named and no when-not-to-use guidance is provided.

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 declare readOnly, idempotent, non-destructive behavior. The description adds useful context beyond that: text is 'retrieved live from the public-domain CAP static mirror (not stored)' and includes each opinion type with its author, which helps the agent understand what will happen when invoked.

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

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

The description is compact and well-structured: the core action is front-loaded, followed by data-source behavior, output composition, and a parameter-bound usage note. 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 two-parameter read-only tool with rich annotations, this is largely complete: it identifies the input, source, output content, and response bounding. Minor ambiguity remains about the exact return format or behavior when max_chars is exceeded, but no output schema exists to fill that 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 both id and max_chars are already documented structurally. The description adds only that max_chars bounds the response and that the id is a CAP case id, which does not significantly extend the schema's own parameter documentation.

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

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

The description states a specific action ('Fetch the full opinion text of a case') and the required identifier ('by its CAP id'), making the core purpose clear. It does not explicitly differentiate from siblings like caselaw_case_details or caselaw_search, though 'full opinion text' and 'CAP id' imply a distinct retrieval role.

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

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

The description implies when to use the tool ('on demand by its CAP id' and 'Use max_chars to bound the response'), but it does not explicitly state alternatives or when not to use it. The schema's id description points to caselaw_search/caselaw_citation_lookup as sources, but the description itself offers only implied usage context.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful context beyond those: the data is public domain, results include CAP ids and citations, and the v1 index only covers the U.S. Reports reporter. This is valuable behavioral transparency and does not contradict 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 three sentences with no filler: purpose first, then output and next-step guidance, then a critical scope caveat. It is front-loaded and 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?

The description covers what is searched, what is returned, how to retrieve full opinions, and a major index limitation. The schema handles parameter details. It stops slightly short of stating whether at least one search criterion is expected or describing the exact result envelope, but for a search tool with strong annotations 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?

Schema coverage is 100%, with each parameter already described and exemplified. The description adds a useful high-level grouping of filters and the decision-date range concept, but does not need to compensate for missing schema documentation.

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

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

The description states a specific action and resource: searching US court opinions from the Caselaw Access Project by case name, keyword, court, jurisdiction, and date range. It clearly differentiates itself from the sibling caselaw_opinion_text by describing its metadata output and directing the agent to that sibling for full opinion text.

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 an explicit follow-up/alternative: 'Use caselaw_opinion_text with a returned id to read the full opinion.' It also sets expectation with the v1 U.S. Reports coverage note. However, it does not explain when to prefer other sibling search tools such as caselaw_citation_lookup or court_opinion_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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context that this is an arbitrary SoQL query against any CDC dataset, but does not mention response shape, pagination, or rate-limit behavior. With annotations carrying the safety burden, this is adequate but not exemplary.

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 no wasted words: the generic scope, the usage rule, and the required input format. The SoQL reference link is useful and placed at the end without disrupting the core guidance.

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

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

Given the rich schema coverage, strong annotations, and the inherently flexible nature of a generic query tool, the description is largely complete. The SoQL reference helps fill the gap left by no output schema, though it does not describe expected return format or mention how to discover valid dataset IDs.

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 fully documents all five parameters. The description reinforces that dataset is a 4x4 Socrata ID and mentions where-clause support, but adds no meaning beyond the schema's parameter descriptions. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Generic SoQL query against any data.cdc.gov dataset.' It also distinguishes itself from siblings by positioning itself as the fallback when 'none of the curated tools fit,' making its role in the tool hierarchy clear.

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

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

The description explicitly says to use it when none of the curated tools fit, which is clear contextual guidance. It does not enumerate specific alternative tools or spell out when not to use it, but the generic-vs-curated distinction is enough for an agent to 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 communicate readOnly, idempotent, and non-destructive behavior. The description adds useful context with '12-month rolling counts' and the dataset ID, which goes beyond the annotations. It does not mention response format, temporal coverage, or pagination behavior, so it adds some but not rich behavioral detail.

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

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

The description is three short sentences, and each one earns its place: identifying the dataset, describing the rolling-count aggregation, and stating practical use cases. There is no filler, redundancy, or unnecessary detail.

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

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

For a read-only tool with three optional parameters and no required inputs, the description covers the subject, dimensions, aggregation, and intended applications. It is missing explicit details like date range or row contents, but given the simple schema and strong annotations, it 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 description coverage is 100%, so the schema already documents all three parameters: limit, indicator, and state_name. The description merely restates 'by state and indicator' without adding new parameter-level meaning. This matches the baseline where the schema does the heavy lifting.

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

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

The description clearly identifies the resource as 'CDC drug overdose deaths by state and indicator' and adds the dataset ID (9j2v-jamp), making it distinct from related CDC tools. It lacks an explicit verb like 'returns' or 'provides', but the intent is unmistakable. It differentiates well from siblings such as cdc_weekly_deaths_by_state and cdc_leading_causes_of_death.

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 use cases ('opioid/fentanyl/stimulant policy research and treatment-program siting'), which imply when this tool is relevant. However, it does not explicitly state when to use this tool versus sibling CDC tools or mention any exclusions. The guidance is implied rather than direct.

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 that the tool is read-only, idempotent, and non-destructive, so the safety burden is covered. The description adds useful context about the data being modeled expected vs observed values, but it does not disclose operational details such as update cadence, response shape, or query limitations. This is adequate but not rich behavioral disclosure.

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

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

Three short sentences each earn their place: the dataset identifier, the data model and granularity, and the intended analytical purpose. There is no filler, repetition of schema content, or unnecessary detail. The key 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 low-complexity, read-only tool with fully documented parameters and safety annotations, the description is sufficient for an agent to understand what the tool returns and why it exists. It does not describe output columns or response formatting, but no output schema is provided and the dataset semantics are clear enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents limit, state, and outcome with examples. The description adds the conceptual framing of 'by state and week' but gives no parameter-specific guidance beyond that. The baseline of 3 is appropriate because the schema carries the parameter documentation burden.

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 a specific CDC dataset (xkkf-xrst) and explains that it contains modeled expected vs observed deaths by state and week. This distinguishes it from siblings like cdc_weekly_deaths_by_state, which would provide observed death data, and cdc_drug_overdose_deaths. Though no explicit verb like 'get' or 'query' appears, the resource and its content are unmistakable.

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

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

The description states a clear purpose: estimating true pandemic impact beyond reported COVID deaths. This gives an agent enough context to select this tool over related CDC mortality datasets. It does not explicitly name alternative tools or state when not to use it, but the intended use case is concrete rather than merely 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 cover safety (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description's burden is reduced. It adds useful context about scope (state-level, weekly) and the dataset, but does not describe output format, pagination, or behavior with empty filters. No contradiction with annotations.

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

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

The description is a single sentence that front-loads the source and the return value, with no filler and no repetition of schema fields. The dataset ID is useful and unobtrusive.

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 read-only tool with zero required parameters and full schema coverage, the description is nearly complete. It states what is returned and at what granularity. However, since there is no output schema, it could be slightly clearer about the form of 'activity levels' (e.g., categorical vs. numeric) and default behavior when no filters are supplied.

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

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

The input schema already describes all three parameters at 100% coverage (limit, season, statename). The description does not add meaningful parameter-level detail beyond what the schema provides, so the baseline score 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 source and resource ('CDC FluView state-level influenza surveillance') and states a clear action with output ('Returns weekly ILI activity levels per state'). It distinguishes itself from sibling CDC tools by focusing specifically on influenza-like illness, and the dataset ID (vh55-3he6) adds precision.

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

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

The description implies when this tool is relevant: any query about state-level flu/ILI activity. However, it does not explicitly state when to prefer this over siblings such as cdc_dataset_query or cdc_weekly_deaths_by_state, nor does it provide exclusions or alternative routing guidance.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds useful output-shape context but does not disclose potential operational behaviors such as default scope when filters are omitted, available year range, or valid cause-name list. 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?

Two sentences are front-loaded with the dataset source and return values, and the closing use-case sentence adds context without clutter. The dataset ID in parentheses is a minor but useful identifier, not wasted space.

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 optional-filter retrieval tool with no output schema, the description provides the key missing output semantics: rows contain deaths and age-adjusted rates by cause, state, and year. It could add valid cause-name/date-range details, but the 100%-covered schema and read-only annotations make the tool safely invokable with reasonable defaults.

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

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

The schema already describes all four parameters at 100% coverage, so the baseline is 3. The description adds value by explaining that results are organized 'per cause per state per year,' clarifying how the optional filters combine into output rows. This goes slightly beyond the one-line schema descriptions.

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

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

The description names a specific resource — the NCHS leading-causes-of-death dataset (bi63-dtpu) — and states the exact returned metrics: total deaths and age-adjusted death rates by cause, state, and year. This makes it easy to distinguish from CDC siblings such as cdc_drug_overdose_deaths or cdc_weekly_deaths_by_state.

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

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

The description offers an implied use case ('useful for chronic disease + injury mortality research') but no explicit when-to-use/when-not-to-use guidance or alternative tool suggestions. Among many CDC siblings, the agent is not told why this tool should be selected over cdc_dataset_query or the other CDC dataset 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 behavior. The description adds value by enumerating the returned data fields (date, state, etiology, illnesses, hospitalizations, deaths, exposure), which is especially helpful in the absence of an output schema. It does not disclose pagination or default-limit behavior, but the annotations cover the safety profile.

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 identifies the dataset, scope, and return fields with zero filler. Every word contributes to the agent's ability to understand and invoke the tool.

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

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

For a read-only query tool with four optional parameters and no output schema, the description plus schema covers the essential invocation details: dataset, filters, returned fields, and default limit. It stops short of explaining filtering behavior or result-set expectations, but the tool is simple enough that these are minor gaps.

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

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

Schema coverage is 100%, with each parameter (year, limit, state, etiology) already having a description in the input schema. The tool description names some of these concepts (state, etiology) but does not add meaning beyond what the schema provides, so the baseline score 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), the dataset identifier (iezt-77pi), and the exact fields returned. This clearly distinguishes the tool from the many other cdc_* siblings by domain and dataset.

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

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

The intended use is implied by 'CDC NORS ... outbreak reports' and the returned fields, but the description does not explicitly state when to choose this tool over alternatives like cdc_dataset_query or other CDC health datasets. No exclusions or alternative routing are provided.

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, covering the safety profile. The description adds useful context: the specific Socrata dataset ID (8xkx-amqh), the breakdown of returned metrics, and the time-series nature. However, it does not disclose default scope when no state/county filter is applied or the time window returned, and no contradiction exists 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?

Three compact clauses front-load the subject, then state the output composition and a use case. Every sentence earns its place; the dataset ID is slightly esoteric but useful for provenance when cross-referencing with cdc_dataset_query.

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 all-optional parameters and no output schema, the description covers what is returned. But it leaves gaps: what happens with zero filters (all counties? national aggregate?), what date range is covered, and how 'over time' is represented in the response. These are material for an agent invoking 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% — limit, recip_state, and recip_county are all documented in the input schema. The description only hints at county-level granularity ('by US county') and adds no parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

Description states a clear verb+resource: returns COVID-19 vaccination coverage by US county, with explicit output content (booster + primary series percentages over time). This distinguishes it from sibling CDC tools covering flu, overdose deaths, and other indicators, though it doesn't explicitly differentiate from the generic cdc_dataset_query which could query the same dataset.

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

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

'Useful for public-health gap analysis' implies a use case, but there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives. Among many cdc_* siblings, an agent gets no routing help beyond the narrow 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 cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond those: the 'provisional' nature of the data, the NCHS dataset identifier, and the ISO-week granularity. This meaningfully informs the agent about data freshness and structure without contradicting the annotations.

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

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

Two sentences deliver the dataset source, output semantics, granularity, and intended use cases with no filler. Key information is front-loaded and 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 simple read-only tool with all parameters documented in the schema and no required parameters, the description is complete enough for safe invocation. It explains what the tool returns, from which dataset, and what analysis it supports, which compensates for the absence of an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description hints at cause categories and state/time granularity, but it does not add much beyond what the schema already documents for year, cause, limit, and state.

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: 'Returns all-cause and selected-cause death counts per state per ISO week' from the CDC NCHS dataset. It identifies the exact dataset id (muzy-jte6) and scope, which clearly distinguishes it from sibling CDC tools like cdc_flu_surveillance or cdc_leading_causes_of_death.

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

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

The description gives clear context for appropriate use: 'excess-mortality and respiratory-disease seasonality analysis.' It does not explicitly name sibling tools to avoid or state 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 convey read-only, idempotent, non-destructive behavior, lowering the bar for disclosure. The description adds context about the data source and optional NAICS filtering, but does not describe output format, pagination, or geographic parameter dependencies. No contradiction with annotations 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?

The description is two sentences with no filler. The first sentence front-loads the core data content and source; the second efficiently explains the optional filter and use cases. Every clause contributes to selection and invocation understanding.

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 tool with no output schema, the description is somewhat thin: it names the data metrics and domain but does not explain geography-level selection rules, return structure, or units. The schema covers required parameter dependencies, but the overall package relies heavily on the schema to make the tool usable. Description is adequate but not comprehensive.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by clarifying that NAICS is an industry filter and that the returned metrics are establishments, employment, and payroll, which helps agents interpret the year and level parameters in context. It does not fully compensate for missing schema-level nuances, but it goes beyond simple duplication.

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 resource: business establishments, employment, and annual payroll from County Business Patterns, with an optional NAICS filter. This differentiates it from sibling census tools like census_demographics or census_population, though it lacks a direct verb such as 'get' or 'query' and does not explicitly name a sibling 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?

The description provides useful usage context ('Used for industry research, competitive intel, supply chain analysis') but gives no explicit when-to-use vs. alternative guidance, such as 'for demographic data use census_demographics.' The intended use is implied by the data domain rather than clearly contrasted with sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds limited behavioral context beyond that, mostly restating topic areas rather than disclosing output shape, limitations, or data-source nuances.

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 concise sentences front-load the tool's substance with a list of returned data categories, then add use-case context. There is no filler, redundancy, or repetition 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?

With rich schema descriptions and annotations, the description covers the essential 'what' and 'when' well. It also lists the return subjects since there is no output schema. Minor gaps remain around output format or precise metric definitions, but they do not prevent correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The tool description adds no parameter-specific guidance beyond what the schema provides, so the baseline score 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 enumerates the specific data topics (labor force, unemployment, commute times, public transit usage, work-from-home rates) and the geographic scope (US geography), which distinguishes it from sibling census_* tools. It lacks an explicit verb like 'returns' or 'provides', but the intent is unambiguous.

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

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

The description gives clear use contexts: site selection, workforce analysis, and commercial real estate. This helps an agent decide when this tool is relevant, though it does not explicitly state when to use an alternative census tool or call out 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 establish read-only, idempotent, non-destructive behavior. The description adds useful context by stating the source is ACS 5-year and listing the returned fields, but it does not disclose potential limitations such as data suppression, margins of error, or geography-specific availability.

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, front-loaded with the core purpose, and includes a compact list of return fields plus the data source. Every sentence adds information without redundancy.

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

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

There is no output schema, but the description enumerates the returned counts and median age, which is adequate for a read-only demographic lookup. The schema handles parameter semantics, and the source attribution provides important temporal context, though a note on ACS estimate reliability would improve completeness.

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

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

The input schema fully documents all 8 parameters with descriptions and an enum for level, so the description does not need to repeat parameter details. The description adds only general geography context, which is insufficient to raise the score above the baseline.

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

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

The description clearly identifies the tool's specific purpose: providing race, ethnicity, and age breakdowns for US geographies. It lists the exact returned metrics and names the data source, making it easily distinguishable from sibling census tools that focus on population, income, or business data.

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

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

The description gives clear context for when the tool is relevant: when demographic breakdowns by race, ethnicity, or age are needed. It does not explicitly name alternatives or exclusions, but the detailed output list makes the appropriate use case 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 cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context about matching behavior, especially the note that state lookups support substring matching. It does not contradict 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?

Three sentences, each earning its place: what the tool does, what inputs it supports, and why/when to use it. The purpose is front-loaded and no filler is present.

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

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

For a simple lookup tool with strong schema coverage and safe annotations, the description is adequate for selection and invocation. The only minor gap is that it does not describe the exact response shape or how ambiguous matches are handled, but no output schema exists and the purpose is simple enough that this is not a serious deficiency.

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

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

The input schema already describes all three parameters in detail, including query examples, the level enum, and the limit default. The description adds only minor extra meaning—substring matching for 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?

The description states a specific verb ('Look up'), a clear resource ('Census FIPS codes by name'), and enumerates supported query forms. It also distinguishes itself from the other census_* tools by identifying it as the code-finding helper needed before those data tools.

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

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

The description provides clear guidance: 'Use this to find the FIPS codes needed by other census_* tools.' This tells the agent when to reach for it, though it stops short of explicitly naming alternatives or stating when not to use it.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds metric and geography scope but does not disclose operational behavior such as return shape, aggregation, wildcard effects, or lookup defaults. No contradiction 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?

The description is two sentences with front-loaded, specific metric content followed by a short use-case statement. It contains no filler, no repetition of schema details, and 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?

The schema fully documents all conditional geography parameters and the annotations cover read-only/idempotent behavior, so most invocation requirements are already structured. The description adds the output metrics and use cases, which is valuable because there is no output schema. A small note on how to choose among geography levels would improve it further.

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

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

Schema description coverage is 100%, and each parameter already has a meaningful description including conditional requirements and wildcard usage. The description adds no parameter-specific semantics beyond the general geography scope, so the baseline score 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 data domain—household income, per capita income, housing units, occupancy, home value, and rent—for US geographies. This concrete metric list makes the tool's purpose clear and distinguishes it from sibling census tools like census_demographics or census_population without opening the schema.

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

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

The description gives explicit use cases ('real estate AI, market analysis, location-based pricing'), which provides useful context. However, it does not compare against sibling census or real-estate tools, nor does it say when not to use this tool, leaving alternative selection 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?

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description adds meaningful behavioral context by listing the returned metrics (total, male, female, median age) and the supported geography scope. This helps the agent predict what the call will produce without 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 three sentences with no wasted words: action and scope first, then return values, then use cases. It is appropriately sized for a data-retrieval tool and front-loads the most important information.

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

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

The description covers the core outputs, supported geographies, and typical use cases, which is sufficient given the rich schema and read-only annotations. It could be slightly more complete by explicitly differentiating itself from census_demographics, but an agent can still invoke it correctly with the schema's parameter descriptions.

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 8 parameters and their conditional requirements. The description adds little parameter-specific meaning beyond restating geography levels, which are already captured in the level enum and parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Get total population for a US geography,' then enumerates all supported geography levels. It also distinguishes itself from sibling census tools by specifying the exact outputs (total, male, female, median age), which clarifies its narrow population-focused scope.

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

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

The description provides clear usage context by stating it is 'Used for market sizing, location intelligence, demographic analysis.' It does not explicitly name alternative tools or exclusion criteria, but the use cases give an agent enough context to select it over broader census or demographic 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 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 establish that this is read-only, idempotent, and non-destructive, so the description does not need to repeat those safety traits. It adds some behavioral context by explaining lens semantics and interval options, but it does not describe output format, default behaviors like trend_depth, or parameter interactions.

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 main purpose is front-loaded, and the lens and interval options are enumerated compactly. Every word 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 tool with seven parameters and no output schema, the description is adequate but leaves gaps. It does not clarify how sub_lens interacts with lens, whether product filters combine with lens=product, or what the returned trend data actually looks like. Schema coverage helps, but sub_lens remains ambiguous.

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 has 100% description coverage, so the baseline is 3. The description adds value beyond the schema by explaining the meaning of each lens enum value and clarifying that interval can be month, quarter, or year. This helps an agent use the most important parameters correctly, though it adds nothing for sub_lens or product filters.

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

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

The description clearly states the tool's purpose: 'Time-series trends of complaint volume.' It further specifies what each lens shows, including totals over time and breakdowns by product, company, or issue, which makes it easy to distinguish from sibling complaint tools like cfpb_search_complaints or cfpb_complaint_detail.

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

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

The description explains the available lenses and intervals, so an agent can infer when to use this tool for time-series trend analysis. However, it does not explicitly state when to prefer this tool over alternatives such as cfpb_complaint_aggregations or cfpb_state_complaints, nor does it mention any 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 read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds useful context about the database's scale, time range, and the availability of public narratives in results, but it does not disclose pagination, rate limits, or other behavioral edge cases beyond what the schema's default/max values already 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?

Two tightly written sentences front-load the core purpose and resource, then list the filter dimensions and return value. There is no filler or redundant restatement of the tool name or annotations.

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 search tool with 9 optional parameters and no output schema, the description gives a solid high-level picture of inputs and outputs. However, it does not orient the agent among the many related CFPB sibling tools, such as cfpb_complaint_aggregations, cfpb_complaint_trends, or cfpb_suggest_company, leaving some selection context to the agent's own reasoning.

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 every parameter. The description paraphrases several filters (free-text term, company, product, state, date range, narrative-presence) but adds no new semantic detail beyond what the schema provides, matching the baseline of 3.

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

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

The description clearly states a specific action ('Search'), a specific resource (the CFPB Consumer Complaint Database), and the main filtering capabilities. It does not explicitly distinguish itself from sibling tools like cfpb_complaint_aggregations, cfpb_complaint_trends, or cfpb_state_complaints, so it falls short of a 5.

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

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

The description implies when to use the tool: when you want raw complaint records matching certain filters. However, it provides no explicit when-not-to-use guidance or direct comparison with alternatives such as cfpb_complaint_aggregations for counts or cfpb_complaint_detail for individual complaint details, leaving the differentiation 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it compares published aggregates only, does not recommend trades, and returns provenance. It also notes the CIT exception in the schema (combined only), which is a meaningful behavioral constraint beyond the annotations.

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

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

The description is compact and front-loaded: the first sentence states the core function and constraints, the second lists return values, the third gives example queries, and the fourth clarifies limitations. Every sentence earns its place with no redundancy.

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

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

For a read-only comparison tool with 100% schema coverage and no output schema, the description is nearly complete. It covers what the tool does, what it returns, example usage, and a limitation. The only minor gap is that it doesn't explicitly state what happens if fewer than two or more than eight markets are provided, but the schema's 'Two to eight' constraint covers that.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds value by clarifying the markets parameter ('Two to eight exact CFTC contract codes or unambiguous names') and the report_type parameter ('Categories differ by family; use search or the evidence pack to discover available families'). It also explains the scope default and CIT exception, which goes beyond the schema.

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

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

The description states a specific verb ('Compare'), a precise resource ('latest reported CFTC COT position'), and a clear scope ('two to eight contract markets using one consistent report family, scope, and trader category'). It also names the return values (stable market codes, exact dates, long/short/net positions, open interest, ranking, provenance), which distinguishes it from sibling tools like cftc_cot_latest and cftc_cot_history.

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 example queries ('compare managed-money positioning in oil, gold, and copper' or 'which selected market has the largest commercial net position?') and states what it does not do ('does not recommend trades'). It also implies when to use it versus siblings by emphasizing comparison across multiple markets, and the schema notes to use search or the evidence pack to discover available families.

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

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

Beyond readOnly/openWorld/idempotent/non-destructive annotations, the description adds useful behavioral context: it surfaces open interest and the largest absolute reported category net per view, preserves incompatible family classifications, and is explicitly not real-time or trading advice. This goes beyond what annotations alone convey.

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

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

Three sentences, no filler: the first states the core function, the second summarizes output semantics, and the third gives usage examples and caveats. The content is front-loaded and 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 complex aggregation tool with no output schema, the description covers what the pack contains, what metrics are surfaced, and how incompatible classifications are handled. It does not detail the exact response structure, but combined with the schema and annotations it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'one contract market' phrasing aligns with the existing market parameter but does not add substantive meaning beyond the schema, and the response_format parameter is already fully documented by 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 ('Combine') and resource (all hosted CFTC COT report-family and scope views for one contract market) and states the output (a provenance-backed evidence pack). It clearly distinguishes itself from the sibling single-view tools like cftc_cot_latest and cftc_cot_history by emphasizing aggregation of all views.

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 use-case examples ('build a COT evidence pack for gold', 'show every CFTC positioning lens for crude oil') and frames the tool as research synthesis, not real-time data or trading advice. It does not explicitly name alternatives or state when not to use it, but the context is clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds beyond that: the result is 'bounded weekly history' with 'pagination', 'source ids', and 'provenance', and warns 'Report-family categories are enforced; not trading advice.' This gives the agent useful expectations about output size, reproducibility, and validation without contradicting 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?

Four dense sentences, each earning its place: purpose, return contents, use cases, and caveat. Front-loaded with the core action, then examples and constraints. No filler or repetition of schema details.

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 tool with no output schema, the description plus fully-covered schema is largely sufficient. It lists return contents, examples, and a validation caveat. The only mild gap is not explicitly routing ambiguous market names to cftc_cot_search_markets, but the schema's market parameter already says 'Search first when the name is ambiguous.'

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 echoes 'report family, scope, and trader category' and hints at 'bounded' pagination, but adds no parameter-specific details beyond what the schema already documents. It is not misleading but also not compensatory.

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: 'Return a bounded weekly history for one CFTC contract market, report family, scope, and trader category.' The examples ('managed money net positions in crude oil over time', 'commercial gold COT history') make the time-series nature unmistakable. Though no sibling is named, 'bounded weekly history' inherently differentiates it from cftc_cot_latest and cftc_cot_compare.

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 use cases: time-series positioning questions and reproducible charts. It does not state when NOT to use it or name alternatives (e.g., cftc_cot_latest for the current snapshot, cftc_cot_search_markets to resolve names), but the context is clear enough for an agent to select it for historical queries.

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 covered. The description adds valuable behavioral context by noting the data is 'delayed aggregate positions' and explicitly disclaiming that it is 'not a trade signal or recommendation,' which goes beyond what annotations provide and helps set expectations about the data's nature.

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

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

The description is concise and well-structured: the first sentence captures the core function, the second enumerates the data fields, and the third provides usage examples and a behavioral disclaimer. Every sentence earns its place with no redundancy or fluff, and the most important scoping information ('latest', 'one contract market') 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 simple read-only tool with only two parameters alert, the description is nearly complete. It describes the output contents (open interest, positions, percentages, dates, ids, provenance) and includes usage exampleship. There is no output schema, so the field enumeration is valuable. Minor gaps include not specifying error behavior or how to handle ambiguous market names, but the schema already advises searching first, so the overall context is adequate.

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 covers both parameters fully (100% coverage): 'market' has a clear description and 'response_format' is an enum with defaults. The description itself does not add substantive parameter-level detail beyond what the schema already provides; it mainly gives usage examples rather than explaining parameter semantics. Baseline 3 is appropriate since schema coverage is high.

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 action ('Return'), a distinct resource ('latest available official CFTC COT position snapshot for one contract market'), and a clear scope ('across every hosted report family and scope'). It also lists the included data fields, making the tool's function unambiguous and distinguishing it from siblings like cftc_cot_history or cftc_cot_compare 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?

The description provides explicit usage examples ('latest managed-money positioning in crude oil', 'current COT categories for gold') that clearly indicate when to use this tool. It does not explicitly state when not to use it or name alternatives, but the emphasis on 'latest' and 'one contract market' implies boundaries against historical or comparative tools, providing clear context without exclusions.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive; the description adds valuable behavioral context beyond that, including that it reads a self-hosted official snapshot, returns stable codes, includes pagination and snapshot provenance, and covers only aggregate US futures/options markets. No statement contradicts 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 three focused sentences: purpose, return contents, and usage guidance. It front-loads the most important information and every sentence earns its place without redundant filler.

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

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

Despite having no output schema, the description lists the key return fields (codes, names, labels, families, scopes, latest date, pagination, provenance) and provides enough context to call the tool correctly. It also ties the search to a downstream history call, covering the typical agent workflow.

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 every parameter has a meaningful description with defaults and enum values. The tool description reinforces the use case but does not add syntax-level 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 opens with a specific verb and resource ('Search contract markets in LiveDataLink's self-hosted official CFTC Commitments of Traders snapshot') and clearly enumerates what is returned (stable codes, names, commodity/exchange labels, report families, scopes, latest date, pagination, provenance). It differentiates itself by stating it is a lookup/search tool for identifiers and explicitly noting it is 'not quotes or prices.'

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

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

The description gives concrete example queries ('find the CFTC code for gold', 'which COT markets cover crude oil?') and states the workflow context: 'resolve an identifier before a history call.' It also sets boundaries with 'Aggregate US futures and options markets only; not quotes or prices,' so an agent knows when not to use it.

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

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

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.

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

Schema description covers the single 'query' parameter 100%, so baseline is 3. The description repeats the name-or-CID input form but adds no new parameter-level 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 (return), resource (GHS hazard classification), and source (PubChem). The description explicitly names the outputs (signal word and hazard statements), making its purpose unmistakable and distinct from a generic chemical_lookup sibling.

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?

Does not name an alternative tool, but clearly frames the use case: retrieving public GHS classification data from PubChem. It adds a boundary condition with the SDS disclaimer, telling the agent this is informational and not regulatory guidance, though it doesn't explicitly route to alternates.

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. The description adds valuable context about the NIH/NLM PubChem public database, keyless access, public-domain data, and the stability of the returned CID. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, each earning its place: what it resolves, what it returns, and when to use it. The action is front-loaded and there is no filler or redundant wording.

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 tool with rich annotations and no output schema, the description fully covers the return fields, data source, access model, and primary use case. An agent has sufficient information to select and correctly invoke 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?

The input schema covers 100% of the single parameter and already explains that query accepts a chemical name or numeric PubChem CID. The description repeats those examples but adds no parameter-specific meaning beyond what the schema already provides.

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

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

The description states a specific verb ('Resolve') and a clear resource: chemical names or PubChem CIDs to identity and physical properties. It lists the concrete return fields, making the tool's scope unambiguous. This clarity separates it from sibling chemical_hazards, which is focused on hazard data.

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