apis-io

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

With no annotations, the description carries the full burden, but it only says 'Add' and gives no detail about idempotency, duplicate handling, list ownership, or error behavior when the list or provider does not exist. It does disclose the primary mutation and target, but little else.

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

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

The description is a single clear sentence with no wasted words. The 'UNDERSTANDING' prefix adds little, but the core message is front-loaded and easy to parse.

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

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

For a three-parameter, two-required mutation tool with no output schema and no annotations, the description provides a usable baseline but omits important operational details: what id refers to, whether duplicates are allowed, and what happens if the list doesn't exist. It is not fully complete but not severely inadequate.

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 only 33%, so the description must compensate. It usefully explains that members are provider/API slugs or aids, but it never explicitly maps the required id parameter to the list identifier, leaving that to inference.

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

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

The description states a specific action—adding providers/APIs to a list—and identifies the member input format (slug or aid). It is clear enough to distinguish from create_list and delete_list, though it does not explicitly say the destination must be an existing 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?

The verb 'add' and phrase 'one of your lists' imply an existing-list mutation, which gives reasonable context. However, it never names create_list as the alternative for creating a list or states when this tool should not be used.

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

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

With no annotations, the description carries the burden of explaining behavior. It discloses the metric semantics, numerator, denominator, and that it covers 'scored providers,' which is useful. However, it does not describe the response shape, pagination behavior, or any potential caveats such as whether unsatisfied dimensions are included.

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 mostly front-loaded with the core metric. The 'UNDERSTANDING — diffusion:' prefix adds a categorization label that is not essential, but the description remains efficient and free of redundancy.

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

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

It explains the core output concept well enough for a metric-focused read tool, and the lack of an output schema is partially mitigated by describing numerator/denominator/share. Still, it omits what dimensions are included, whether results are paginated, and how to interpret missing or zero counts.

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 only 33%, and the description does not compensate. It adds no meaning for the page or limit parameters, and while context has a rich schema description, the tool description never explains how parameters relate to the diffusion metric or filtering.

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 deliverable: for each agent-readiness dimension, the count and share of scored providers that satisfy it. It clearly names the resource ('agent-readiness dimension') and the metric, though it does not explicitly differentiate itself from siblings like get_agent_readiness or find_agent_readiness.

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 denominator every "the agent web is/is not here yet" claim needs' gives a clear context for when this tool is useful. It does not explicitly list exclusions or alternative tools, but the intended use case is evident.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the call is federated, returns per-section counts, applies per-section limits, and supports multiple filter categories. However, it does not disclose output shape beyond counts, sort defaults, or how filters combine, which matters for a tool with no output schema.

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

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

Three dense sentences earn their place: the entry-point signal is front-loaded, the core federated behavior is stated compactly, and the sibling routing is explicit. 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?

The tool has 13 parameters, no output schema, and no annotations, so the description must carry more weight. It explains the broad purpose and routing, but it leaves the agent without crucial parameter semantics and without a clear picture of the response structure beyond per-section counts.

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 only 46%, so the description needs to compensate for undocumented parameters like area, region, industry, providers, artifact_types, min_score, and match. It only lists filter categories generically, which adds little beyond parameter names, and the 'limit is per section' point is already captured in the schema.

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

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

The description states a specific verb and resource: a federated overview of the APIs.io catalog returning top APIs, providers, and tags in one call. It also distinguishes itself from siblings by naming find_apis/find_providers/find_tags and get_api/get_provider as the tools for full list pagination or single-entity 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?

Usage guidance is explicit: 'START HERE' signals this is the entry point, and the final sentence gives concrete routing conditions for when to use sibling tools instead. This is strong when-vs-alternative guidance with no ambiguity.

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

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

With no annotations, the description carries the full burden and does a reasonably good job: it says 'read it back,' lists possible status values, mentions reviewer notes, and covers the plan requirement and error-reporting path. It does not explicitly rule out side effects or mention rate limits, but for a status check this is fairly transparent.

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

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

The description is only three sentences and packs in useful information, but the cryptic 'INFLUENCE —' opener and the awkward 'now required' phrasing detract from clarity. It is structured competently but not front-loaded around a clean verb phrase.

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?

Since there is no output schema, listing the six possible statuses and notes meaningfully fills the gap. The description also covers the plan prerequisite and how to report errors; missing details like id provenance or invalid-id behavior are secondary for a simple status read.

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

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

The schema describes 'context' well, but 'id' has no schema description. The tool description only adds 'the id identifies the request,' which is minimal and doesn't explain id format or where to obtain it, so it only partially compensates for the 50% schema 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?

The description clearly identifies the resource ('a check request by id') and the returned data: the status values and any reviewer notes. It also signals the read nature with 'read it back,' though the leading 'INFLUENCE —' is confusing and no explicit verb like 'retrieves' is used.

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 provides some usage context: the Influence plan is required, and errors should be routed to report_correction. However, it never explicitly says when to use this tool over siblings like request_check or my_checks, leaving the usage conditions mostly 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?

With no annotations, the description carries the full burden and does so thoroughly: it discloses that the call is asynchronous (202), returns a token and host list, requires an external action (DNS TXT or file publication), demands persistence ('leave it up'), and involves human verification via email. This is rich behavioral context well beyond a simple claim.

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

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

The description is dense yet efficient: it covers the action, the response, the required follow-up steps, and the tracking path in four sentences. It is front-loaded with the core action and every sentence adds necessary information.

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

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

Given no output schema and no annotations, the description gives the agent everything needed to understand the workflow: what response to expect, how to complete verification, the human-in-the-loop delay, and how to monitor progress. No critical behavioral or procedural information 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 50%: only context has a description, while slug only has a name. The description implies slug identifies the listing being claimed, but it does not explicitly describe either parameter or their format. It provides some contextual meaning but does not fully compensate for the missing slug description.

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

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

The description opens with a specific verb and resource: 'claim a listing as yours'. It clearly distinguishes this from siblings like watch_listing or check_status by describing the ownership-claim action and its asynchronous verification flow.

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

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

It explains exactly what to do after calling the tool—publish the DNS TXT record or well-known file—and explicitly routes follow-up to check_status. It also states 'there is nothing else to call', which effectively guides the agent away from unnecessary additional calls, though it does not explicitly contrast with sibling tools.

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

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

With no annotations provided, the description carries the behavioral burden. It clearly discloses pagination behavior: byte-budgeted chunks, `complete: false`, `cursor` set to `next_cursor`, and the terminal page with `complete: true`. It does not cover auth, rate limits, or exact response formatting, but the pagination disclosure 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 description is compact and front-loaded with the core purpose, then adds the pagination contract. Every sentence contributes: what the tool returns, why it matters, and how to page through large results. No filler.

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

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

For a paginated tool with no output schema, the description covers the main return concept (artifact counts and readiness dimensions) and the complete pagination protocol. It could be more explicit about response field names, but an agent has enough to call it correctly and interpret the iterative flow.

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 50%; `cursor` and `context` already have descriptive schema text, while `kind` and `slug` do not. The description reinforces the cursor/resume flow but does not clarify what `slug` refers to or how `kind` values map to cohort types beyond the schema enum. It is adequate but does not fully compensate for the undocumented required parameters.

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

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

The description names a specific resource (cohort members) and a precise output: artifact counts by type plus the agent-readiness dimensions each satisfies. This distinguishes it from sibling tools like cohort_scores, cohort_rankings, and cohort_stats, even without naming them explicitly.

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

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

It gives a clear use case — 'the capability matrix behind a market report' — which tells an agent when this tool is relevant. It does not explicitly rule out alternatives or name a preferred sibling tool, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that results are ranked by potential impact on the cohort mean, that only named checks are returned, and that facet rollups are unsupported. It does not mention output structure, pagination, or error behavior, but the core behavioral traits are clearly disclosed.

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 information-dense and front-loads the central idea, but it includes stylistic flourishes such as 'UNDERSTANDING' and 'which is the shape of a finding worth publishing' that do not add operational value. It is longer than necessary without addressing key invocation details.

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

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

The tool has no output schema, no annotations, and only one documented parameter, so the description needed to explain both the return shape and how to invoke it. It explains the conceptual output well but leaves required parameters undocumented and gives no indication of what a response item looks like, making it incomplete for an agent to call correctly.

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

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

Schema description coverage is low at 20%, so the description needed to compensate, but it never explains the required parameters kind and slug, nor page, limit, or the meaning of the enum values. The context parameter is already described in the schema, so the description adds little to parameter understanding.

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

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

The description clearly identifies the tool's purpose: it reports the agent-readiness checks that cohort members most commonly fail, ranked by how much fixing each would move the cohort mean. It also explicitly distinguishes itself from gap_analysis, so an agent can tell the two apart without inspecting schemas.

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

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

The description explicitly positions the tool as the inverse of gap_analysis and explains the semantic difference: gap_analysis shows where a market is under-served, while cohort_failures shows where it fails the rubric. It also warns that it returns named checks only, not facet rollups, which helps an agent decide when this tool is appropriate.

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

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

