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

With no annotations, the description carries the full behavioral burden. It discloses the return content and an important interpretation caveat (counts unadjusted for company size), which is genuinely useful. It says nothing about read-only nature, permissions, or filtering behavior beyond optional params, so it remains incomplete.

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

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

Dense and front-loaded: the core purpose and returned fields come first, followed by the size-normalization caveat and optional params. No wasted sentences, though the second and third clauses are compressed into a single run-on.

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 tool with no annotations and no output schema, the description does cover the shape of the result and a key caveat, so an agent can call it. It is still thin on input semantics and sibling differentiation, leaving the definition only minimally 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 0%, so the description must compensate. It names company_contains (explaining it selects 'all name variants') and lists date_from/date_to/product as optional, covering most parameters by name, but adds no format or semantic detail (e.g. date format, company matching behavior) beyond what the parameter names imply.

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 clear resource ('Profile of one company') and enumerates the specific contents returned (totals, first/last complaint, top products, issues, states, response outcomes, yearly counts), so the agent knows exactly what it gets. It distinguishes the company vs company_contains variant scoping, but doesn't contrast itself against siblings like find_company or compare_companies.

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

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

Usage is implied through the described output and the caveat that counts are not adjusted for company size, which tells the agent how to interpret results. However, there is no explicit when-to-use guidance nor any exclusion telling the agent why to pick this over compare_companies or find_company.

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

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

With no annotations, the description carries the behavioral load and does so reasonably well: it discloses the 6-company cap, that entries are matched as substrings with all company-name variants combined, and that counts are not adjusted for company size. It omits permission/auth needs and any error or pagination behavior, but the matching semantics and the size-normalization caveat are genuinely valuable disclosures.

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

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

Three tight sentences: purpose and metric scope first, then the input-matching rule, then the important normalization caveat. No filler, and the caveat is placed last so it reads as a qualifier rather than burying the main purpose.

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 output schema handles return values, so the metric list need not be exhaustive. However, for a six-parameter tool with zero schema descriptions and no annotations, the description leaves the filter parameters' semantics unexplained, which is a meaningful gap an agent must fill from sibling tools.

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 0%, so the description must compensate and it only does so for one of six parameters: 'companies' gets clear semantics (substring match, all variants combined, max 6). The filter parameters (issue, state, product, date_from, date_to) are referred to only as 'the same filters' with no format, default, or matching explanation.

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 ('side-by-side comparison of up to 6 companies') and enumerates the compared metrics (complaints, timely_rate, relief rates, top product, top issue), which clearly separates it from single-company tools like company_profile. It never names the sibling it is not, so it falls short of full sibling 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?

Usage is only implied by the 'comparison of up to 6 companies' framing; there is no explicit when-to-use versus company_profile or complaint_counts, and no exclusions. An agent can infer the multi-company context but receives no 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?

With no annotations, the description carries the burden and does so well for a read tool: it names every returned metric, notes that rates are fractions of each group's complaints, warns that counts are raw and not adjusted for company size, and clarifies that 'In progress'/'Untimely' are CFPB response categories rather than outcomes. It omits any note on pagination/limit semantics or auth, but the analytical caveats are unusually strong.

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

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

It is a single dense paragraph but well front-loaded: purpose and return shape first, then filters. Nearly every clause carries parameter or return semantics, though the run-on packing of filters into one sentence slightly hurts scannability.

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?

An output schema exists, so the return-shape detail is a bonus rather than a requirement, and the filter semantics are mostly covered. The gaps are the undocumented pagination/order params (limit, offset, order_by) and has_narrative, which an agent manipulating results would need given the total absence of schema 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 coverage is 0% across 17 params, so the description must compensate, and it documents the majority: group_by values, company vs company_contains (exact vs substring), state (2 letters), company_response (exact, case-insensitive), tag examples, timely true/false, and date_from/date_to formats (YYYY-MM-DD or YYYY-MM, on date received). It leaves limit, offset, order_by, and has_narrative undocumented, which is a real gap given the coverage is otherwise nil.

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?

Starts with a specific verb+resource: 'Count complaints, optionally grouped.' The scope (aggregate counts with optional grouping, distinct from per-record tools like get_complaint and from count_narratives) is immediately clear, and the enumerated group_by values pin down exactly what aggregation means here.

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 routes the agent to siblings for prerequisites and edge cases: 'company (exact name as in find_company)' and 'use list_values field=product' for the renamed product names. It clearly frames which parameters are filters and how to match them, though it never states an explicit when-not or names a competing aggregation sibling to prefer 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?

No annotations are present, so the description carries the full burden. It discloses a meaningful data-coverage caveat (counts only complaints with a narrative, coverage through 2026-08-14) and a performance trait (excludes the slower issue/response filters). It omits auth/permission needs and pagination behavior, but the coverage limitation is exactly the kind of non-obvious behavior an agent needs.

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

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

