apis-io

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

Annotations already disclose the safety profile (idempotentHint=true, destructiveHint=false), so the description's main addition is cost context (B1, $0.01/call) and the note that 'context' is never used to rank. It does not state what happens on duplicate members beyond what idempotentHint implies, so the added value is moderate.

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 core action is front-loaded in a single clause, with pricing appended as a secondary pointer to apis://prices. Efficient overall, though the 'UNDERSTANDING —' prefix is slightly noisy.

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 three-parameter mutation with no output schema, the description covers the core action and cost, but omits operational details that would help an agent (e.g., behavior on duplicates, whether the list must be owned, partial-failure handling). Adequate but with clear 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 description coverage is 100%, so the schema already documents all three parameters, including the 'aid' format example. The description only echoes the 'by slug or aid' phrasing, which the member schema already covers. Baseline 3 is appropriate.

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

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

States a specific verb (add), resource (providers/APIs), target (one of your lists), and the accepted identifier forms (slug or aid). It is readily distinguishable from siblings like create_list, delete_list, and get_list.

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

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

No when-to-use guidance is given: it doesn't say when to add vs. create a new list, nor does it mention prerequisites such as obtaining the list id first (only the schema hints at this). The only context is the pricing tier, which is not usage guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine non-annotation context: the pricing tier (B1, $0.01/call, included in Understanding and Influence) and a pointer to apis://prices. It adds no detail on pagination, ordering, or result shape beyond what is stated as output.

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 core semantics are front-loaded in the first sentence, which is good. However, the second sentence is editorial sales copy ('The denominator every ... claim needs and almost never has') that consumes space without adding invocation-relevant information. The pricing sentence is useful; the rhetoric is not.

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 some of the return-value burden and does state the shape (counts and shares per dimension). Combined with annotations covering the safety profile, this is adequate but thin: ordering of dimensions, the meaning of the share denominator, and pagination behavior are not addressed.

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 three parameters (page, limit, context) are fully documented in the schema, including defaults and bounds. The description adds no parameter-level meaning, so the baseline of 3 applies when the schema does all the work.

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 output: for each agent-readiness dimension, the count of scored providers satisfying it as a share. That is a concrete verb+resource (aggregate readiness dimension coverage). It does not explicitly distinguish itself from siblings like insights_dimensions or get_agent_readiness, but the shape of the result is clear enough to route on.

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

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

There is no explicit when-to-use guidance or named alternative. The sibling list contains several near-neighbors (insights_dimensions, get_agent_readiness, find_agent_readiness, readiness_gates), and the description does not say which condition selects this one over them. The closest thing to guidance is an editorial justification ('the denominator ... claims need').

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 annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe read against a closed catalog. The description adds that results are top matches per section with total match counts, which is useful return-shape context. It does not elaborate on pagination limits, authentication, or ranking behavior beyond what the annotations and schema provide.

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

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

The description is front-loaded with 'START HERE' and then proceeds in compact, information-dense sentences. Every sentence earns its place by covering purpose, filters, limit behavior, and alternatives. There is 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?

Despite 14 optional parameters and no output schema, the description explains the federated return shape, what each section contains, and how results are scoped. It also routes the agent to alternatives when pagination or single-type listing is needed. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the input schema already documents all 14 parameters, including enums and defaults. The description reinforces the filter categories and clarifies that limit applies per section, but it adds little syntax or semantics beyond the schema. A baseline score of 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: a federated search of the APIs.io catalog across APIs, providers, and tags. It clearly differentiates this federated overview from the sibling type-specific search and entity-lookup tools. An agent can tell exactly what this tool does 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?

It gives explicit routing guidance with 'START HERE' and directly names alternatives for other needs: use find_apis / find_providers / find_tags for paging or sorting a full list of one type, and get_api / get_provider for a single entity. It also states the supported filter dimensions. This is strong when-to-use and when-to-use-something-else guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's useful additions are the plan gating requirement, the reviewer-notes payload, and the cost ($0.01/call, B1 tier, included in Understanding/Influence). Authentication/quota and billing disclosure is genuinely beyond what the annotations convey.

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

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

The core purpose is front-loaded in the first clause, and the remaining sentences each carry actionable information (plan prerequisite, error-reporting alternative, price). The unexplained 'INFLUENCE —' prefix and the trailing 'See apis://prices' pointer are the only mild clutter.

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

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

With no output schema, the description usefully enumerates the terminal and intermediate statuses plus the reviewer-notes field, and it covers the plan gate and pricing. Error/not-found behavior and whether polling is expected are the only notable omissions; still solid for a two-param read tool.

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

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

Schema description coverage is 100%, so both parameters are already documented; the description only restates that the id identifies the request, without adding format or sourcing detail beyond what the id schema note ('returned by request_check, or my_checks lists') already provides. 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+resource (fetch the status of a check request by id) and even enumerates the possible return values: queued, in_review, running, done, rejected, needs_info. It does not explicitly contrast itself with the closely related siblings request_check or my_checks, which is why 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?

Gives a real prerequisite (the Influence plan is now required to read the request back) and routes error reporting to report_correction or a repo issue rather than this tool. That is clear context plus an explicit alternative, but it never states the intended flow (call after request_check to poll).

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

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

Goes well beyond the annotations: returns 202 with a token and the hosts to be checked, requires publishing a DNS TXT record or a /.well-known/apis-io-challenge file that must stay up, and a human verifies and emails. It also discloses pricing ('B4, human work, no charge') — valuable for a non-readOnly mutation with no output schema.

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

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

Front-loads the action and outcome, then the verification mechanics and pricing. Every sentence carries information, though the pricing/uri reference is slightly tangential to invocation.

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

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

With no output schema, the description carries the return contract itself (202, token, hosts) and the full async verification workflow, so nothing an agent needs to call or follow up correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both slug and context. The description adds no extra parameter syntax or format guidance beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ('ask to claim a listing as yours') and implicitly distinguishes itself from the read/track sibling by routing tracking to check_status. An agent can tell this is a claim-submission tool 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 clear context (claiming ownership) and an explicit follow-up route: 'Track it with check_status' plus 'there is nothing else to call', which heads off redundant calls. It does not explicitly contrast with adjacent siblings like watch_listing or unwatch_listing, so it falls short of a full 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=true and openWorldHint=false, so the safety profile is covered. The description adds substantive behavior beyond that: byte-budgeted chunked pagination with the complete/next_cursor loop, and cost disclosure ($0.05/call, tier B2, included in Understanding/Influence). Auth requirements and rate limits remain unstated.

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

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

Front-loads the purpose, then layers pagination and pricing. Every sentence is load-bearing, though the pricing sentence and 'See apis://prices' add bulk that could be trimmed for a description primarily used for selection.

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

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

With no output schema, the description carries the burden of explaining returns and does so partially: artifact counts by type, satisfaction dimensions, and the complete/next_cursor paging fields. It stops short of describing the shape of individual entries, but an agent has enough to call and iterate 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 kind, slug, cursor and context, including the enum values. The description reinforces the cursor/next_cursor paging contract but adds no meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource: what members of a cohort publish — artifact counts by type plus the agent-readiness dimensions each satisfies. The 'capability matrix behind a market report' framing distinguishes it from siblings like cohort_scores, cohort_rankings and cohort_stats 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?

Gives a usage context ('the capability matrix behind a market report') and detailed pagination instructions, but never explicitly contrasts with the many sibling cohort_* tools or states when NOT to use this one. Usage is implied rather than routed.

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

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

Annotations only certify readOnly/openWorld=false, but the description goes well beyond that: full cost model ($0.005/request + $0.0002/record, less past 100, capped at $0.50), plan gating (pay-as-you-go, Understanding, Influence), an estimate endpoint, and a hard data-shape limit ('facet rollups cannot name the checks underneath them'). This is exactly the extra context annotations cannot carry.

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 intent statement is front-loaded in the first clause and no sentence is pure filler, but roughly half the text is pricing/tier boilerplate that could have been a single pointer to the prices resource. Efficient, though not maximally tight.

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

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