With no annotations, the description carries the transparency burden. It discloses the core behavior: returns a mean over members present on each date, includes members_scored, and warns that membership changes over time can confound interpretation. This goes well beyond a generic 'returns history' statement, even if operational details like default time range and result shape are omitted.

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

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

The description is well-structured and front-loaded, but the origin-story sentence about per-provider and whole-dataset series adds length. It is informative, yet a tighter version would keep the same value with less narrative.

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

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

The description explains the return semantics well, including the mean calculation and members_scored field, but it lacks explicit parameter guidance, time-range controls, or response format. For a tool with no output schema and no annotations, this leaves an agent needing to infer too much.

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 only 33%, so the description must compensate for undocumented kind and slug parameters. It does not explicitly explain what kind or slug mean, how they relate, or what slug values look like. The 'banking' example only indirectly hints that slug identifies a market, which is insufficient for reliable parameter construction.

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

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

The description clearly identifies this as a set-level time series showing how a market's Kin Score and agent readiness moved, and states that it returns the mean over members present plus members_scored. It distinguishes the tool from per-provider and whole-dataset series, though it does not name specific sibling tools.

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

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

The description gives a concrete use case ('how has banking moved over six months') and positions the tool as filling the gap between per-provider and whole-dataset views. This provides clear context for when to use it, though it stops short of explicitly naming alternatives or when-not-to-use conditions.

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

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

With no annotations, the description carries the behavioral burden. It adds meaningful context: the two orders differ and the gap is significant. However, it does not disclose ranking direction, pagination, response shape, or whether this is a read-only operation, leaving important operational behavior unspecified.

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

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

The description is compact and front-loaded with the core concept. The second sentence adds interpretive value, but the leading word 'UNDERSTANDING' is somewhat ambiguous and does not contribute functional clarity.

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

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

The description captures the conceptual essence but is incomplete for practical invocation. It lacks parameter semantics, output details, and explicit instructions for interpreting or paginating results, and with no output schema, agents are left without enough information to reliably use the tool.

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

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

Schema description coverage is only 20%, so the description must compensate, but it does not explain slug, page, limit, or how kind maps to a market. It introduces the concept of a 'market' without explicitly tying it to the kind and slug parameters.

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

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

The description clearly identifies the tool as a leaderboard for a market and specifies the two ranking axes (Kin Score composite and agent readiness). It distinguishes itself from related sibling tools by emphasizing the dual rankings and the gap between them, though it lacks an explicit verb like 'returns' or 'gets'.

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 guidance is provided on when to use this tool versus alternatives such as cohort_scores, cohort_stats, or agent_readiness_dimensions. The description implies it is for understanding market leaderboards, but it does not state conditions, exclusions, or 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?

With no annotations, the description is the only behavioral disclosure. It says what the response contains (scores, average, delta), but it does not disclose operational traits such as default ordering, pagination, or whether it is non-mutating. No contradiction with annotations exists because none are present.

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 first sentence front-loads the core purpose and is appropriately short. However, the 'UNDERSTANDING —' prefix and the governance/market metaphor add style and emphasis rather than new operational detail, so the description is not as information-dense as it could be.

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

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

There is no output schema and no annotations, so the description must carry the full context; it leaves parameter semantics, pagination behavior, and the relationship to related cohort endpoints unresolved. An agent could guess the required inputs from the schema, but the description alone is not sufficient to use the tool confidently among its siblings.

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

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

Schema coverage is only 20% (only `context` has a description), and the tool description does not explain `kind`, `slug`, `page`, or `limit`. The reference to a cohort is abstract and is not linked to the required parameters, so the description does not compensate for the low schema 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?

The description clearly identifies the deliverable: facet-level scores for each cohort member, with the cohort average and delta. It conveys the resource ('cohort') and the comparative nature, but it does not explicitly contrast it with near-sibling tools like cohort_rankings 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?

The '60 in governance... market sits at 45' example implies when the tool is valuable (benchmarking an individual score against the group), giving some usage context. It stops short of explicit when-to-use/when-not-to-use guidance, and no alternative tools are named.

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

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

With no annotations, the description carries the full behavioral burden, and it does well: it states that results are computed live, that a coverage block is always returned, and that enrichment depth can skew cohort numbers by up to ~42 points of catalog_gap. It does not explicitly state read-only status, permissions, or edge-case behavior, but the read-oriented content strongly implies a safe query.

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 longer than typical, but nearly every sentence earns its place: the metric list defines scope, the 'market-stats sheet from a Trend Report' analogy is useful, and the coverage caveat is critical. The final sentence is somewhat dense with the ~42-point catalog_gap detail, but it is not 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?

In the absence of an output schema and annotations, the description does a good job explaining what results look like and why they need careful interpretation. However, it leaves the required kind/slug parameters essentially unexplained and gives no detail on how the coverage block is structured or how errors behave, so an agent can interpret output well but may struggle to construct a correct call.

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

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

Schema description coverage is only 33%, and the description adds no explanation of how kind and slug select the cohort or how they interact. The enum on kind is the only guidance for that parameter, while slug is entirely undocumented beyond its name. Given the low schema coverage, the description should have compensated but does not.

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

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

The description clearly identifies the tool as producing market-wide distribution statistics, listing the exact metrics returned (Kin Score mean/median/min/max/stdev, band split, per-facet averages, adoption rates). It distinguishes itself from sibling tools like cohort_scores or cohort_rankings by focusing on aggregate market statistics, but it does not explicitly name alternatives or use a strong imperative verb.

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 opening frames the intended use case: understanding the distribution for a whole market rather than individual cohort details. It also gives a crucial operational rule to read the coverage block before quoting means, which is excellent usage guidance. However, it never contrasts this tool with sibling cohort tools or states when not to use it.

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

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

With no annotations, the description must carry the full burden. 'UNDERSTANDING' weakly implies a read-only analysis, but there is no disclosure of return behavior, data scope, access requirements, or any side effects. The 'Pro.' tag is the only additional behavioral 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?

The description is short and front-loaded with the core concept, which aids scannability. However, 'UNDERSTANDING —' and the trailing 'Pro.' are low-signal filler that do not earn their place; the structure is acceptable but not exemplary.

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

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

For a simple one-required-parameter tool, the description is functional but incomplete. There is no output schema, no hint at return values, no guidance on slug format, and no differentiation from similar gap-oriented tools. An agent could call it, but not with confidence about what it will receive or why it is the right tool.

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

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

The tool description does not mention or explain its parameters. The schema documents 'context' thoroughly, but 'slug' has no description, and the 50% schema coverage is not compensated by the description. The agent receives no help on what slug values are valid.

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 does identify a specific resource: 'a company's weakest investment dimensions' and adds business nuance ('where it is thin and a vendor could sell in'). However, it lacks an explicit verb such as 'get' or 'list,' making the action implicit 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?

No guidance is given about when to use this tool versus alternatives like gap_analysis, industry_gap_analysis, or get_company_insight. The only extra marker is 'Pro,' which hints at access level but not usage context.

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

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

There are no annotations, so the description carries the full behavioral burden. It does well by disclosing what is returned (distributions, deltas on score, agent readiness, facets, adoption rates) and by warning about the depth-confounding effect and `depth_note`. It does not mention output structure, errors, or side effects, but the confounding caveat is valuable and genuinely behavioral.

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

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

The description is a few dense sentences with no filler, and the critical warning about `depth_confounded` is placed prominently. The sentence about written reports adds context but is slightly tangential; still, it helps explain why the tool exists and earns its place.

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

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

The description is reasonably complete for a read-only comparison tool: it states what is returned, gives a motivating example, and surfaces an important interpretation caveat. With no output schema, it could have described the exact response shape more, but the listed outputs (distributions, deltas, depth_note) give an agent enough to understand what to expect.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond the schema, but the schema already provides clear examples for `a` and `b` and a detailed rationale for `context`. No additional compensation is needed or provided.

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 clear, specific purpose: comparing two markets/cohorts side by side on a single rubric and returning distributions plus deltas. It gives a concrete example ("is US payments further along than UK banking?") and distinguishes this cohort-level comparison from a single-market report or provider-level comparisons.

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

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

The description clearly conveys when to use the tool: when an agent needs a direct side-by-side comparison of two markets on the same rubric. It even frames this against reports, which only cover one market. It does not explicitly name alternative tools or provide when-not-to-use exclusions, so it falls just short of a 5.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose the nature of the operation (side-by-side comparison) and the shape of the result (composite/band, per-facet leaders, artifact-coverage matrix), which is useful. However, it does not mention side effects, read-only status, error behavior, or what happens with invalid or nonexistent provider slugs.

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

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

The description is a single sentence and front-loads the core message efficiently. The 'UNDERSTANDING —' prefix is somewhat superfluous and does not add semantic value, but the rest is tightly written with no filler.

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

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

With no output schema, the description does a reasonable job of telling the agent what the tool returns by naming three result components. Still, it leaves gaps around interpretation of 'per-facet leaders', limits on provider count, and whether the matrix is ordered or filtered. For a two-parameter tool this is adequate but not comprehensive.

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

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