Four sentences, front-loaded with the core purpose before the caveats and the narrowing advice. Dense but every sentence carries information; nothing is 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?

An output schema exists, so return shape needn't be explained, and the data-coverage caveat is well covered. But for an 11-parameter tool with zero annotation coverage and zero schema descriptions, several argument semantics remain unaddressed, leaving the agent to guess at key filters.

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 0% across 11 parameters, so the schema provides only titles. The description compensates partially by listing the group_by dimensions (year, month, product, company, issue, state) and the filter categories (date, company, product), and by pointing to search_narratives for the shared argument set. However, non-obvious parameters such as any_of, phrase, company_contains vs company, and limit are left entirely unexplained.

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

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

States a specific verb+resource (count archived narratives) with the grouping dimensions enumerated, and explicitly distinguishes itself from search_narratives and implicitly from complaint_counts by noting it counts only complaints that have a narrative. An agent can tell what this tool returns without opening the schema.

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

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

Gives a concrete use case ("how many complaints mention X"), names the sibling whose arguments it shares (search_narratives), and advises narrowing with date/company/product. It stops short of an explicit when-not (e.g., use search_narratives when you need the actual narrative text), so routing is strong but not fully closed.

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

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

No annotations are provided, so the description carries the full disclosure burden. It reveals the shape of the return content (counts, ranges, coverage, freeze), which is genuinely useful, but says nothing about whether the call is cheap, cached, side-effect free, or how large the response is. For a zero-parameter read tool the risk is low, but the disclosure is still thin.

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

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

Two short sentences, the content inventory first and the usage cue second, with no filler. The phrase 'the narrative freeze' is domain jargon left unexplained, which slightly blunts an otherwise tight statement.

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 parameters and no output schema, the description is the only place an agent can learn what comes back, and it does list the returned fields. It is sufficient to call the tool correctly, though it could say more about the scale or freshness of the metadata.

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 takes no parameters, so there is nothing to disambiguate; baseline 4 applies. The description instead spends its words describing the payload, which is the right use of the space.

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

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

States a specific resource (this dataset) and enumerates the concrete content it reports: row counts, date ranges, narrative coverage, and the narrative freeze. It is clearly the metadata/overview tool rather than a data-query tool like search_narratives or count_narratives, though it never explicitly names a sibling to sharpen the contrast.

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?

'Call first when unsure about coverage' gives a clear triggering condition and implies priority ordering relative to the other tools. It stops short of naming which alternative to use once coverage is known, so it is strong but not fully prescriptive.

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

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

No annotations exist, so the description carries the full behavioral burden. It does disclose that results are disambiguated name variants with complaint counts and first/last dates, which is useful, but it says nothing about matching semantics (exact vs substring), the effect of the limit default of 25, ordering, or truncation, which matters for an unfiltered lookup.

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

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

One dense but well-ordered sentence: purpose first, then the disambiguation rationale with examples, then the hand-off guidance. Nothing is redundant, though the example list and the two-branch closing clause make it longer than a minimal statement.

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?

An output schema exists, so return values need not be spelled out, and the description still flags the useful parts (counts, first/last dates). It is close to complete for a lookup tool; the remaining gap is that an agent cannot tell whether the search is exact-match or contains-match, which is precisely the distinction the sibling company_contains hinges on.

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 0% across two parameters. The description gives partial meaning to 'name' (it may be a firm name whose variants are returned, and exact names are the portable form), but 'limit' is never mentioned and no format or matching rules for 'name' are supplied, so it only half compensates for the coverage gap.

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

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

States a specific verb and resource ('Find companies by name') and immediately explains the CFPB naming-variant problem that gives the tool its reason to exist, citing concrete examples ('EQUIFAX, INC.', 'Equifax Information Services LLC'). It also implicitly separates itself from company_profile and company_contains, so an agent can route without opening a schema.

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

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

Explicitly tells the agent what to do with the result ('pass the exact names you want to other tools via company') and names the alternative path for the bulk case ('use company_contains for all variants at once'). That is a when-to-use plus a when-to-use-something-else in one sentence.

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

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

With no annotations, the description carries the full burden and does add real behavioral value: it discloses what comes back (all structured fields) and a conditional return rule (full narrative only when archived). It does not cover failure behavior for an invalid/missing ID, so it falls short of full transparency.

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

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

One sentence, front-loaded with the action and resource, with the return detail appended where it belongs. No padding or redundant restatement of the 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 one-parameter read with no output schema, the description usefully sketches the return payload and its archive conditionality. It stops short of error/not-found semantics, which is the only meaningful remaining 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 0%, so the description must compensate, and it does by naming the identifier domain ('CFPB Complaint ID') rather than leaving the bare integer unexplained. A single self-evident required key limits how much more could be said.

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

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