With no output schema, the description does describe the result conceptually (failing checks ranked by lift to the cohort mean) and covers access tier and cost. Remaining gaps — exact record shape and pagination interaction with the per-record price — are minor for a read-only cohort 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 description coverage is 100%, so kind, slug, page, limit and context are already fully documented in the schema. The description adds no syntax, format, or example detail beyond that ('Named checks only' constrains output shape, not parameters). Baseline 3 is correct when the schema does the heavy lifting.

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

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

Specific verb+resource: it returns the agent-readiness checks a cohort most commonly fails, ranked by impact on the cohort mean. It differentiates from the nearest sibling explicitly ('The inverse of gap_analysis, which says where a market is under-served; this says where it is failing the rubric'). An agent can select this without opening any other schema.

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

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

Names the alternative (gap_analysis) and the condition that separates them, and adds a real usage constraint ('Named checks only — facet rollups cannot name the checks underneath them'). It does not, however, route among the other cohort_* siblings (cohort_scores, cohort_rankings, cohort_capabilities, cohort_stats), so the guidance is clear but not exhaustive.

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

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

Goes well beyond the readOnly annotation: it discloses the return shape (MEAN over members present each date plus members_scored), the attribution caveat (membership shifts as the catalog grows), and full pricing/plan details ($0.05 B2, included in Understanding and Influence, apis://prices). This is exactly the extra context annotations can't 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?

Front-loaded with the core purpose, then returns and pricing. Mostly earns its length, though the editorial aside ('a move you cannot attribute to scores rather than population is not a finding') is slightly discursive for a tool definition.

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

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

With no output schema, the description carries the return-value burden and does so (MEAN and members_scored), plus pricing and the key membership caveat. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so kind/slug/context are already documented and the description's cohort framing adds little param-level detail beyond what the schema states. Baseline 3 applies when the schema carries parameter semantics.

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

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

Opens with a specific framing — 'the SET-LEVEL time series' of Kin Score and agent readiness — and explicitly positions it against the per-provider series and whole-dataset licence it sits between, so an agent can tell what it returns. The verb is descriptive rather than a crisp action verb, and it doesn't name the sibling tools (e.g. cohort_scores, get_rating_history) directly, keeping it from a 5.

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

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

Frames the use case concretely ('how has banking moved over six months had no answer') and contrasts it with the per-provider and whole-dataset alternatives, giving clear context for selection. It stops short of naming the actual sibling tools or stating explicit exclusions, so it's a strong 4 rather than 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=true and openWorldHint=false, but the description adds genuinely useful context beyond them: the dual-axis ordering, the interpretive note that the gap between a provider's two ranks is the story, and a full pricing model (per-request, per-record, cap, plan inclusion). Pagination behavior is left to the schema, which is acceptable.

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 the dual-axis distinction are front-loaded, and the pricing sentence, while long, carries information an agent needs to avoid a costly call. Slightly dense but no wasted sentences.

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

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

With no output schema and full schema coverage, the description supplies what's missing: what is returned (a leaderboard), how it's ordered (two divergent axes), how to interpret it, and the full cost model plus an estimate pointer. Nothing an agent needs to call it correctly and safely is absent.

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 kind, slug, page, limit, and context in detail. The description adds no parameter-level meaning (e.g., no example slugs or kind semantics), so it sits at the baseline for a fully-documented 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?

It states a concrete resource (a market leaderboard) and scope (ranked on two axes: Kin Score composite and agent readiness), which is far more specific than a tautology. It does not, however, explicitly contrast itself with close siblings like cohort_scores, compare_cohorts, or get_industry_leaders, so an agent must infer the boundary.

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 never says when to choose this over cohort_scores, cohort_stats, or the various *_leaders siblings, nor does it state prerequisites. The only procedural advice is about pricing (estimate first, see apis://prices), which is billing guidance rather than tool-selection guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely non-structured context: per-record pricing, the $0.50 cap, plan inclusion, and the directive to estimate at /api/v1/prices/estimate first — useful operational traits beyond the annotations.

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

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

Front-loaded with the purpose in the first sentence, and the pricing block is dense but each clause carries actionable information. Slightly verbose on billing detail, but nothing is truly wasted.

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

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

With no output schema, the description does describe what comes back (per-member scores, cohort average, delta), and it discloses cost and pre-call estimation. Only the sibling-relative 'when to use' dimension is thin.

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 kind/slug/page/limit/context are already documented in the schema; the enum and example are there too. The description contributes no additional parameter meaning, making the baseline 3 appropriate.

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

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

The description names a specific output shape — facet-level scores for every cohort member plus cohort average and per-member delta — which is materially distinct from siblings like cohort_stats or cohort_rankings. It stops short of naming those siblings explicitly, so an agent still has to infer the boundary.

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 framing ('A 60 in governance means nothing until you know the market sits at 45') plus the pricing/estimate guidance. There is no explicit statement of when to prefer this over cohort_rankings, cohort_stats, or compare_cohorts.

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

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

Annotations only declare readOnlyHint and openWorldHint, but the description goes well beyond: it discloses a guaranteed `coverage` block, `enrichment_depth` semantics, the ~42-point catalog_gap span, the caveat that cohort numbers partly reflect coverage rather than the market, and the pricing tier ($0.05 B2, included in Understanding/Influence, see apis://prices). This is exactly the extra operational context annotations cannot carry.

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

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

Front-loads the purpose before the caveats and pricing, and the coverage warning is high-value rather than filler. It is dense and long, with parenthetical detail (~42 points of catalog_gap) that is borderline for a tool description, but nearly every clause carries substance.

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

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

With no output schema, the description does the work of describing the returned sheet (statistics, coverage block, enrichment_depth, adoption rates) and even adds pricing. It is largely self-sufficient for calling correctly; the only missing piece is explicit routing among the cohort_* siblings.

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

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

Schema description coverage is 100% and each of the three parameters (kind enum, slug, context) is already documented in the schema. The description adds no extra meaning about kind/slug syntax or the enum values, so the baseline of 3 applies.

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

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

States a specific resource (the market-stats sheet / distribution for a whole market) and enumerates exactly what it returns: Kin Score mean/median/min/max/stdev, agent-readiness spread, band split, per-facet averages, artifact adoption. It is clearly a distribution-statistics tool rather than a ranking or listing one. However, it never names a sibling (cohort_scores, cohort_rankings, cohort_capabilities) as the alternative, so differentiation from close neighbors is left implicit.

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

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

Frames itself as the 'UNDERSTANDING' layer and tells the agent to read the coverage block before quoting the mean, which implies when the output is trustworthy. But it gives no explicit when-not or alternative-tool routing against the many cohort_* siblings, so selection guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully adds cost behavior ($0.05/call, B2 tier, included in Understanding/Influence), which is genuine operational context beyond the annotations, but says nothing about return format, latency, or result shape.

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

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

Two sentences, front-loaded with the core purpose before the pricing detail. It is reasonably tight, though the pricing/tier sentence is somewhat verbose and could be deferred to a pricing resource.

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, no-output-schema tool with fully documented params, the safety and parameter story is complete. However, the description never clarifies what a returned 'dimension' is or how many results to expect, leaving the agent guessing about output shape.

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

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

Schema description coverage is 100%, and the schema itself documents both slug and context fully, including the format example and the caveat that context is never used to rank. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb+resource: it returns a company's weakest investment dimensions ("where it is thin and a vendor could sell in"). The scope is clear, but it never distinguishes itself from close siblings like gap_analysis or industry_gap_analysis, which an agent could easily confuse it with.

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 no when-to-use or when-not-to-use guidance and names no alternatives, despite several near-synonymous siblings (gap_analysis, industry_gap_analysis, report_gap). The only implied usage is the vague 'UNDERSTANDING' framing and the sales-oriented aside, which is not actionable 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description goes further with the depth_confounded caveat and depth_note explanation, plus full pricing mechanics (per-request, per-record, cap, plan inclusion, estimate endpoint). It adds genuine behavioral context, though it says nothing about latency, caching, or failure modes.

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

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

Front-loads the understanding and return before the caveat and pricing, and every sentence carries information not present in structured fields. The pricing sentence is long and dense but is the only place that cost model is documented, so it earns its place.

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

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

With no output schema, the description steps up to describe exactly what comes back (both distributions plus per-dimension deltas), warns about the confound that would otherwise mislead interpretation, and documents the full cost path. Nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100%, including inline examples for a and b and the semantics of context ('never used to rank'). The description adds no parameter-level detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb+resource (side-by-side comparison of two cohorts on one rubric) and spells out the return: both distributions plus deltas on score, agent readiness, every facet and adoption rate. The framing question ('is US payments further along than UK banking?') makes it immediately distinguishable from single-cohort siblings like cohort_scores or cohort_stats.

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 clear usage scenario and an implicit when-not ('a report only ever covers one market'), so the agent knows this answers cross-market questions other tools can't. However, it never names a sibling alternative or an explicit exclusion, so routing against the many cohort_* tools is left partly 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 and openWorldHint=false, so the safety profile is covered. The description adds genuine non-redundant context: it is a billed synthesis call ($0.05, included in Understanding/Influence), names cheapest_entry as a computed output, and discloses provenance (quoted figure + date read).

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 output enumeration is front-loaded and informative, but the single em-dash-chained sentence is dense and overloaded, and the pricing/tier sentence plus apis://prices pointer add bulk beyond what is needed to select and call 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?

With no output schema, the description does the work of describing the return payload in detail, which is exactly what is needed. It stops short only on pagination/limits and explicit alternative-tool routing, minor for a bounded 2-param comparison call.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description confirms the 2+ provider requirement but adds no syntax, slug-format, or context-parameter detail beyond what the schema already documents.

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 resource (providers) and enumerates the distinct outputs — composite/band, per-facet leaders, artifact-coverage matrix, economics — so an agent can distinguish it from get_provider or find_providers 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?

The '2+ providers side by side' phrasing implies the use case, but there is no explicit when-to-use guidance, no exclusions, and no routing against adjacent siblings like match_providers, find_similar_providers, or compare_cohorts.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: output contents, the replan-loop mechanism, and explicit pricing ('B2 cross-catalog synthesis — $0.05 per call', included in Understanding and Influence, see apis://prices). The 'POST back ... via the replan link' phrasing is slightly risky (an agent could misread POST as an action of this tool) but it is scoped to the replan link, not this call.

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 core purpose is front-loaded, but the opening is one very long run-on clause chaining seven or eight deliverable types, which is hard to parse at a glance. Sentences do carry information (deliverables, invocation modes, pricing) with little pure filler, but bullet-style structure would serve better than the packed em-dash list.

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

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

With no output schema, the description must carry the return contract, and it does: it enumerates the affordance fields, the contract location pointer, Arazzo workflow matching, and provider rate limits/pricing. Combined with 100% schema coverage for six parameters and read-only annotations, an agent has enough to call this correctly; only the exact response envelope shape is left implicit.

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

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

Schema coverage is 100% and the parameter descriptions already explain goal-vs-operations ranking and give a state example. The description restates the operations-from-plan_goal and goal-ranking semantics and clarifies that state.done/state.have is the state shape, but adds little 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+resource: produces hypermedia affordances for a goal across providers, enumerating exactly what each affordance carries (href, HTTP method, safety/idempotence, path params, contract location, Arazzo workflow, rate limits/pricing). It also names plan_goal as the upstream source of operations, which orients the agent within the workflow. Jargon-heavy ('INFLUENCE — hypermedia') but the concrete output list keeps it from being vague.

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

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

Gives two explicit invocation modes: pass `operations` from a plan_goal bundle, or pass a `goal` to rank within the providers. It also explains the follow-up loop: POST state.done/state.have via the replan link to get what is possible now. Clear context, though it never states when NOT to use this versus plan_goal or find_operations.

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

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

Annotations only declare this is a non-read-only, non-destructive write. The description adds real behavioral context beyond them: returns 202, changes are applied by a human (async, not immediate), score/band are ignored, and the pricing model (included in Influence, else $49 one-off with its own receipt, never from prepaid balance).

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

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

Front-loads purpose and constraints, and each clause carries operational weight (review, pricing, routing). The one editorial aside about 'a marketing surface, not a catalog' is justification rather than instruction and could be trimmed, but overall it is dense without padding.

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 submission/mutation tool with no output schema and no annotations on outcome, the description covers the async 202 result, human review, non-settable fields, pricing, and the free alternative. An agent has everything needed to call it and interpret the response.

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 with examples, making the baseline 3 appropriate. The description names 5 of the settable fields but adds no syntax or format detail beyond what the schema provides, and says nothing about slug (required), contact, or context.

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

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

Opens with a specific verb (propose corrections) and resource (what we say about you), then enumerates the settable fields: name, description, url, industries, tags. It also distinguishes itself from the sibling report_correction and from owner-settable score/band, so an agent can tell it apart without opening the schema.

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

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

Explicitly routes the agent: use report_correction instead 'if this is your own company and our data about it is wrong' because it is free. States the condition, the alternative tool, and the reason, which is exactly the when-to-use/when-not guidance an agent 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 only tell the agent this is not read-only and not destructive. The description adds meaningful behavior beyond that: the list is persistent, ownership is asserted, and the call requires an API key and carries a cost (B1, $0.01/call). It does not cover duplication behavior or what the call returns, but the added context is substantial.

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 naming purpose, then short trailing clauses for auth and pricing. No waste, though the pricing tier code and price pointer add slight noise relative to a simple create operation.

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 3-parameter creation tool with no output schema, the description covers purpose, persistence, auth requirement, and cost. It omits what is returned on success (e.g. a list identifier needed for subsequent add_to_list calls) and any naming/duplication constraints, but the core is complete.

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

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

Schema description coverage is 100%, so the schema already explains name, context, and members in detail. The description adds nothing about parameter formats or the seeding behavior of 'members' beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb+resource with scope: 'Create a named, persistent list ... of providers or APIs', and characterizes it as a shortlist/stack the caller owns. This is clearly distinguishable from siblings like add_to_list, get_list, and list_lists.

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 names the required apis.io API key and the pricing tier, which is useful context, but it never states when to create a list versus adding to an existing one (add_to_list) or when a list is preferable to a saved search. Usage is left implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered by structured fields. The description adds the ownership/authorization constraint, but does not say whether the delete is permanent, what happens to list items, or whether it can be undone.

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 is front-loaded in the first phrase and the rest is a compact pricing/tier note. The pricing sentence is metadata rather than tool semantics, which is slightly off-topic but brief and genuinely useful for cost-aware agents.

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 destructive tool with full schema coverage, a rich annotation set, and no output schema, the description plus structured fields give an agent enough to invoke it correctly. The only material omission is the consequence of deletion (permanence, effect on list items).

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 `context` are already documented in the schema. The description adds no syntax or usage detail for either parameter, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Delete a list") plus a scoping constraint ("you own"), which cleanly separates it from create_list, get_list, and add_to_list. An agent can identify the operation 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?

There is no guidance on when to use this versus alternatives, and no mention that deletion is irreversible or what to do instead (e.g., set_visibility or unwatch_listing). The only usage hint is the ownership precondition embedded in the purpose 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is fully covered structurally. The description only adds the ownership precondition, which is mildly useful, but says nothing about irreversibility, cascade effects, or behavior when the caller doesn't own the search.

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

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

Front-loads 'UNDERSTANDING —' branding followed by a long pricing sentence ('Priced B1 (single-entity synthesis) — $0.01 per call... See apis://prices') that does not help the agent select or invoke the tool. Only the middle clause is load-bearing, so the text is bloated relative to its information content.

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

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

For a simple single-entity delete with full annotation coverage and 100% schema description coverage, the description is adequate. However, it omits error/ownership-failure behavior and offers nothing beyond the annotations on the destructive operation, so it is minimum viable rather than complete.

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

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

Schema coverage is 100%, and the schema already explains both 'id' and 'context' clearly, so the baseline is 3. The description adds no 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?

States a clear verb+resource: 'Delete a saved search you own.' The ownership scoping distinguishes it from siblings like list_saved_searches, run_saved_search, and save_search. Only the irrelevant branding/pricing prefix dilutes an otherwise precise purpose statement.

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

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

No when-to-use guidance and no named alternatives (e.g., delete_list vs delete_saved_search). The 'you own' phrase is a precondition, not usage guidance. The agent must infer all context for calling 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 safety (readOnlyHint true, openWorldHint false), yet the description adds substantial context the agent needs: a concrete pricing model with caps, the pay-as-you-go vs. Understanding/Influence inclusion, and an estimate endpoint pointer. That is real behavioral disclosure beyond the structured fields, though it omits pagination/return-shape 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?

Purpose and scope are front-loaded in the first sentence, and the drill-down guidance follows logically. The 'which nothing could see before' phrasing is promotional filler that dilutes an otherwise efficient paragraph.

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 aggregate tool with no output schema, the description supplies the essentials: what it returns (a ranked provider list), the scale of the result set, the drill-in alternative, and the pricing/cost model the agent must weigh before calling.

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 page, limit, and context are fully documented in the schema itself. The description adds no parameter-level syntax or meaning, so the baseline 3 applies.

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

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

The description names a specific resource (providers that publish at least one deprecated operation) and a specific ordering (ranked by count). It clearly distinguishes itself from get_provider_operations, which it frames as the drill-down rather than the aggregate view.

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 an explicit follow-up path ('Drill in with get_provider_operations(deprecated=true)') and frames the tool's niche as lifecycle-level discovery vs. per-provider filtering. It does not state exclusions, but the when-to-use is clear.

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

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

Annotations only give readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the description carries most of the burden and does deliver: it discloses the 202 response, the human-review-and-email workflow, the no-ownership-required policy, and the pricing ($49 one-off, B4, never from a prepaid balance). Ratings on the response outcome and latency are not given, but the behavioral picture is unusually 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 action is front-loaded, but the 'INFLUENCE — "you say we lack X, here it is"' framing and the dense pricing/policy sentences add verbosity ahead of the operational facts. Several sentences do earn their place (pricing, ownership, alternative), but the register is padded.

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

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

With no output schema, the description usefully explains the return lifecycle (202, human verification, email either way), eligibility, pricing, and the sibling alternative. It is close to complete for a submission tool, though it could state expected turnaround or what 'checks it against what we hold' yields.

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

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

Schema description coverage is 100%, so all five parameters (slug, claim, contact, context, evidence_url) are already documented in the schema. The description only restates 'the claim in words and a URL' — it adds no syntax, format, or constraint meaning beyond the schema, so the baseline 3 applies.

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

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

The description states a concrete action — 'Send the claim in words and a URL that evidences it' — so an agent knows it submits a dispute with evidence. It also names a sibling (report_correction) and the condition that selects it. The 'INFLUENCE — ...' marketing opener somewhat obscures the verb at the front, keeping it short of a clean 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?

Explicitly says who may call it ('Open to any paying caller') and when to use the alternative ('If this is your own company and our data about it is wrong, report_correction is free'). This gives an agent a clear routing rule, though no explicit 'do not use for X' exclusions beyond the report_correction case.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description is consistent with them while adding real value beyond them: per-call pricing ($0.05 B2 tier), plan inclusion (Understanding and Influence), a dated migration note about base groups, and the assurance that the context parameter is never used to rank. It does not describe failure modes, rate limits, or response shape.

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 value proposition and the group list, and every sentence carries information (scope, groups, pricing, migration). The pricing and the 'Understanding plan — the base groups moved...' clause are dense and the latter is ambiguous about what actually changed, slightly diluting an otherwise efficient description.

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

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

With no output schema, the description correctly compensates by stating that it returns exactly the requested groups and by enumerating the valid groups and defaults. Pricing and plan coverage round out the operational picture; only failure/edge behavior is unaddressed, which is minor for a read-only enrichment call.

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

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

Schema description coverage is 100%, so the schema already documents id, fields, and context in detail; the description restates the group list and the default set without adding syntax or format detail beyond it. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource (enrich a provider) and immediately names the four sibling tools it replaces (get_provider, get_provider_rating, get_provider_artifacts, get_provider_onboarding), plus enumerates the available field groups. An agent can distinguish this from the chained-call siblings without opening any schema.

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

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

Explicitly frames the when-to-use case: one call instead of chaining get_provider + get_provider_rating + get_provider_artifacts + get_provider_onboarding, and explains the selection mechanism ('pick your field groups'). It names the alternatives clearly but offers no when-not-to-use guidance or prerequisites (e.g., when a single cheap get_provider call suffices).

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

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

Annotations only declare readOnlyHint=true and openWorldHint=false; the description goes well beyond that by disclosing byte-budgeted chunking, the `complete`/`next_cursor` continuation contract, the attribution + rubric-citation obligation, and concrete pricing ($0.002/row, $0.50 minimum, plan inclusions). These are exactly the operational facts an agent needs and none of them are in 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?

Dense but mostly earned — each clause covers dataset contents, paging, licensing or pricing. The main flaw is front-loading: the first five words are a licence/plan parenthetical rather than the core action, and the per-dataset payload detail is long enough to be skimmed. Still, no sentence is pure filler.

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

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

With no output schema and no required parameters, the description carries the return-shape burden itself and does so — chunked `data`, `complete`, `next_cursor` — plus attribution and cost so the agent can decide whether a bulk licence call is appropriate. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds substantive meaning: it expands each `dataset` enum value with the actual payload contents (facets/trend/rubric+provenance; parallel date/composite/agent_readiness arrays; movement summary) and restates the cursor continuation rule as part of the paging loop. Only `co_brand` and `context` get no added 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?

States a specific verb (export) and resource (dataset), then enumerates the three exports (`ratings`, `providers`, `history`) and what each contains. It also draws an explicit boundary against the paged search siblings — 'the WHOLE dataset, not a 100-row page' — so an agent can tell it apart from find_ratings without opening a schema.

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

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

Gives a clear audience/condition ('for media outlets and analysts licensing the data to publish rankings and trends') and singles out `history` as the one that cannot be reconstructed after the fact, which is a real selection signal. It never names the alternative tool (e.g. find_ratings, export_stack) or states when NOT to use it, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds genuinely useful behavior beyond that, namely the exact output artifact produced (APIs.json + Arazzo hint) and full pricing terms (B3, $0.002/row, $0.50 minimum, plan inclusions). No contradiction with the read-only hint.

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 output format are front-loaded before the pricing sentence, and there is little wasted text. The leading tier label 'UNDERSTANDING —' is the one piece of structural noise.

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 export tool with no output schema, the description names the produced artifact and pricing, which is what an agent needs to decide and budget. It is only missing usage routing, which is scored separately.

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 region, context, and capabilities (with an example) on its own. The description adds no syntax or format detail about the parameters, so the baseline 3 applies.

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

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

States a specific verb (Export) and resource (a designed capability stack) plus the concrete output form: an adoptable APIs.json document with an Arazzo hint. The 'UNDERSTANDING —' prefix is tier noise, but the purpose itself is unambiguous and distinguishable from siblings like export_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 phrase 'the team can commit' hints at design-time use, but there is no explicit when-to-use, when-not, or named alternative (e.g. export_dataset or recommend_stack). The agent must infer routing from the resource name alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description goes further by disclosing the cost model ($0.005/request plus $0.0002/record, capped at $0.50), plan inclusion, the estimate endpoint, and what the response contains (agent score + band alongside Kin Score). That is well beyond annotation coverage, though pagination/limits behavior is left to the 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?

Front-loaded with the core purpose, then filters, then return/pricing. Dense but every clause carries information; the long pricing sentence is justified by the cost-sensitive nature of a per-record-priced tool. Slightly overstuffed in a single block.

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

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

With 8 optional params, no output schema, and no required fields, the description covers purpose, filter semantics, return contents, and cost. The main gap is not pointing to agent_readiness_dimensions for the valid dimension vocabulary, which an agent needs to construct has/missing values.

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 earns above baseline by interpreting the has/missing filters semantically (ANDed cohorts, 'gap view') and supplying real dimension names and example values. band, min_score, and sort get no extra explanation beyond the schema, keeping it at 4 rather than 5.

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 with scope: 'the agent-readiness leaderboard across the whole catalog. Rank providers by agent readiness' plus a filter capability. This is clearly a list/search tool over providers, distinguishable in practice from the singular get_agent_readiness, though no sibling is named explicitly.

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

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

Gives concrete usage patterns with worked examples: has="mcp_server,protected_resource_metadata" for the OAuth-capable MCP cohort and missing="agent_card" as the addressable market for a fix, which tells the agent when this tool is the right one. No explicit exclusions or named alternative (e.g. get_agent_readiness for a single provider) are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds valuable context beyond those annotations: free/no-account access, the self-registration mechanism, and the returned fields (card URL, operator, verification grade, protocol version, transport). 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 key access facts front-loaded. The final sentence uses a metaphor ('door an unattended agent can walk through unaided') that is slightly ornamental but still conveys meaningful differentiation about accessibility.

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 listing tool with no output schema, the description identifies the returned fields and access requirements, while the schema handles pagination parameters. It could mention result ordering or total counts, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so all three parameters (page, limit, context) are fully documented in the schema. The description adds no additional parameter syntax or behavioral details. Per the rubric, this baseline is 3 when the schema already provides full coverage.

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

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

Identifies the specific resource as the A2A agent registry and explains it contains agents that self-registered by serving an agent card and calling register_agent. This distinguishes it from register_agent, but the verb 'find' is only implied by the tool name, not stated in the description.

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?

States that the registry is FREE and needs no account, and that an unattended agent can use it unaided while others require a person or voucher. This gives useful context, but it does not explicitly say when to choose this over sibling tools such as find_agent_readiness or get_agent_readiness.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description still adds real behavior: results are paginated and sortable, q is a lexical match against the API's own name/description, and via_provider deliberately unions in provider-name matches (the same union apis_io_search counts). These are non-obvious behaviors an agent would otherwise get wrong. It does not discuss result volume limits or rate limits, keeping it out of the top band.

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 tight sentences: what it returns, how filtering works, the key caveat, the sibling alternative, and a docs pointer. Scoping information is front-loaded and nothing repeats the schema verbatim.

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 24-parameter, zero-required search tool with no output schema, the description covers purpose, filtering model, pagination, and a documentation escape hatch for the many enum/slug parameters. A brief note on the response envelope (beyond 'paginated') would make it fully self-sufficient, but it is adequate to call correctly.

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

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

Schema description coverage is 96%, so the baseline is 3; the description earns above baseline by clarifying the subtle interactions the schema does not spell out — the lexical scope of q and the union semantics of include=["via_provider"] needing q. It also delegates the full parameter reference to apis://docs/tools/find_apis, which is honest but leaves some depth external.

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

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

Opens with a specific verb and resource plus scope: 'Paginated, sortable list of APIs across providers', then enumerates the filter dimensions. It also explicitly differentiates itself from the sibling apis_io_search ('cross-type overview'), so an agent can choose between them without opening either schema.

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

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

Gives clear routing guidance ('Use apis_io_search first for a cross-type overview') and a conditional usage note for include=["via_provider"] which requires q. It stops short of stating when NOT to use this tool or naming get_api/find_similar_apis as follow-ons, so it is clear context without full 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 state readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that include=["content"] inlines bodies, but this repeats the schema, and it does not disclose pagination, return format, or any rate/auth behavior 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?

The description is short and front-loads the resource scope before filters and the sibling alternative. The second sentence is a fragment that slightly repeats the first, but it still earns its place by clarifying the indexed artifact type.

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 full schema coverage and read-only annotations, the description covers the tool's scope, key filters, inline behavior, and cross-type alternative. It could be slightly more complete about pagination or result shape, but no output schema exists and the schema covers those parameters.

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 nine parameters are already documented in the input schema. The description mentions q/tags/providers and include content but adds no syntax, format, or constraint details beyond what the schema provides.

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

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

The description names the specific resource ('APIs.json discovery documents themselves') and its scope ('indexes across the catalog'). It also distinguishes the tool from cross-type search by naming find_artifacts as the 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?

It gives clear usage context through filters (q / tags / providers) and explicitly routes cross-type searches to find_artifacts. It does not clarify when to choose this over other sibling type-specific finders such as find_apis, but the main alternative is handled.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the include=["content"] inlining behavior, but that is largely restated from the schema rather than new behavioral context (pagination, ranking, cost).

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 fragments, front-loaded with the resource definition before filters and the alternative tool. Telegraphic phrasing costs a little clarity but every sentence carries 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 read-only, no-output-schema search tool with full schema coverage and clear annotations, the description covers resource, filters, and alternative routing. No ranking or pagination detail is provided, but little else is needed to call it correctly.

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

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

Schema description coverage is 100%, so all nine parameters are already documented. The description mentions q/tags/providers filters and the include semantics, but adds no syntax or format detail beyond what the schema provides — the expected 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?

Names a specific resource (Arazzo workflows) and defines it as multi-step API workflows chaining operations, which distinguishes it from generic artifact search. No explicit verb, but the tool name supplies 'find' and the sibling find_artifacts is named as the cross-type 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?

Gives clear usage context ('Filter by q / tags / providers') and explicitly routes the agent away to find_artifacts for cross-type search. It lacks a when-NOT-to-use-a-filter statement, but the alternative routing is the key signal.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and the closed/curated nature of the data are covered structurally. The description reinforces that the index is curated and scored, but says nothing about pagination behavior, result count, or the shape of a returned area record.

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

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

Two compact clauses with the resource and its nature front-loaded, followed by the operating instructions. Slightly stylistic (em dash, trailing ellipsis) but no wasted sentences.

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, closed-world list tool with a fully documented five-parameter schema and no output schema, the description gives enough to call it correctly. It could optionally sketch what an area result contains (e.g., provider counts), which is the only 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 description coverage is 100%, so every parameter is already documented in-schema (q, page, sort, limit, context). The description only restates text search and provider-count sorting, adding no syntax or format detail beyond what the schema provides — the baseline 3 fits.

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

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

States a concrete verb+resource: browse the "areas taxonomy" with example members (authentication, webhooks, payments) and clarifies these are curated, scored provider indexes. The only shortfall is that it does not explicitly contrast itself with siblings like get_area or find_industries, so the agent must infer the find-vs-get distinction.

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

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

"Search by text; sort by provider count" tells the agent how to drive the tool, which implies the browse/filter use case, but there is no explicit when-to-use versus when-not, and no named alternative for retrieving a single area's detail (get_area) or its leaders (get_area_leaders).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond the schema: that scopes and security are PRO-gated, and that include=["content"] inlines bodies rather than returning URLs. It does not discuss pagination behavior or result limits, keeping it from a 5.

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

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

Front-loaded with the core purpose and the sibling routing rule, then supporting details. The long type enumeration partly duplicates the schema's type list but is defensible for a cross-type entry point; slightly dense overall.

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

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

For an 8-parameter read-only finder with no output schema, the description covers purpose, routing, type taxonomy, and the include behavior. It does not address pagination semantics or result shape, but with 100% schema coverage that gap is minor.

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 goes further by enumerating the type values and flagging which ones (scopes, security) are PRO-only, meaning that is not conveyed by the schema's type description alone.

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

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

States a specific verb (find) and resource (artifacts) and explicitly frames itself as the cross-type entry point. It distinguishes itself from the many find_<type> siblings by naming that pattern and its trade-off.

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

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

Explicitly says to prefer the dedicated find_<type> tools when the type is known, and positions itself as the fallback/any-type path. This is direct when-to-use vs alternative guidance with nothing left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds the include=["content"] inlining behavior, which is useful, but discloses nothing about pagination limits beyond the schema or rate/result characteristics.

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, front-loaded sentences with essentially zero waste. The fragmentary style is efficient but slightly telegraphic rather than polished.

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 catalog search with fully documented params and no output schema, the definition covers the essentials and names a sibling alternative. Minor gaps remain around result/return expectations.

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 11 parameters in detail. The description only echoes q/tags/providers and include without adding syntax or format meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific resource — AsyncAPI event-driven specifications — and clarifies scope as 'across the catalog,' with event/streaming APIs noted. It is clear but relies partly on noun fragments rather than a full verb+resource sentence, and sibling differentiation is only handled via the final sentence.

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 filter guidance (q / tags / providers) and explicitly routes cross-type searching to find_artifacts, which is a real alternative among the many find_* siblings. It stops short of stating when NOT to use it or listing multiple alternatives.

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

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

Annotations only declare readOnlyHint/openWorldHint, so the description carries the behavioral burden and does so well: it discloses that all=false is the default, that uncovered capabilities are 'a real answer rather than a gap', and full pricing behavior ($0.005/request plus $0.0002/record, volume discount past 100, $0.50 cap, pay-as-you-go, included in Understanding and Influence).

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

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

Front-loads the highest-value content ('START HERE', model size) and every sentence is functional, though the pricing clause is a dense run-on and reads slightly promotional ('Free.'). Still well under the size where it would obscure the primary 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?

For a read-only 6-param discovery tool with no output schema, the description covers purpose, default behavior, cost model, and even the shape of the results (capabilities with provider-coverage counts). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine semantics beyond the schema for `all` — explaining what the flag changes in the result set and why the zero-coverage rows exist. Other parameters (q, page, limit, industry, context) are left to 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 and resource ('find capabilities', the business-capability model of 333 capabilities across 28 industries) plus scope ('with how many catalog providers reach each one'). The 'START HERE for what can a business do with these APIs' framing distinguishes it from the many other find_* tools an agent could pick.

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

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

Gives clear entry-point guidance ('START HERE') and the key default-vs-alternative condition: defaults to capabilities the catalog actually reaches, pass all=true for the full model. It also advises estimating first at /api/v1/prices/estimate before calling. It stops short of naming an explicit sibling alternative (e.g. find_industries or get_capability) for narrower lookups.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe-read profile is covered. The description adds the useful behavioral note that include=["content"] inlines bodies rather than just returning URLs, but says nothing about pagination, result shape, or catalog scope beyond 'across the catalog'.

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

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

Three short sentences, front-loaded with the resource identity before filtering and the alternative. No filler, though the first two sentences overlap in describing the same resource.

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 an 11-param, zero-required search tool with no output schema and annotations covering safety, the description covers identity, filtering, the include behavior, and routing to find_artifacts. Pagination/sort are left to the schema, which is acceptable.

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 11 parameters with examples and enums. The description's mention of q/tags/providers and include merely mirrors the schema, adding no syntax or semantic detail beyond it. Baseline 3 is appropriate.

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

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

States a specific resource (AsyncAPI event channels, described as topics/streams) and distinguishes it from the catch-all sibling by naming find_artifacts for cross-type search. It does not explicitly contrast with the closely-named find_asyncapis, so the differentiation is good but not exhaustive.

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

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

Gives clear context (filter by q/tags/providers) and points to an alternative with a condition ('Use find_artifacts for cross-type search'). It omits guidance on when to prefer this over find_asyncapis, so it falls short of full when-not coverage.

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 readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful operational context beyond that: the full pricing model with per-record and per-request rates, the $0.50 cap, plan inclusion, and a pointer to /api/v1/prices/estimate and apis://prices. It does not describe result shape or pagination behavior, but pricing transparency is a real addition.

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 highest-value instruction ('START HERE'), followed by scope, routing, and cost. Dense but well ordered. The pricing sentence is long, though it is bounded by a pointer to apis://prices, so it earns most of its length.

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

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

For a 7-parameter discovery tool with no output schema, the description covers purpose, scope, routing to downstream tools, and cost — enough to call it correctly. The one real gap is that return shape/pagination is not hinted at, though the sibling routing partially compensates.

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 every parameter including the tier and kind enums, page/limit ranges, and min_providers semantics is already documented in the schema. The description groups the filter axes (kind, minimum population, promotion tier) but adds no format or behavioral detail beyond what the schema states, making the baseline 3 appropriate.

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

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

States a specific verb (find) and resource (cohorts), and defines the resource precisely as 'every scored population of providers' spanning tags, industries, regions, areas and VC portfolios. It also distinguishes itself from the many sibling find_* tools by positioning itself as the unified index rather than a single-roster 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?

Opens with 'START HERE for market-level questions' and explicitly routes the agent onward: cohort_stats for distributions, cohort_rankings for leaderboards. It also names the filtering dimensions, so an agent knows both when to pick this tool and how to move on from 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=true and openWorldHint=false, so the safety profile is covered. The description adds one behavioral note — include=["content"] inlines each body and the default returns 'just its URL', hinting at output shape and potential response-size cost. It adds no auth, rate-limit, or pagination behavior, so with annotations carrying the safety burden this lands at the baseline.

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 tightly front-loaded: resource and scope first, then filters, then the alternative. Every clause carries information and nothing is padded. The telegraphic 'Postman / Open collections' opening is slightly cryptic, which keeps it from a 5.

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

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

For a 9-parameter read tool with a fully-documented schema and no output schema, the description covers the essentials: what a collection is, the usable filters, the inlining option, and the cross-type alternative. Return format is only implied via 'instead of just its URL' and pagination behavior is left to the schema, which is acceptable given 100% coverage.

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 q, tags, providers, include, sort, and pagination with examples. The description's restatement ('filter by q / tags / providers; include=["content"] inlines bodies') adds emphasis but no meaning beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description names the resource and scope precisely — 'Postman / Open collections across the catalog' — and clarifies what a collection is ('runnable request collections'), which distinguishes it from type-specific siblings like find_openapis or find_mcp. It explicitly routes the agent to find_artifacts for cross-type search, so the agent can tell the two apart. The verb is only implied, keeping it short of a 5.

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

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

It names the alternative explicitly ('Use find_artifacts for cross-type search'), giving a clear routing condition that steers the agent away from this tool when searching across types. It also enumerates the filtering dimensions (q / tags / providers) which implies when this tool fits. It stops short of stating when-not-to-use this tool beyond that single alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: ranking behavior, per-record/per-request pricing with a cap, plan gating, and an estimate endpoint. It does not describe pagination behavior or return shape, but the pricing/plan detail is substantive.

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 core purpose and the industry-vocabulary caveat are front-loaded before pricing detail. The pricing sentence is long and slightly crammed, but each clause carries distinct operational information (rate, cap, plan inclusion, estimate path), so it largely earns its 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 read-only, no-output-schema discovery tool, the description covers purpose, ranking, parameter vocabulary, plan gating, and cost. The only notable gap is the relationship to get_company_insight and return/pagination shape, which is minor here.

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 goes further by explaining that `industry` takes an insights industry NAME from insights_industries rather than a catalog slug, and that it matches every roster a company sits on. This is valuable disambiguation, though it sits in tension with the schema's own example ("artificial-intelligence"), which is itself described as a slug.

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 (browse/find) and resource (profiled Fortune 1000 companies), plus the ranking signal (technology-readiness). It explicitly distinguishes its industry vocabulary from find_providers, so an agent can separate it from the catalog-side sibling without opening a schema.

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

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

Gives clear routing context: the industry parameter uses a different vocabulary than find_providers, and it notes the Understanding plan requirement. It does not address when to use this list tool vs the singular get_company_insight sibling, leaving that inference to the agent.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: "Membership is derived and known to be partial: read a count as a floor, not a census," which warns the agent about data reliability in a way no structured field conveys.

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 resource identity, then taxonomy relationship, then mechanics, then the data-quality caveat. Dense and largely waste-free, though the taxonomy aside is slightly expansive.

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 definition still gives the agent enough: what the dimension contains, the record-kind modes, and the critical caveat that counts are floors. Return-format gaps are minor since the tool is a simple filtered list.

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

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

Schema coverage is 100%, so the schema already documents all six parameters. The description restates the search-by-text and sort-by-count behavior already present in the schema, adding no syntax or format details beyond it. Baseline 3 is appropriate.

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

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

States a specific verb and resource ("Browse the country dimension") and situates it precisely within the place taxonomy, explicitly naming its peers find_industries / find_regions / find_areas. An agent can tell it apart from siblings without opening any schema.

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

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

The description clarifies that this is the finest of four place taxonomies and "the one a buyer usually names," which is genuine routing guidance, and names the peer tools. It stops short of explicit when-not-to-use conditions, e.g. when to call get_country or find_regions 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description goes beyond them by disclosing the ranking order (by member count), the pricing tier (B1, single-entity synthesis, $0.01/call, included in Understanding and Influence) and a pointer to apis://prices — real operational context an agent can act on.

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

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

Front-loads the definition of an estate, then the routing cue, then ranking and pricing. Every clause is relevant, though the pricing sentence is dense and could be tightened; the 'UNDERSTANDING —' label adds mild clutter.

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, four-parameter search tool with no output schema, the description supplies the concept, the ranking semantics, and cost. It does not describe the shape of an estate record (members, slugs), a minor gap given there is no output schema to lean 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 100% with four well-documented parameters, so the schema carries the semantic load. The description adds nothing about q, page, limit, or context, which is acceptable at this coverage level but earns only 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?

States a specific verb+resource (browse corporate estates) and defines the non-obvious domain concept: one company whose API surface spans many provider records, with concrete examples (Amazon 237, Salesforce 27). The ranking rule (by member count) further pins down what the tool returns, so an agent can distinguish it from provider-level tools like find_providers.

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 triggering condition: 'Use this when two slugs look like separate vendors and you need to know whether they are one company.' That is a clear when-to-use signal, but it names no alternative tool or exclusion, so it stops short of full 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one genuine behavioral detail — that include=["content"] inlines artifact bodies instead of returning only URLs — but says nothing about pagination behavior or result shape. With annotations carrying the safety load, this is a moderate addition.

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

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

Three short, front-loaded sentences with no filler. The only minor waste is the second sentence ('Real request/response examples'), which largely restates the first, but overall it is tight and scannable.

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 read-only search tool with no output schema, the description covers the resource, the filter levers, the include behavior, and the sibling alternative. Pagination and sort semantics live in the schema, which is fully documented, so the description is nearly complete, though it could say more about when to prefer it over other find_* siblings.

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

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

Schema description coverage is 100%, so all nine parameters (q, tags, providers, match, include, sort, page, limit, context) are already documented in the schema. The description repeats the filter names and the include behavior without adding syntax or format detail beyond the schema, so baseline 3 applies.

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

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

The description states a specific resource — example payloads (real request/response examples) across the catalog — and explicitly distinguishes itself from find_artifacts for cross-type search. The retrieval verb is only implied by the tool name rather than stated, which keeps it just short of a 5.

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

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

It gives an explicit alternative ('Use find_artifacts for cross-type search'), which routes the agent for one condition, and states the filtering levers (q / tags / providers) plus the include flag. It lacks broader when/when-not guidance and does not say what distinguishes this from other find_* tools beyond find_artifacts.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds real value beyond that by disclosing what the results carry — publisher, document counts, position in the document, value shape — and framing it against the OpenAPI Initiative registry. Pagination behavior is left to the schema, which is acceptable.

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?

Short two-sentence structure that leads with the resource and the provenance value proposition, then the control knobs. The first sentence is long but every clause carries information; nothing is redundant.

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 search tool with no output schema, the description usefully stands in for return-value documentation by enumerating the result fields. The only real hole is the undocumented `include_pipeline` flag, which an agent cannot reason about from any available field.

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 83%, so the schema baseline is 3; the description reinforces that `q` matches key or purpose and that `sort` accepts occurrences, but adds no syntax or default detail beyond the schema. `include_pipeline` has no description in either the schema or the description, leaving one parameter 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 and resource: browsing OpenAPI `x-` specification extensions harvested across the catalog, with the scope made explicit ('every'). It differentiates from get_extension implicitly (browse/list vs. fetch one) but never names the sibling, so the distinction is inferable 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?

'Search by key or purpose; sort by occurrences' hints at how to drive the tool, but there is no explicit when-to-use-it vs. get_extension guidance and no stated prerequisites or exclusions. An agent can guess this is the discovery/list counterpart to get_extension, but the description doesn't say so.

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 closed-world scope. The description earns credit by disclosing the result shape of meta (pricing category, method, provenance_date, primary_unit) and flagging `template: true` for sweep output lacking units/meters — genuinely useful context absent from any structured field.

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

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

Front-loads the domain, then packs filtering and the meta/template semantics efficiently. Dense and fragmentary in places but nearly every clause carries non-obvious information.

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

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

With no output schema, 11 params and a read-only profile, the description compensates by explaining the meta payload and template flag. It covers what an agent needs to interpret results, leaving only minor gaps like pagination behavior.

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 11 parameters are self-documented. The description restates q/tags/providers and include=["content"] filtering, which is largely redundant with 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 domain (FinOps/billing models and how usage is metered and billed) and scopes it as a catalog search. It is distinguishable from find_artifacts via the explicit cross-type routing note, though the opening is a noun phrase rather than a crisp verb+resource statement.

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 usage: filter by q/tags/providers, and inline bodies with include=["content"]. It names find_artifacts as the alternative for cross-type search, establishing when to prefer this type-scoped tool, but offers no explicit exclusion criteria or ranking caveats.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds one useful behavioral fact — include=["content"] inlines bodies instead of just URLs — but says nothing about pagination limits or result shape, which matters for a 9-param listing tool.

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 short clauses, front-loaded with the resource before the filters and the alternative. The "GraphQL type systems" fragment is near-redundant with the first sentence, a minor waste in an otherwise tight description.

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 filter-and-list tool with a fully described schema and read-only annotations, the description covers purpose, filters, the inline-body option, and the sibling alternative. No output schema exists, but return values are not described, which is the main 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 100%, so the schema already documents all nine parameters and the baseline is 3. The description restates q/tags/providers and clarifies the include semantics, but adds no format or interaction detail beyond what the schema provides.

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

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

The description identifies the resource concretely ("GraphQL schemas across the catalog. GraphQL type systems") and points to find_artifacts as the cross-type sibling, which lets an agent separate it from find_openapis/find_asyncapis. It relies on the tool name for the verb rather than stating one, and the second fragment adds little, but the resource 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?

"Filter by q / tags / providers" gives clear usage context, and "Use find_artifacts for cross-type search" names the alternative and the condition that selects it. There is no explicit when-not guidance beyond that, so it stops short of a full routing rule.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds only that results can be sorted, which is already exposed by the schema's sort parameter; it says nothing about pagination behavior, total counts, or result shape for a 5-parameter listing tool.

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 short clause, front-loaded with the verb and resource plus the sort hook. Nothing is wasted, though the extreme brevity edges toward under-specification rather than pure conciseness.

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

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

For a zero-required-parameter discovery tool with no output schema, the description is minimally adequate but omits what a browse call returns and how it relates to the industry detail/leader tools. It is complete enough to invoke, not to use optimally.

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% (q, page, sort, limit, context all documented), so the schema carries parameter semantics. The description merely restates the sort dimension ('provider/API count') and adds no format, default, or interaction detail beyond it. 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: 'Browse industry verticals'. The sort capability is also mentioned, so an agent knows this is a listing/discovery call rather than a detail lookup. It does not, however, name any sibling (e.g. get_industry, find_apis, insights_industries) to disambiguate.

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

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

There is no statement of when to use this tool versus alternatives such as get_industry (single industry) or find_apis/find_providers (entities within an industry), nor any prerequisite or exclusion. Usage is only implied by the word 'browse'.

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=true and openWorldHint=false, so the safety profile is set. The description adds non-obvious behavioral context: a partial paywall (count free, named firms gated behind Understanding), a per-call price, and a pointer to apis://prices. It does not describe pagination or result shape, but the added gating/cost detail is meaningful.

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

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

One tight paragraph, front-loaded with the capability statement, then gating and price. Every clause earns its place and nothing is repeated.

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 should carry more of the return-value burden; it only implies a count plus named firms and does not describe ordering, limits, or empty-result behavior. It is adequate for a simple lookup but leaves the response shape underspecified.

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 both parameters are already documented in the schema. The description only echoes 'by slug' and adds no format or edge-case semantics beyond what the schema provides — 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 ('which VC firms in the network back a given provider/company (by slug)') and frames it as 'the reverse portfolio edge,' which implicitly contrasts it with the forward-looking vc_portfolio sibling. An agent can tell what it retrieves 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?

It discloses that the investor COUNT is free while named firms require Understanding, and that it is priced B2 at $0.05/call — useful gating context. But it never names the alternative (vc_portfolio) or states an explicit when-to-use/when-not condition, 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one behavioral detail beyond the schema ('include=["content"] inlines bodies'), but says nothing about pagination behavior, result ordering effects, or what the default URL-only response looks like, so added value is modest.

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 definition is short, front-loaded, and waste-free, with the resource stated first and the routing note last. It is telegraphic and fragmentary ('Linked-data vocabularies.'), which is efficient but slightly cryptic rather than maximally self-explanatory.

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 100% schema coverage for nine parameters, an annotation-covered read-only profile, and no output schema, the description is close to complete for a filtered search tool. The main minor gap is the return-shape description, which is only partially addressed by the include 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 schema fully documents all nine parameters with examples and defaults. The description only restates a few parameters (q, tags, providers, include) that are already covered, adding no syntax or meaning beyond what the schema provides. 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 identifies the resource specifically as 'JSON-LD contexts' and 'linked-data vocabularies' across the catalog, which an agent can distinguish from generic artifact search. It names the sibling find_artifacts as the cross-type alternative, aiding differentiation. The purpose is clear though stated as a noun phrase rather than an explicit verb, keeping it just shy of a 5.

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

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

It gives one routing rule ('Use find_artifacts for cross-type search') and lists filter dimensions (q/tags/providers), which is implied usage guidance. However there is no explicit when-to-use statement, no prerequisites, and no other exclusions, leaving an agent to infer when this tool is the right choice.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the burden is lighter. The description adds one real behavioral fact — include=["content"] inlines bodies rather than returning only URLs — which affects payload size. It discloses nothing about auth, rate limits, or return/pagination format, so it adds only modest value beyond structured fields.

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

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

Very short and front-loaded, opening with the resource and then the filters and sibling alternative. Slightly fragmentary phrasing and the near-redundant 'Standalone data schemas' keep it from a 5, but there is no wasted 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 filtered-list tool with no output schema, the description covers the resource, available filters, the content-inlining option, and sibling routing — enough for an agent to call it correctly. It omits auth/rate-limit context and does not characterize result payloads, which are minor given the annotations already present.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters, including the meaning of tags/providers and the content inlining behavior. The description largely restates this (q/tags/providers, include=["content"]), adding little beyond the schema; baseline 3 is correct.

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

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

Names a specific resource ('JSON Schemas across the catalog') and scopes it ('Standalone data schemas'), and it explicitly distinguishes itself from find_artifacts as the cross-type sibling. The fragmentary style ('Standalone data schemas.') leaves the exact nature of a 'JSON Schema artifact' slightly implicit, but the purpose is clear enough to route correctly.

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

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

Gives explicit routing: 'Use find_artifacts for cross-type search,' which names the alternative and the condition that selects it. It also lists the supported filters (q / tags / providers), implying when it fits. No when-not guidance beyond the sibling, so a 4 rather than 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=true and openWorldHint=false, so the safety profile is covered. The description adds one genuinely behavioral fact — that include=["content"] inlines artifact bodies instead of URLs — but says nothing about pagination limits, result ordering behavior, or cost/latency with inlined content, so the added value is modest.

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?

Very short and front-loaded: the resource is named first, then filtering, then the routing hint. The telegraphic sentence fragments ('Data structures behind an API.') are slightly terse but nothing is wasted.

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

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

For a ten-parameter search tool with no output schema, the description should say more about what a returned structure contains and how paging/sorting behave. Annotations cover safety and the schema covers params, but the result shape and the meaning of struct_type/match are left entirely to inference.

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 ten parameters with enums and defaults. The description's 'Filter by q / tags / providers' and the include note merely restate what the schema says, adding no syntax or semantics beyond it; 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 the resource clearly ('JSON Structures across the catalog', 'Data structures behind an API') so an agent knows it lists JSON structure artifacts. It does differentiate from find_artifacts (cross-type search), but never distinguishes itself from very close siblings like find_json_schemas, find_json_ld or find_apis_json, which an agent could easily confuse it with.

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 offers one explicit routing hint ('Use find_artifacts for cross-type search') and repeats what filters exist, which implies when to use it. But it gives no when-not guidance against the near-identical structural siblings (json_schemas, json_ld) and no prerequisites, so usage is only partially covered.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one genuine behavioral detail beyond that — include=["content"] inlines bodies rather than returning just URLs, which changes response size and shape — but says nothing about pagination behavior, result limits, or empty-result semantics beyond what the schema states.

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 sentences with no filler: resource first, then filtering and the include option, then the sibling redirect. The leading sentence is an elliptical fragment ("MCP servers across the catalog") that relies on the name for its verb, but nothing is 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?

For a ten-parameter, zero-required, read-only search tool with no output schema, the description covers what is searched, how to filter, what include does to the response, and where to go for cross-type search — enough to call it correctly. The remaining details (paging, sorting) live in the fully populated schema.

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

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

Schema description coverage is 100%, so all ten parameters are already documented in detail (including defaults, ranges, and the unusual context parameter). The description only summarizes a subset (q / tags / providers / include) and adds no syntax or format detail 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?

The description names a specific resource, "MCP servers across the catalog," and clarifies what those are ("Model Context Protocol servers a provider offers to agents"). It separates itself from find_artifacts by naming it as the cross-type alternative, though it does not distinguish itself from the many other find_* siblings (find_apis, find_providers).

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 is present: "Use find_artifacts for cross-type search," which tells the agent when a different tool wins. It also lists the filter axes (q / tags / providers) and the include option, giving clear usage context, but offers no explicit exclusions such as when to prefer find_providers 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavior about include=["content"] inlining bodies versus returning URLs, and that get_openapi returns only the primary spec. It says nothing about pagination behavior (page/limit exist), result ordering semantics beyond the schema enum, or what happens on empty results.

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?

Five short telegraphic sentences with the core resource statement and sibling routing front-loaded. 'The REST contract' is a fragment that earns some framing value, though the definition leans terse rather than complete.

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 nine-parameter, zero-required search tool with no output schema, the description covers filtering and inlining but omits pagination expectations, default result size (limit defaults to 25), and the shape of a result. It is adequate but leaves gaps an agent would otherwise have to discover.

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 nine parameters including the unusual 'context' parameter (explicitly documented as never used for ranking) are already explained in the schema. The description echoes q/tags/providers and include without adding syntax or semantics beyond what the schema provides, so the baseline 3 applies.

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

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

The definition identifies the resource (OpenAPI specifications across the catalog) and distinguishes it from two siblings: get_openapi (one API's primary spec, optional inlined body) and find_artifacts (cross-type search). It lacks an explicit verb and never contrasts with the nearby find_apis / find_apis_json / find_graphql family, so an agent still has to infer that this is the OpenAPI-specific variant.

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 filtering context (q / tags / providers) and an explicit routing rule: 'Use find_artifacts for cross-type search.' That is a real alternative-condition pairing, but there is no when-not guidance relative to find_apis or get_openapi beyond the one-line contrast.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses de-duplication semantics (one row per real operation; the same call may appear in several provider documents, all listed in `apis`), read truncation behavior (page of matching providers up to max_providers with a 100 cap, surfaced via meta.query.truncated), and the full pricing model with a pointer to an estimate endpoint. That is unusually rich behavioral context for a read tool.

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

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

Front-loaded with purpose before mechanics, and the example and truncation note earn their space. The pricing sentence is comparatively long and could be one clause shorter, but the information is relevant and non-redundant.

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 carries the return-shape burden and does so: it explains the row granularity, the `apis` list, and the truncation signal in `meta.query.truncated`. Combined with the pricing/prerequisite pointer, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so a 3 is the baseline, but the description adds genuine meaning: q is explained as segment-matched AND-semantics with a concrete example, method as verb narrowing, and deprecated as a filter for retiring operations. page/limit/max_providers and context are left to the schema, which is acceptable.

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 with scope: 'CATALOG-WIDE operation search: which providers expose a path matching your terms.' It also draws a sharp conceptual line against tag-based search ('tags are what a company says about itself, a path is what its API accepts'), letting an agent separate it from the tag/domain lookup tools without opening a schema.

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

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

Gives clear usage conditions: terms match path SEGMENTS and all must appear (with a worked example), method narrows by verb, deprecated=true surfaces retiring operations. It does not explicitly name alternatives such as get_provider_operations or find_openapis, so routing between the several operation/spec-search siblings 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.