Schema description coverage is 100%, and both parameters are already explained well in the schema: 'providers' is described as provider slugs to compare, and 'context' has a thorough rationale. The description adds some context by naming the output dimensions, but it does not significantly deepen understanding of either parameter beyond the schema.

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

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

The description uses a specific verb ('Compare'), names the resource ('providers'), and enumerates the concrete output components ('composite/band, per-facet leaders, and an artifact-coverage matrix'). This clearly differentiates it from single-provider lookups like get_provider and search-focused tools like find_providers, and from the sibling compare_cohorts which targets cohorts rather than 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?

There is no explicit guidance on when to use this tool versus alternatives such as compare_cohorts, find_providers, or get_provider. The 'Compare 2+ providers' phrasing implies a multi-provider comparison use case, but nothing is stated about when not to use it or which sibling should be preferred in related scenarios.

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

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

With no annotations provided, the description carries the transparency burden. It discloses the 202 response, the human-review process, and that score/band are ignored, and it explains why unreviewed owner edits are disallowed. It does not cover authentication, rejection behavior, or what happens after review, but the core behavior is visible.

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 and the rationale about unreviewed edits is relevant to understanding the 202/human-review behavior. The wording is a little dense and contains an awkward aside, but every sentence contributes useful context.

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 tool with no annotations and no output schema, this description does a decent job covering the request flow and constraints, but it leaves parameter coverage incomplete, does not clarify ownership verification, and does not describe outcomes after human review. It is adequate 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 only 13%, so the description must compensate. It does add meaning by enumerating editable fields and stating that score/band are ignored, but it omits the semantics of 'slug' and 'contact', and leaves ambiguity about whether 'contact' is correctable. Compensation is partial, not complete.

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

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

The description names a specific action ('propose corrections') and a target ('what we say about you'), and lists the editable fields: name, description, url, industries, tags. It is clearly an owner-facing correction flow, but it does not explicitly distinguish itself from sibling tools like report_correction.

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

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

The description gives clear context: this is for proposing corrections that will be applied by a person, and it explicitly states that score and band are not owner-settable and will be ignored. It does not name alternatives or say when not to use it, but the context is reasonably 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose that the list is persistent and that an API key is required, but it does not state what happens on duplicate names, whether it is idempotent, or what the response contains. For a creating/mutating tool this is a notable gap.

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 content is a single clear sentence, but the leading 'UNDERSTANDING — ' prefix adds no functional value and slightly obscures the actionable verb. The essential information is front-loaded, but every word should earn its place and this one does 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?

For a creation tool with no output schema and no annotations, the description omits important operational context: return behavior, idempotency, error handling, and relationship to sibling tools like add_to_list or get_list. It is minimally sufficient for invoking the tool, but not enough for an agent to reason about consequences or workflows.

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 67%, with 'name' lacking a schema description. The tool description adds marginal context ('named' for name, 'providers or APIs' for members) but does not clarify name format, validation, or how members map to slugs/aids beyond the schema. Overall it adds a little value over the schema without fully compensating.

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 ('Create') and resource ('named, persistent list ... of providers or APIs'), and clarifies the list is a shortlist/stack the user owns. This distinguishes it from siblings like get_list, delete_list, and list_lists, though it does not explicitly name the closest sibling, add_to_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?

The description gives a prerequisite (requires an apis.io API key) but provides no guidance on when to use this tool versus alternatives such as add_to_list, get_list, or delete_list. An agent must infer that create_list is for making a new list, while add_to_list handles additions to an existing one.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It implies a destructive operation and an ownership requirement, but does not state whether deletion is permanent, what side effects occur, what happens when the list is not found or not owned, or whether confirmation is involved.

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

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

The description is a single, front-loaded sentence with no filler. The leading 'UNDERSTANDING —' label adds a bit of noise but the core message is immediate and unambiguous.

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 tool this is thin: no output schema, no annotation coverage, and no mention of return values, error behavior, or ownership verification. An agent is left to guess what happens after a successful delete or on failure.

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

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

The required 'id' parameter is undocumented in the schema and the description gives no clue about its format or how to obtain it. The optional 'context' parameter is well-described in the schema itself, but the description adds no parameter-level information to compensate for the id gap.

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

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

The description states a specific verb and resource: 'Delete a list you own.' It clearly differentiates from sibling tools like delete_saved_search by naming 'list' as the target, and adds an ownership condition that scopes the operation.

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

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

The intended use is implied: call this when you want to delete a list you own. However, there is no explicit guidance about when not to use it, prerequisites (e.g., must own the list), or how it relates to alternatives such as delete_saved_search or create_list.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It reveals that the operation is destructive and requires ownership, but it omits critical details like permanence, failure behavior for nonexistent or unauthorized searches, and any cascading side effects.

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

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

The description is a single, direct sentence with no filler. The 'UNDERSTANDING —' prefix is extraneous and adds no semantic value, which prevents a perfect score for 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?

This is a destructive tool with no annotations and no output schema, yet the description provides no information about success/failure behavior, reversibility, or error reporting. The agent has insufficient context to invoke it safely and predict outcomes.

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 50%, with only the context parameter described. The tool description adds meaning by clarifying that 'id' refers to the saved search being deleted, but it does not elaborate on id format, error handling, or the exact role of the id beyond the obvious.

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 ('Delete') on a concrete resource ('a saved search') with an ownership constraint ('you own'). This clearly differentiates it from sibling tools like delete_list and other saved-search helpers, making the tool's intent unmistakable.

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

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

The description implies when to use the tool: when deleting a saved search the user owns. However, it does not explicitly mention alternatives (e.g., delete_list) or exclusion scenarios, leaving the usage guidance mostly implicit rather than explicit.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It conveys that this is a read-only, catalog-wide, ranked list, but it does not describe response fields, pagination behavior, or any ordering direction beyond 'ranked by how many.' The core behavior is clear but under-specified.

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 includes several useful elements but also extraneous motivation ('which nothing could see before') and a hard-coded statistic (8,297 operations / 681 providers) that will age and does not help invocation. The core definition is front-loaded, but the extra context could be trimmed.

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

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

The description gives a solid conceptual model and a drill-in pointer, but with no output schema and no annotations, the agent must infer the return format and how page/limit affect results. It is adequate for a simple categorized list but not fully complete for a low-coverage 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 only 33% (only 'context' has a schema description). The tool description itself says nothing about page, limit, or context, so it adds no meaning beyond the schema. Page and limit must be inferred from their names, and context is only explained in the schema, not reinforced.

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: it lists every provider with at least one deprecated operation in its own OpenAPI, ranked by count. It also explicitly names the drill-down sibling get_provider_operations(deprecated=true), which distinguishes this catalog-wide view from per-provider tools.

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

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

The description gives clear when-to-use context: to see deprecated operations across the catalog without already suspecting a provider, because a provider's own deprecated filter requires prior suspicion. It also points to the exact alternative for drilling in, get_provider_operations(deprecated=true).

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

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

With no annotations at all, the description carries the full disclosure burden and largely succeeds: it discloses the async 202 response, a human fetching and checking evidence, email follow-up either way, and (via the context param text) that context is never used to rank. Unstated failure handling and response timeframes prevent a 5.

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

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

Three sentences with high information density — workflow, status code, and access policy each earn their place. The unexplained 'INFLUENCE —' prefix occupies the front-loaded position without adding functional value, costing the fifth point.

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

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

The workflow and access model are well covered, but an agent cannot reliably invoke the tool: the required slug is undefined, what a 'finding' refers to in this domain is never clarified, and with no output schema the agent has no sense of the successful result beyond a bare 202. Critical invocation details are 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 only 20% (just the context parameter), so the description was obligated to compensate. It explains claim and evidence_url ('Send the claim in words and a URL that evidences it'), but the required slug parameter is entirely undefined and contact is only inferable from the 'emails you either way' statement. That is a significant gap for a required parameter.

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

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

The description states the action — submit a dispute of a system finding by sending a claim and an evidence URL — and differentiates it from simple reporting by disclosing the human-mediated evidence-check process. The 'INFLUENCE' prefix and quoted phrase are informal, and the domain object 'finding' is never explicitly defined, which keeps this 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?

Provides one genuinely useful access guideline: open to any paying caller, no ownership proof needed before disputing data. However, it never names alternatives among many plausible siblings (report_correction, correct_facts) nor states explicit selection conditions; usage context is implied rather than contrasted.

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

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

No annotations are provided, so the description carries the full burden. It discloses that it resolves identifiers and returns selected groups, which suggests a read operation, but it does not explicitly state side-effect safety, error behavior, or the implications of the 'Understanding plan' note about the discovery layer. The context parameter's non-ranking behavior is documented in the schema, not the main description.

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 value proposition is front-loaded and expressed compactly: 'One call, pick your field groups.' The final 'Understanding plan' sentence is cryptic and does not clearly earn its place, preventing 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?