States a specific verb and resource ('get one complaint') plus the lookup key ('by its CFPB Complaint ID'), so the agent knows this is a single-record fetch rather than a search. It does not name a sibling (e.g., search_narratives) to draw the boundary explicitly, but the singular-by-ID framing 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?

Usage is only implied: the 'by its CFPB Complaint ID' phrasing signals the precondition (you must already have an ID), which distinguishes it from search tools. There is no explicit when-to-use/when-not statement and no mention of the alternative to pick when you lack an ID.

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

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

No annotations exist, so the description carries the full burden. It does add real behavioral detail (field enumeration, case-insensitive vs exact matching, date formats, substring vs exact semantics), but omits any mention of permissions/auth, result limits beyond the 'limit' default, or the shape of returned counts. Adequate but not rich.

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 purpose and field enumeration are front-loaded and efficient. The closing filter list, however, is both verbose and largely irrelevant to this tool's four parameters, so a meaningful portion of the text does not earn 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?

An output schema exists, so return values need not be described. Given 0% schema coverage and 4 params, the description covers the critical field/search/product semantics well but leaves 'limit' undocumented and pads with filters that aren't real parameters, so it is partially complete rather than fully so.

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 0%, so the description must compensate: it enumerates all valid 'field' values (the required param) and explains 'search' and 'product'. But it also lists a long set of 'filters' (company, sub_product, tag, timely, date_from/date_to, etc.) that do not exist in the input schema, which muddies rather than clarifies the actual parameters, and 'limit' is never explained.

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 ('List the values of a field with complaint counts') and adds the goal ('to find exact product/issue/response names'), which distinguishes it from siblings like complaint_counts and find_company. An agent can tell what it returns 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?

Implied usage is present ('to find exact product/issue/response names' signals this is a lookup/discovery step before filtering), and it cross-references find_company for exact company names. However, it never states when to prefer this over siblings like complaint_counts or compare_companies, so routing is left to inference.

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

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

With no annotations present, the description carries the full burden and does so: it discloses the data is frozen at 2026-08-14, that results are date-ordered rather than relevance-ranked (a real surprise for a 'search' tool), that every result contains all words, that snippets plus structured fields are returned, and that unfiltered searches can time out. This is unusually rich behavioral context.

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

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

A dense single block, but front-loaded with the core purpose and each subsequent clause carries a distinct piece of information (query semantics, return shape, filter guidance, timeout warning). It would read better split into a few short sentences, hence not a 5.

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

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

An output schema exists so return values needn't be fully specified, yet the description still summarizes the return shape and ordering. Combined with the freeze date, timeout caveat, filter performance notes, and the get_complaint handoff, an agent has everything needed to call this correctly for a 16-parameter 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 0% across 16 parameters, so the description must compensate, and it largely does: it defines the mutual semantics of query/phrase/any_of (all-words vs exact phrase vs alternatives), state as 2 letters, date formats as YYYY-MM-DD or YYYY-MM, and separates fast filters from slower ones. It omits limit/offset and does not say whether the three query modes are combinable or exclusive.

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 ('keyword search over archived complaint narratives') and immediately distinguishes itself from the sibling get_complaint by noting that get_complaint returns the full text while this returns only a snippet. The frozen-date note pins down exactly what corpus is being searched.

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

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

Explicit routing to the alternative ('use get_complaint for the full text') and explicit escalation guidance ('narrow with date_from/date_to, company/company_contains, product or state when you can: an unfiltered search over all years can time out'). It also flags which filters are slower, which is actionable when-not guidance.

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

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

With no annotations the description carries the full burden, and it does disclose non-obvious data semantics: the latest period is partial, 'In progress'/'Untimely response' are response categories not outcomes, and product names were renamed by CFPB. It stops short of stating read-only behavior or any result-size limits.

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

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

Purpose and caveats are front-loaded before a compact filter list. Dense but every clause carries semantic content; the only waste is scope noise such as mentioning sub_product and timely, which are not in the schema.

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

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

An output schema exists so return format need not be explained, and the filter semantics, period behavior and data caveats are covered. What is missing is the relationship to sibling tools and how multiple filters combine (AND semantics) for an 11-parameter query.

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 0%, so the description must compensate and it largely does: exact vs substring matching for company vs company_contains, case-insensitivity for company_response, 2-letter state format, YYYY-MM-DD/YYYY-MM date formats, and the date-received basis. It even adds guidance to use list_values for disambiguated product names.

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

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

States a specific verb+resource: aggregated complaints over time at month/quarter/year granularity for a single filter set. An agent can distinguish it from complaint_counts or company_profile, though the description never names an alternative explicitly.

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

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

It explains how to fill in filters and what period values mean, which implies the use case, but it never says when to choose this tool over siblings like complaint_counts or compare_companies. Usage is inferable rather than stated.

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