With no output schema and no annotations, the description explains the selection model but not the shape or content of the returned groups, nor error behavior. An agent would need to infer those from sibling tools, so the description is adequate but incomplete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a group list ('profile, onboarding, artifacts, rating, insights') but omits 'security', which the schema includes. This is a slight inconsistency rather than added meaning, and the default group set is already described in the schema.

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

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

The description states a precise function: 'resolves a slug OR any identifier and returns exactly the groups you ask for.' It lists the available groups and explicitly contrasts with chaining get_provider + get_provider_rating + get_provider_artifacts + get_provider_onboarding, clearly differentiating it from sibling tools.

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

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

It directly positions the tool as a one-call alternative to chaining multiple get_provider* tools, which serves as a clear usage guideline. However, it does not state when not to use it (e.g., if only a single group is needed), so it lacks explicit 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?

With no annotations, the description carries the behavioral burden. It discloses licensing requirements, pagination via cursor/next_cursor, chunked delivery, the meaning of 'complete', and the attribution obligation. It does not mention failure modes or rate limits, but the core behavioral expectations for calling the tool are clearly laid out.

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

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

The description is long but densely packed with decision-relevant information: licensing, dataset semantics, pagination mechanics, and attribution. It is front-loaded with the most important scoping statement. Some sentences are complex, but no sentence feels redundant or promotional in a way that wastes agent attention.

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

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

For a tool with four parameters and no output schema, the description covers the key operational details: available datasets, chunked pagination, cursor usage, completion signal, and attribution. It does not describe the exact response object shape beyond data/complete/next_cursor, but for a streaming export that is acceptable. Overall it gives an agent enough to invoke the tool correctly.

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

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

Schema coverage is 75%, so the schema already explains cursor, context, and co_brand. The description adds substantial meaning beyond the enum by detailing what each dataset value returns, e.g., ratings includes facets, trend, rubric and provenance, and history includes parallel date/composite/agent_readiness arrays. This materially improves agent understanding of the dataset parameter.

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

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

The description states a specific action and resource: exporting a full dataset ('ratings', 'providers', or 'history') as opposed to a partial page. It distinguishes itself by emphasizing 'the WHOLE dataset, not a 100-row page' and describes each dataset variant concretely, making the tool's purpose unmistakable even among many find/get/export siblings.

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

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

The description gives clear context: it is for media outlets and analysts licensing data to publish rankings and trends. It also explains when the 'history' variant is uniquely valuable. It does not explicitly state when to avoid this tool in favor of alternatives like export_stack or find_ratings, so it stops 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?

With no annotations, the description carries the full burden of behavior disclosure. It does convey the key result — producing an APIs.json document with an Arazzo hint for the team to commit — which makes the read/export nature reasonably inferable. However, it does not mention permissions, failure modes, or whether any state is modified, so it is adequate but not rich.

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

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

The description is a single focused sentence that front-loads the action and output. The 'UNDERSTANDING —' prefix is a minor nonessential addition, but the overall structure 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 simple export tool with one required parameter and full schema coverage, the description is largely complete: it states the output artifact, which compensates for the lack of an output schema. It could be stronger by noting when to choose this over export_dataset, but that gap is more about usage guidance than contextual completeness.

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

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

Schema description coverage is 100%, so the schema already documents capabilities, region, and context. The description itself adds no parameter-level detail, which fits the baseline of 3 for full schema 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?

The description uses a specific verb ('Export') and resource ('a designed capability stack') and clearly states the output form ('adoptable APIs.json document'). It is not a tautology and is distinct in action, though it does not explicitly differentiate itself from sibling tools 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?

There is no guidance on when to use this tool versus alternatives such as export_dataset, recommend_stack, or the find_* family. It implies a prerequisite (a designed stack) but does not state exclusions, alternatives, or concrete use conditions.

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

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

With no annotations provided, the description carries the behavioral burden, and it does so well: it discloses ranking behavior, the whole-catalog scope, output components (agent score + band alongside Kin Score), and the context parameter's unusual property of never being used to rank. It does not cover rate limits or authorization, but the read-only leaderboard nature is clearly implied.

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

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

The description is dense and front-loaded with the main purpose, followed by illustrative filters and a return-value statement. The examples add length but earn their place by clarifying the two most important parameters. The leading 'UNDERSTANDING —' tag is minor framing rather than waste.

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

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

For a tool with 8 optional parameters and no output schema, the description covers the core behavior, the key filter semantics, and the return payload, which is enough to call it correctly. Some optional parameters are left to the schema, and dimension values are not enumerated here, but the overall picture is complete for typical use.

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

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

Schema coverage is 75%, so the baseline is 3. The description adds meaningful examples and semantics for has and missing, notes that sort ranks highest first, and clarifies the return value, but it leaves band, min_score, page, and limit to the schema. This is adequate but not exceptional compensation for the remaining gaps.

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

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

The description clearly identifies a specific verb and resource: it builds an agent-readiness leaderboard across the whole catalog, ranks providers, and filters by dimensions. The has/missing examples, such as the OAuth-capable MCP cohort and addressable market for a fix, make the purpose concrete and distinguish it from sibling provider-search tools.

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

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

The description provides clear context for when the tool is useful—understanding readiness cohorts and gaps—with concrete usage examples. It does not explicitly name alternative tools or state when not to use this tool versus siblings like find_providers or get_agent_readiness, so it stops short of full exclusionary guidance.

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

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

With no annotations, the description carries the full behavioral burden for safety and side effects, and it does disclose core list behavior: pagination, sorting, and filtering by multiple dimensions. It does not state read-only guarantees, result shape, default ordering, or pagination behavior, so the disclosure is adequate but shallow.

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

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

Two concise sentences with the core purpose and capabilities front-loaded, followed by a valuable routing instruction. 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?

For a 20-parameter tool with no annotations and no output schema, the description is under-specified: it omits result-shape guidance, default behavior, and disambiguation from find_apis_json. The schema fills in some details, but the overall definition leaves an agent with significant uncertainty when selecting and invoking this tool.

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

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

The description adds semantic grouping by naming the main filter categories (tag, provider, artifact type, industry, region, rating band), which maps usefully onto several parameters. It does not compensate for the many undocumented parameters (e.g., area, match, min_score, providers) or clarify how pagination and sorting parameters interact, leaving clear gaps at 55% schema 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?

The description clearly identifies a specific resource and operation: a paginated, sortable list of APIs across providers, with concrete filter dimensions. It also names and routes around apis_io_search. However, it does not disambiguate from the closely named sibling find_apis_json or the artifact-specific find_* tools.

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

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

'Use apis_io_search first for a cross-type overview' provides an explicit alternative and sequencing rule, which is useful guidance. It lacks explicit when-not-to-use guidance for the many other find_* tools with overlapping purposes, so the guidance is partial rather than comprehensive.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose useful traits: the include=['content'] behavior that inlines bodies and the filter-by q/tags/providers mechanism. But it leaves out what the default response shape is, how pagination behaves, and does not explicitly confirm this is a read-only lookup (only implied by the 'find' naming convention and search context).

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

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

Three short sentences with no filler; the resource is stated first and the sibling routing is last. The structure is slightly marred by the opening fragment pair, where the second sentence reads as an awkward noun appositive rather than a clean clarification, but overall it is compact and every clause earns its place.

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

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

For a tool with 8 parameters, no annotations, and no output schema, the description covers the essential purpose, core filter parameters, the inlining behavior, and the key sibling distinction. It remains incomplete: no return-value description (no output schema to fall back on), no pagination guidance, and several parameters left to a sparsely documented schema.

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

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

Schema coverage is only 38%, so the description must compensate. It does add meaning: it groups q/tags/providers as filters and explains include=['content'] inlines bodies. However, page, limit, and match receive no description-level semantics beyond their schema defaults/enums, so the compensation is only partial.

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 a specific resource — APIs.json discovery documents — and distinguishes it from the broader find_artifacts tool. However, the opening sentences are grammatically fragmented ('APIs.json indexes across the catalog. The APIs.json discovery documents themselves.') and never state an explicit verb like 'find' or 'search' for this tool; the purpose is inferable but not stated cleanly.

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 one concrete routing directive: 'Use find_artifacts for cross-type search,' which tells the agent when this tool is NOT appropriate. It does not enumerate the other artifact-specific find_* siblings (find_openapis, find_asyncapis, find_operations) or explicitly state 'use this when you want APIs.json documents specifically,' so the guidance is helpful but incomplete.

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

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

With no annotations, the description carries the behavioral disclosure burden. It usefully reveals that `include=["content"]` inlines bodies, which is a non-obvious behavior. However, it does not describe default result shape, pagination effects, or how tags/providers interact with match semantics, so the behavioral picture is only partial.

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 deliver the resource type, key filters, and the cross-type alternative with no filler. The most important distinguishing content is front-loaded, and every sentence earns its place.

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

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

For a search tool with 8 parameters and no output schema, this description gives only the essentials: the artifact type, available filters, and inline-content behavior. It is sufficient for a basic call but incomplete around match behavior, result shape, and provider/tag semantics, leaving the agent to infer important behavior from the schema or trial.

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 low at 38%, so the description's mention of "q / tags / providers" adds helpful signposting. The phrase "include=["content"] inlines bodies" gives meaning beyond the bare enum. Still, it leaves page, limit, match, and context to the schema, and it does not clarify parameter interactions.

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

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

The description clearly identifies the resource as "Arazzo workflows" and defines them as "multi-step API workflows chaining operations," so an agent can tell what kind of object this tool returns. It also distinguishes itself by directing cross-type searches to find_artifacts. The lack of an explicit verb is minor because the tool name supplies it.

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

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

The description states the core route for Arazzo searches and explicitly points to find_artifacts when cross-type search is needed. It also lists the available filters, giving the agent enough context to choose this tool over siblings. It does not exhaustively contrast against every find_* sibling, but it names the most relevant 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?

No annotations are provided, so the description must carry the full behavioral burden. It states the tool browses a curated, scored index but does not disclose details like whether results are read-only, how pagination works, what 'scored' means, or any side effects. The context parameter's behavior is described in the schema but not reinforced in the description. This is a minimal disclosure for a tool that may have hidden ranking logic.

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

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

The description is two sentences with no fluff. It front-loads the core purpose and immediately follows with usage hints. Every word earns its place, making it easy to parse quickly.

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

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

Given the tool's simplicity (5 params, no output schema), the description is minimally sufficient but misses some context. It does not explain what an 'area' is beyond the taxonomy examples, nor does it describe the return structure or pagination behavior. For a browse tool, some clarity on expected output would help, but the basics are covered.

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 only 20% (only 'context' has a description). The description does add some meaning by indicating 'Search by text' implies q is a text query, and 'sort by provider count' suggests sort values relate to provider count. However, it does not explain 'page' or 'limit' semantics, though these are common. The description partially compensates for low schema coverage but leaves gaps.

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

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

The description clearly states the resource (API Evangelist areas taxonomy) and the action (browse/search). It distinguishes itself from sibling find_* tools by naming the specific taxonomy type ('areas') and providing examples like authentication, webhooks, payments. This makes the tool's purpose unambiguous even 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 explicit guidance on when to use this tool versus alternatives. The description mentions 'Search by text; sort by provider count' which is instructional but not contextual. With over 30 sibling find_* tools, the lack of exclusions or comparison to related tools (e.g., find_providers, find_apis) leaves the agent to infer usage solely from the resource name.

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

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

No annotations are provided, so the description carries the full burden. It discloses a useful behavior ('include=["content"] inlines bodies') and hints at a filter ('PRO: scopes, security'), but it does not explicitly state that the operation is read-only, nor does it mention pagination limits or rate limits. The 'PRO' line is cryptic and may confuse an agent. The description is not contradictory, but it leaves the safety profile implicit.

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

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

The description is front-loaded with the core purpose and differentiator, then follows with the type list and a brief note about 'include'. It is not overly verbose, but the 'PRO: scopes, security' line is cryptic and adds little without explanation. Still, the structure is efficient and the information density is reasonable.

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

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

With 8 parameters, no output schema, and no annotations, an agent needs guidance on how to construct a query, handle pagination, and interpret results. The description only covers type enumeration and the 'include' option. It does not mention default behaviors (beyond schema defaults), sorting, or response format. The tool is complex enough that this level of incompleteness would likely lead to incorrect calls or confusing results.

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 only 13% (1 of 8 params). The description adds value by enumerating the valid 'type' values (mcp, skills, rules, etc.) and explaining the effect of 'include', but it does not explain 'q', 'tags', 'providers', 'limit', or 'page'. These parameters are simply left to their schema definitions, which lack descriptions. Given the low schema coverage, the description does not compensate enough for the missing parameter meanings.

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

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

The description opens with 'Find artifacts of ANY one type across the catalog — the cross-type entry point,' giving a clear verb, resource, and scope. It explicitly differentiates itself from the dedicated find_<type> siblings, naming several examples, which makes the purpose unmistakable.

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

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

The description states 'Each type also has a dedicated find_<type> tool ... prefer those when you know the type.' This gives explicit when-to-use vs. when-not-to-use guidance, identifying the alternative category and the condition for choosing it. The agent is told to use this tool as the cross-type fallback.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It discloses that include=['content'] inlines bodies and that this is a catalog-wide search tool, but it does not describe pagination, match semantics, output shape, or any read-only guarantees. Some useful behavior is conveyed, but not comprehensively.

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

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

Two dense sentences, no filler. The core scope is front-loaded, filtering options are listed compactly, and the key sibling alternative is stated last without redundancy.

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

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

The tool has 10 parameters, no output schema, and no annotations, yet the description covers only basic filters and one sibling alternative. It omits pagination behavior, match semantics, and expected return format, leaving meaningful gaps for an agent to call it correctly in edge cases.

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

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

Schema coverage is only 50%, so the description must compensate for undocumented params. It adds meaning for providers (filter) and include (inlines bodies), and restates q/tags as filters. However, it leaves page, limit, match, and other params unaddressed, creating a partial but incomplete compensation for the schema gaps.

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 type clearly — AsyncAPI/event-driven specifications across the catalog — and adds useful domain context ('event/streaming APIs'). It differentiates from find_artifacts for cross-type search, though it could more explicitly state the search/return action rather than relying on the tool name.

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 for cross-type search ('Use find_artifacts for cross-type search') and indicates how to narrow results (filter by q/tags/providers, include content). It does not exhaustively distinguish from other sibling find_* tools like find_openapis or find_apis, but the core usage guidance is present.

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

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

With no annotations provided, the description carries the disclosure burden. It transparently documents the default filtering behavior, the effect of all=true, and the intended interpretation of zero-coverage results. It does not cover pagination, auth, or response format, but the core behavioral choices are well explained.

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

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

The description is two sentences and front-loads the most important information: the tool is the entry point, and what it returns. The explanation about all=true earns its place because it prevents a common misinterpretation of zero-coverage results.

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

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

There is no output schema and no annotations, so the description must compensate by explaining return values. It states that the result includes how many catalog providers reach each capability and discusses the all=true behavior, but it does not describe the response structure, pagination behavior, sorting, or concrete usage examples. For a six-parameter tool, this leaves some gaps.

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

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

Schema coverage is 67%, so the schema already handles q, all, context, and industry. The description adds meaning for the all parameter by explaining default behavior and reframing zero-coverage data as a real answer. It does not add anything for page, limit, q, context, or industry 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 clearly identifies the resource: a business-capability model with 333 top-level capabilities across 28 industries and counts of catalog providers per capability. The 'START HERE' framing establishes it as an entry-point tool, but it does not explicitly differentiate it from related siblings like get_capability or find_industries.

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 provides clear context for when to use the tool: as the starting point for 'what can a business do with these APIs.' It also explains the default vs. all=true choice, including why zero-coverage capabilities are a meaningful result rather than a gap. It does not mention alternative tools or exclusions, so the guidance is contextual rather than comparative.

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

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

With no annotations, the description must carry behavioral transparency. It does disclose filtering capability and the notable behavior that include=['content'] inlines bodies. However, it says nothing about pagination, match semantics, the context parameter's purpose, or read-only status. Some behavior is present, but the full picture is incomplete.

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

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

The description is brief and front-loaded with the resource identity, then filter syntax, then alternative routing. The first two sentences are slightly redundant ('AsyncAPI event channels' vs 'Individual event channels'), but otherwise every sentence earns its place.

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

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

For a tool with 10 parameters, no annotations, and no output schema, this description is under-specified. It covers the core purpose and one behavioral nuance, but an agent would still lack guidance on pagination, match semantics, context usage, return shape, and how version/protocol filters interact with the catalog.

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

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

Schema description coverage is 50%, so the description must add some parameter meaning. It does identify q, tags, providers, and include as filters, and adds the key semantic that include=['content'] inlines bodies. But it omits version, protocol, context, match, page, and limit semantics, leaving much 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?

The description clearly identifies the resource as 'AsyncAPI event channels' and scopes it to 'the catalog', with 'Individual event channels (topics/streams)' adding useful precision. It distinguishes itself by pointing to find_artifacts for cross-type search, though it does not explicitly contrast with find_asyncapis.

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

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

The description provides explicit routing guidance: 'Use find_artifacts for cross-type search.' It also implies when to use this tool—when searching for event channels specifically. It does not enumerate every alternative or exclusion, but gives the key decision point.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses scope (which cohort types are browsable) and filter dimensions, but says nothing about pagination defaults, field semantics of the tier concept beyond what the schema already states, or availability guarantees. As a read-only browse tool the behavior is largely self-evident, so this is adequate but not rich.

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

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

Three tight sentences. The usage directive is front-loaded ('START HERE'), scope is one clause, and the call-order guidance is the final sentence. No filler or redundant restatement.

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-param browse tool with no output schema, the description covers entry-point positioning, filter options, and downstream routing in one place. Nothing an agent needs to choose and call it correctly is missing; only the return shape is left unspecified, which is acceptable for a listings 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?

With 71% schema coverage, the baseline is 3. The description reinforces three key filters (kind, min_providers, tier) with the tier enum values in parentheses, mapping directly to schema params, but adds no meaning beyond the schema. The semantic payload is carried mostly by the input 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... cohorts' as 'one browsable index' covering tags, industries, regions, areas and VC portfolios). It clearly distinguishes itself from siblings like find_tags, find_industries, and find_vcs by positioning itself as the aggregating entry point, and explicitly flags cohort_stats/cohort_rankings as follow-ups.

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,' giving clear entry-point positioning, and directs the agent to cohort_stats for distribution and cohort_rankings for the leaderboard. It stops short of explicitly stating when NOT to use it versus the individual find_tags/find_industries siblings, though the aggregated-index wording implies the distinction.

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

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

With no annotations, the description carries the behavioral burden. It adds useful context by noting these are 'runnable request collections' and that include=['content'] inlines bodies. However, it does not mention read-only status, response shape, pagination behavior, or any prerequisites, leaving notable gaps for a search tool with zero annotation support.

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

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

The description is compact, front-loaded, and every sentence contributes: scope, collection nature, filtering/inlining behavior, and the key sibling alternative. There is no filler or repetition.

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

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

This tool has 9 parameters, no annotations, and no output schema, so the description needs to provide substantially more context. It covers filters and include behavior, but does not explain match semantics, pagination defaults, result ordering, or what a returned collection looks like. The description is too sparse for an agent to confidently select and invoke it alongside many similar find_* tools.

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

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

Schema description coverage is only 44%, so the description must compensate for undocumented parameters. It does add meaning beyond the schema by naming providers as a filter and explaining that include=['content'] inlines bodies. But it does not cover page, limit, match, sort, or context, leaving several parameters underdocumented.

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 a specific resource, collections, and states the core action of finding them across the catalog. It differentiates from find_artifacts by noting that find_artifacts is for cross-type search. However, it leaves 'Postman / Open collections' somewhat ambiguous and does not distinguish from close siblings like find_postman or find_openapis.

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 one explicit routing instruction: use find_artifacts for cross-type search, which helps an agent choose an alternative. It also lists the main filter dimensions and the include option. It does not cover all sibling distinctions, but the guidance provided is concrete and actionable.

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

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

With no annotations, the description carries the full behavioral disclosure burden. It usefully adds that the tool browses Fortune 1000 companies, filters by name, and ranks by a technology-readiness signal. However, it does not describe what a result contains, whether pagination matters, or what side effects (if any) exist. The 'Understanding plan.' fragment is opaque and adds no behavioral clarity.

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 main sentence is compact and front-loaded, stating the core action, scope, and ordering. However, 'Understanding plan.' is an unhelpful appended fragment that wastes the second sentence and creates confusion. Overall it is concise but not clean.

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

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

Given no annotations, no output schema, low parameter coverage, and a large sibling family, the description is too thin for an agent to reliably choose and invoke this tool. It omits what an 'insight' result looks like, how to use pagination, and how this compares to get_company_insight. A few more sentences about return shape and selection criteria would be needed.

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 only 25%, so the description must compensate. It does help infer that q is a company name ('by name') and hints at sorting, but page, limit, and search format are not explained. The context parameter is already described in the schema, so the description adds little new parameter meaning.

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

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

The description names a specific action ('browse'), a clear resource ('profiled companies (Fortune 1000)'), and the ranking basis ('overall technology-readiness signal'). It is reasonably distinct from the singular sibling get_company_insight, though the distinction is implicit rather than explicit. The trailing 'Understanding plan.' is confusing but not enough to sink the purpose.

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

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

No guidance is given about when to use this tool versus alternatives such as get_company_insight or other find_* tools. The 'by name' phrasing weakly implies a name-based search, but there is no explicit when-to-use, when-not-to-use, or alternative selection criteria.

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

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

With no annotations, the description carries the burden and does add behavioral facts: results are real request/response examples, and include=['content'] changes the response by inlining bodies. It does not disclose read-only status, pagination defaults, match semantics, or output structure, though these may be partially inferable from tool type.

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-loaded, with filtering details and the find_artifacts handoff in the final sentence. The first two sentences are slightly redundant ('Example payloads' and 'Real request/response examples'), but overall there is minimal waste.

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

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

This tool has 9 parameters, no required fields, no annotations, and no output schema, yet the description only covers a subset of filtering options and one include value. Missing page/limit behavior, match semantics, providers values, and expected response shape leaves significant gaps for an agent trying 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?

Only 4 of 9 parameters have schema descriptions, and the description only clarifies include and names q/tags/providers as filters. It adds no semantic detail for page, limit, match, or providers, and does not compensate for the low 44% schema 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?

The description clearly states the tool's resource and intent: 'Example payloads across the catalog' and 'Real request/response examples.' It also differentiates it from a close sibling by explicitly directing cross-type searches to find_artifacts, so an agent can select this tool with confidence.

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 guidance ('Filter by q / tags / providers; include=["content"] inlines bodies') and explicitly names an alternative for cross-type search. It does not exhaustively enumerate when to prefer this over all other find_* siblings, but the provided context is clear and actionable.

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

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

With no annotations, the description carries the behavioral burden. It discloses a useful behavior: include=['content'] inlines bodies. However, it does not explicitly state that this is a read-only search, describe pagination behavior, or mention match semantics. For a find-style tool this is adequate but not rich.

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

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

Three sentences with no redundancy: resource, scope, filters, include behavior, and sibling alternative are each packed efficiently. The most important identifying information is front-loaded.

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

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

Given 9 parameters, no annotations, and no output schema, the description covers tool selection and primary filters but leaves pagination, match semantics, and billing_model selection to the schema. It is sufficient to choose the tool, but not fully complete for invoking it confidently in edge cases.

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

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

Schema coverage is low (44%), with page, limit, match, include, and providers undocumented in the schema. The description adds genuine value by naming q/tags/providers filters and explaining that include=['content'] inlines bodies. But key parameters like billing_model, match, page, and limit are not addressed, so it does not fully compensate.

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 the resource ('FinOps / billing models') and the scope ('across the catalog') with a specific verb, and explains what the domain means ('How usage is metered and billed'). It also distinguishes itself by pointing to find_artifacts for cross-type search, so an agent can tell this tool apart from at least one sibling.

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

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

The description gives clear context for when to use the tool — FinOps/billing models in the catalog — and states an explicit alternative: 'Use find_artifacts for cross-type search.' It does not fully map all boundary cases against the many other find_* siblings, but the primary when/when-not guidance is present.

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

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

With no annotations, the description carries the full transparency burden. It discloses a meaningful behavior ('include=["content"] inlines bodies') and the catalog-wide scope, but it omits other behavioral details such as match semantics, pagination defaults, 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?

The description is brief and front-loaded, with the core subject in the first sentence and the key alternative in the last. The second sentence, 'GraphQL type systems,' is largely redundant with the first and does not fully earn its place.

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

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

Given an 8-parameter tool with no annotations and no output schema, the description gives a solid starting point but is incomplete. It covers the main filter options and one cross-type alternative, yet leaves match behavior and the meaning of several parameters 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 description coverage is only 38%, so the description must compensate. It does add meaning for 'include' (inlines bodies) and identifies 'providers' as a filter, but page, limit, and match are left with only their schema names/enums and no explanatory content.

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 the resource clearly ('GraphQL schemas across the catalog') and differentiates from a sibling ('Use find_artifacts for cross-type search'). It lacks an explicit verb like 'find' or 'retrieve,' but the filtering language and tool name make the action clear.

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

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

It gives an explicit alternative and when-not condition: 'Use find_artifacts for cross-type search.' It also tells the agent what filters are available (q / tags / providers) and how to inline bodies with include=['content'], providing useful invocation 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?

No annotations are present, so the description carries the full burden of behavioral disclosure. It communicates only that the tool browses and sorts by count; it does not reveal pagination behavior (implied by page/limit params), whether q filters results, what 'provider/API count' means, or what the return payload looks like. Browsing implies read-only, which is some signal, but coverage is thin given zero annotation support.

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 short sentence plus a fragment, front-loaded with the core action and the distinctive sort affordance. No wasted words. It is efficient, though it could absorb a little more useful detail (e.g., what q filters) without becoming bloated.

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

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

With no output schema, no annotations, and only 20% schema coverage, the description is the only behavioral source, and it is too thin. An agent has no idea what q accepts, which sort values are legal, how pagination works despite page/limit defaults, or what shape the result takes. For a 5-parameter discovery tool this is a meaningful completeness gap.

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

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

Schema coverage is only 20% (just the 'context' parameter is described), so the description must compensate. It does clarify 'sort' by stating the sort dimension is provider/API count, but it does not enumerate valid sort values, and the 'q' parameter's filtering semantics are left entirely unexplained. page/limit are partially self-documenting via numeric names and defaults, yet the overall parameter picture remains largely opaque.

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 clear resource (industry verticals) and a concrete capability (browse, sort by provider/API count). Among the large find_* family it is reasonably distinguishable from get_industry and get_industry_leaders by framing itself as a listing/discovery tool, though it never states how it differs from those siblings.

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

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

The verb 'browse' and the sort capability imply discovery use, but the description gives no explicit when-to-use guidance, names no alternatives (find_areas, find_regions, find_tags, find_cohorts all compete for the same browse job), and offers no exclusions or conditions for selecting this tool over its many siblings.

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

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

With no annotations, the description carries the full disclosure burden. It usefully reveals a behavioral/commercial trait — the investor count is free while named firms require Pro — but it does not mention output shape, error behavior, or whether any privileges are needed beyond the count/name distinction.

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

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

The description is a compact two-part statement: the core purpose first, then the free-vs-Pro constraint. The 'UNDERSTANDING —' prefix and 'edge' jargon add a little noise, but every substantive sentence earns its place.

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

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

For a one-required-argument lookup with no output schema, the description conveys the request semantics and the main output limitation. It is adequate, but it leaves the actual return structure and the meaning of 'Pro' unspecified, which an agent may need to know to evaluate the result.

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

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

The schema documents context, but not slug; the description compensates by specifying that slug identifies the provider/company being reverse-looked-up. It adds real meaning to the otherwise bare string parameter, though it does not define slug format or source.

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 precise verb/resource combination: given a provider/company slug, return the VC firms that back it — the reverse of a normal portfolio lookup. This clearly distinguishes it from siblings like find_vcs and vc_portfolio.

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 'reverse portfolio edge' framing gives a clear context: call this when you need the investors behind a specific company rather than a general VC search or a VC's own portfolio. It does not spell out exclusions or explicitly name alternatives, but the use case is unambiguous.

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

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

With no annotations, the description carries the full behavioral burden. It contributes one genuine behavioral fact — include=['content'] inlines bodies, which explains a side effect of a parameter the schema only exposes as a bare enum. But it discloses no safety profile, default sort/ordering, pagination behavior, or result shape, leaving much of the behavioral picture to inference.

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 with zero wasted words; the subject matter and the sibling routing are front-loaded. The fragment style ('JSON-LD contexts across the catalog. Linked-data vocabularies.') is terse to the point of choppiness, but every sentence earns its place and an agent can absorb it at a glance.

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

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

For a 9-parameter tool with no annotations and no output schema, this is thin. It covers the subject, the filter axes, the inline behavior, and one routing rule, but an agent is left guessing at the result format, default pagination/ordering behavior, and — most importantly — the boundary against the closely named siblings find_json_schemas and find_json_structures.

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 44%, below the threshold where the schema can carry the load, so the description must compensate. It adds meaning the schema lacks: include='content' inlines bodies, and providers is named as a valid filter axis even though the schema leaves it undocumented. But page, limit, and match are addressed by neither source, so compensation is only partial.

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 search subject precisely — 'JSON-LD contexts' and 'Linked-data vocabularies' in the catalog — and the verb is implied by the find_* family convention. It also names find_artifacts as a sibling to distinguish against. The phrasing is telegraphic (two noun fragments), but the object of the search is unambiguous and not a tautology.

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

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

'Use find_artifacts for cross-type search' is an explicit alternative directive, and 'Filter by q / tags / providers' describes the concrete query surface. However, it only covers one exclusion case and says nothing about when-not to use this versus equally proximate siblings like find_json_schemas or find_json_structures, which an agent would plausibly confuse with this tool.

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

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

With no annotations, the description carries the behavioral burden. It usefully discloses that include=['content'] inlines bodies, implying the default returns metadata only, and it shows this is a filtering/search operation. However, it doesn't state pagination, ordering, read-only behavior, or what the result shape looks like, leaving some gaps.

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

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

The description is compact and front-loaded: scope, then filtering mechanics, then a sibling alternative. There is no filler; every clause earns its place, and the include behavior is packed efficiently.

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

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

For a read-oriented finder with no output schema, the description covers the core purpose, key filters, the include behavior, and an important sibling handoff. It omits pagination and return-value shape, but those are partially inferable from the schema defaults and the tool's name, so the description is nearly 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 only 38%, so the description needs to compensate. It names the main filter dimensions q, tags, providers, and include, and explains that include inlines bodies. But it does not describe page, limit, or match semantics, even though match's any/all behavior is not self-evident from the name alone.

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

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

The description clearly identifies the tool as finding JSON Schemas in the catalog and narrows it to 'standalone data schemas.' It also distinguishes this from find_artifacts by pointing cross-type search there, but the opening is a noun fragment rather than an explicit command like 'Search' or 'List,' so it stops short of a 5.

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

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

It provides an explicit alternative: 'Use find_artifacts for cross-type search,' which tells the agent when not to use this tool. The 'standalone data schemas' phrase gives useful context, but there is no explicit statement of when to prefer this over other schema-related finders such as find_json_ld or find_json_structures.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals a genuine behavioral trait — include=['content'] inlines bodies, implying bodies are excluded by default — and states core filtering behavior. However, it does not disclose response shape, pagination defaults, matching semantics, or performance characteristics, leaving the no-annotation burden only partially met.

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 sentences with zero filler. The scope is front-loaded, the filtering behavior is condensed into one line, and the sibling routing is the final economy. Every sentence earns its place.

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

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

For a 10-parameter tool with no output schema and no annotations, this is thin. It never explains what a returned JSON structure entry looks like, what the default result set is, or how sort/match/providers interact. An agent would need to open the schema and still lack return-format 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 coverage is 50%, and the description adds value for include by explaining that it inlines bodies — meaning beyond the bare enum. It also groups q/tags/providers as the filter surface. But it says nothing about the remaining undocumented parameters (page, limit, match, providers semantics beyond tags) and does not fully compensate for the coverage gap.

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

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

The description identifies a specific resource — JSON structures / data structures behind an API across the catalog — and is distinguishable from find_artifacts via an explicit contrast. However, the lead sentence is a noun fragment rather than a verb+resource statement, and the description does not differentiate it from the closely named sibling find_json_schemas.

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

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

The description explicitly names an alternative — 'Use find_artifacts for cross-type search' — which is a clear when-not condition. The intended use case (searching data structures behind an API, filtered by q/tags/providers) is implied clearly enough to guide selection, though no broader comparison against other find_* siblings is 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?

No annotations are provided, so the description carries the behavioral burden. It usefully reveals that include=['content'] inlines bodies and that filtering is supported, but it does not disclose output format, pagination behavior, read-only status, or what happens with no filters. This is partial transparency rather than a serious gap.

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

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

Three short sentences, each contributing real information: the resource type, the filter capabilities, and the sibling alternative. The most important scoping information is front-loaded and there is no filler.

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

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

With 9 optional parameters and no output schema, the description is adequate but incomplete. It covers core filters and inline content behavior, and names the right sibling for cross-type search, but omits pagination semantics, match behavior, and install_method usage, which an agent may need to call confidently.

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 only 44%, so the description must compensate. It adds meaning for include=['content'] (inlines bodies) and groups q, tags, and providers as valid filters. However, page, limit, match, and install_method get no added semantic help beyond sparse schema text or enum values.

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

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

The description states a specific resource ('MCP servers') and clarifies it as 'Model Context Protocol servers a provider offers to agents.' It also differentiates from a sibling by pointing to find_artifacts for cross-type search, though it does not contrast against all nearby find_* tools.

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

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

The description explicitly names the primary filters (q, tags, providers) and gives a concrete alternative: 'Use find_artifacts for cross-type search.' It does not state when not to use the tool beyond that, but the guidance is clear enough for selection in most cases.

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

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

With no annotations, the description carries full behavioral burden. It does disclose filtering and the include content inlining behavior, but leaves pagination defaults, match semantics, and result shape unmentioned.

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

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

Three sentences with no wasted words. The central resource is front-loaded, key filters are summarized, and the sibling alternative is named compactly.

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 tool with no annotations and no output schema, the description is adequate for tool selection and basic invocation, but omits matching and pagination semantics that would be needed for more complex calls.

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 only 38%, so the description must compensate. It adds meaning for providers and the include enum, but does not explain match any/all behavior, page, limit, or the context parameter.

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

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

States the resource clearly: OpenAPI specifications across the catalog, described as the REST contract. It also distinguishes itself from get_openapi and find_artifacts, making sibling separation 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?

Explicitly routes usage: get_openapi for a single API's primary spec, find_artifacts for cross-type search, and provides filter dimensions q/tags/providers. The agent knows when to choose this tool over 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?

With no annotations, the description carries the full burden and does so thoroughly: it discloses segment-wise matching, per-operation row semantics despite tag-split specs, the `apis` aggregation of duplicate documents, max_providers cap behavior, and the `meta.query.truncated` signal. This goes well beyond a minimal definition.

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

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

The description is dense and front-loaded with the core purpose, and most sentences add operational value. The 'tags are what a company says about itself' aside is helpful for differentiation but slightly rhetorical; overall it remains well-structured for a tool with this nuance.

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 seven parameters, no output schema, and no annotations, the description covers query semantics, filters, duplicate handling, provider limits, and truncation metadata. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 57%, but the description meaningfully enriches the key parameters: it explains q as path segments that all must appear, method as a verb narrow, deprecated as targeting retiring operations, and max_providers as the read cap with truncation reporting. This compensates for the incomplete schema and adds real selection guidance.

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

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

The description opens with a specific, differentiated purpose: 'CATALOG-WIDE operation search: which providers expose a path matching your terms.' It names the resource (operations), the verb (search/find), and draws a clear contrast with tags, so an agent can distinguish it from find_tags/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?

It explains matching semantics ('Terms match path SEGMENTS (all must appear)') and gives concrete narrowing guidance: 'Add method to narrow by verb, deprecated=true for the retiring ones.' It does not explicitly name sibling alternatives or exclusion cases, but the usage context is clear enough for an agent to decide when to call 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?

There are no annotations, so the description carries the behavioral burden. It discloses one meaningful behavior: include=['content'] inlines bodies, implying bodies are not inlined by default. However, it does not describe pagination, ordering defaults, match semantics, or return shape, which are relevant for a 9-parameter search 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?

The description is compact and front-loaded: purpose first, then filters/options, then the sibling alternative. Every phrase earns its place; there is no fluff or repetition, and the key differentiator is stated at the end.

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 required parameters, the description covers the essential behavior: what it searches, what filters exist, what the include option does, and when to use a sibling. It does not detail response format or every paging/sorting default, but those are either in the schema or conventionally inferable for a find_* 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 only 44%, and the description compensates partially by naming q, tags, providers, and include, with include behavior explained ('inlines bodies'). Still, page, limit, sort, match, and context receive no description-level help beyond the schema, leaving some parameter semantics under-specified.

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 immediately identifies the resource ('Pricing plans across the catalog') and defines it as 'An API's pricing tiers', which is specific and matches the tool name. It also differentiates from a key sibling by saying 'Use find_artifacts for cross-type search.' This is enough for an agent to understand what the tool returns and how it differs from nearby tools.

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

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

The description gives practical guidance: 'Filter by q / tags / providers; include=["content"] inlines bodies.' It also names an explicit alternative, find_artifacts, for cross-type search. It does not enumerate when not to use it relative to every other find_* sibling, but the core routing context is clear.

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

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

No annotations exist, so the description carries the behavioral burden. It discloses that results are references by default and that include=['content'] inlines bodies, which is meaningful beyond the schema. It does not describe output shape or pagination, but for a read-only search tool this is reasonable.

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

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

Three short sentences, each adding a distinct piece of information: the resource scope, the reference-vs-content behavior, and the alternative sibling tool. No wasted words and no repetition of schema details.

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

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

For an optional-parameter search tool, the description plus schema covers the main invocation path: what is searched, how to filter, and how to inline content. The main gaps are lack of return-format detail and a fuller sibling comparison, but neither blocks correct use.

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

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

Schema description coverage is low (~38%), and the description compensates by identifying q / tags / providers as filters and clarifying that include=['content'] inlines bodies. It does not explain match or pagination defaults, but those are visible in the schema and relatively self-explanatory.

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

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

The description clearly identifies the resource ('Postman collections') and the scope ('across the catalog'), and explicitly contrasts with find_artifacts for cross-type search. An agent can immediately tell this from the many sibling search tools.

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

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

It gives a concrete alternative: 'Use find_artifacts for cross-type search.' It also states the key filtering inputs (q, tags, providers) and the include behavior. It does not enumerate all exclusions or compare with find_collections, but provides enough context for correct use.

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

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

With no annotations, the description carries the behavioral burden. It does disclose that the result is paginated/sortable and clarifies the non-obvious tag semantics (company identity vs endpoint touch). However, it does not explicitly state read-only behavior, output record shape, pagination defaults, or any edge-case behavior, so it is only minimally transparent.

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

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

Three sentences with no filler. The core purpose is front-loaded, the critical tag ambiguity is explained immediately, and the final sentence gives cross-tool guidance. Every sentence earns its place.

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

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

For a 21-parameter tool with no annotations and no output schema, the description covers the most important semantic traps and routes between related tools. It lacks explicit output field details and some parameter definitions, but the input schema covers many of those, making this reasonably complete for selecting and invoking the tool correctly.

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

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

Schema coverage is only 57%, but the description compensates by mapping the main filter dimensions (text, tag, artifact type, industry, region, rating band, access model) to parameter groups. It adds the crucial distinction between tags and api_tags, which is not obvious from the schema alone, though some params like min_score, providers, and area remain under-explained.

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

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

The description opens with 'Paginated, sortable list of providers', giving a specific verb, resource, and result shape. It also distinguishes itself from siblings by explicitly mentioning find_apis and apis_io_search, so an agent can tell it apart without inspecting schemas.

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

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

It gives explicit routing guidance: use apis_io_search first for a cross-type overview, and use find_apis?tags= or api_tags= for resource-level terms. The tag distinction clearly tells the agent when find_providers is not the right tool.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses a key trait—these are 'declared' throttling policies, not necessarily enforced ones—and explains that include=['content'] inlines bodies. However, it does not clarify read-only behavior, pagination behavior, or what happens when filters return no matches.

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

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

The description is compact and front-loaded with the resource definition, then filters, then the alternative tool. The two opening noun phrases are slightly clunky but not redundant—'across the catalog' and 'declared throttling policies' carry distinct scope and semantic meaning.

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?

This is a 9-parameter search tool with no output schema and no annotations, so the description needs to provide more context. It omits the meaning of match, sort, page, limit, and context, and does not describe the shape of results or how to interpret policy entries. The single sibling pointer helps, but the overall picture is incomplete for reliable invocation.

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

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

Schema description coverage is only 44%, so the description needed to compensate. It adds meaning for q, tags, providers, and include (especially 'inlines bodies'), but it does not explain match semantics, sort behavior, page/limit defaults, or the context parameter. The compensation is partial, not complete.

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 ('rate-limit policies') and scopes it ('across the catalog'), and distinguishes it from sibling search tools by noting these are 'declared throttling policies.' However, it lacks an explicit action verb like 'find' or 'search' in the main clause, relying on the tool name to supply the operation.

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 a clear alternative: 'Use find_artifacts for cross-type search,' which tells the agent when not to use this tool. It also states the main filtering modes (q / tags / providers) and the include option, giving practical invocation 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the comparison window, but not whether results are sorted by absolute change, what the returned records look like, whether pagination is handled, or if any side effects exist. This is under-disclosure for a tool with no output schema.

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

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

The description is a single, front-loaded sentence that states the core behavior without waste. The 'UNDERSTANDING —' label is minor noise, but not harmful.

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 annotations and no output schema, the description leaves important context undefined: return format, how 'biggest' is measured, and what an agent should do with the result. An agent can invoke it, but cannot fully anticipate 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?

The description adds no meaning to the existing parameters. The schema describes context well and gives limit type/default/min/max, but with 50% schema description coverage the tool description should have compensated at least minimally; it does not mention either parameter.

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

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

The description uses a specific verb and resource: it finds rating movers, and defines them as the biggest up and down changes since the previous scoring build. This distinguishes it from related tools like find_ratings or get_rating_history, though it does not explicitly name an alternative.

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

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

No guidance is given about when to prefer this tool over siblings such as get_rating_history, find_ratings, or whats_changed. The time-window phrase implies use for recent changes, but there are no explicit use cases, exclusions, or alternative conditions.

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

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

With no annotations provided, the description carries the full burden. It discloses the read-like nature (leaderboard) and the ability to filter and sort, but doesn't mention pagination, limits, or error behavior. It adds basic behavioral context but lacks depth on edge cases or side effects.

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

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

Two concise sentences that front-load the core purpose and sorting options. Each sentence adds value—the first defines the tool's output and filters, the second explains sorting dimensions. No superfluous 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 10-parameter tool with no output schema and no annotations, the description gives a solid overview but leaves gaps: it doesn't mention tags, pagination, or the return structure. It also doesn't differentiate from find_rating_movers, which could confuse an agent choosing between them. Adequate but not exhaustive.

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

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

The description significantly compensates for the low schema coverage (20%) by explaining key parameters: 'band' maps to band, 'score range' to min_score, 'trend' to trend, 'facet threshold' to min_facet, and it clarifies all sort options. However, it doesn't cover tags, page, or limit, leaving some parameters undocumented in both schema and description.

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

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

The description clearly states a specific verb and resource: it returns a ranked ratings leaderboard with filtering and sorting capabilities. It distinguishes the tool from siblings by emphasizing the leaderboard aspect, though it doesn't explicitly name alternatives.

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

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

The description implies usage when a ranked leaderboard is needed, but it doesn't explicitly contrast with similar sibling tools like find_rating_movers or get_provider_rating. No when-not-to-use guidance is provided, leaving the choice to the agent's 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?

No annotations are provided, so the description carries full responsibility. It states the browse action and sorting behavior, which implies read-only, but does not disclose pagination, response shape, or any side effects. The single sentence is thin on behavioral context.

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

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

One short sentence that efficiently states purpose and key capability. It is front-loaded and free of filler, though it could include more detail without much cost.

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