apis-io

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description does not need to restate those. The description adds pricing and plan-inclusion context, which is useful but not behavioral. It does not disclose whether adding a duplicate member is silently ignored (idempotent) or whether the list must already exist, though idempotentHint partially covers that.

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 compact sentence that front-loads the action and resource, then adds pricing context. It is efficient and does not waste words, though the pricing detail could arguably be moved to a pricing reference.

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 mutation tool with no output schema, the description covers the core action and member identifier format. It lacks explicit confirmation of what 'id' refers to and does not mention error cases (e.g., nonexistent list, invalid slug/aid). The idempotentHint annotation covers duplicate behavior, but the description itself is thin on operational context.

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

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

Schema description coverage is only 33% (only 'context' has a description). The description adds meaning for 'members' by saying they are providers/APIs identified by slug or aid, which helps. However, 'id' is left undocumented in both schema and description; the description says 'one of your lists' but does not explicitly say id is the list id. This is a partial compensation 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 states a specific verb ('Add') and resource ('providers/APIs ... to one of your lists'), and clarifies the identifier types accepted (slug or aid). It is clear enough to distinguish from create_list and list_lists, though it does not explicitly name 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 description implies the use case: adding existing providers/APIs to a list. It does not explicitly state when to use this tool versus create_list, delete_list, or get_list, nor does it mention prerequisites like needing an existing list id. The pricing note is context but not usage guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context: it explains the output is a share/proportion, notes it's a 'single-entity synthesis' (B1 pricing), and mentions pricing model. It does not contradict annotations and provides useful details about the nature of the result.

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

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

The description is a single, dense sentence with a dash and technical jargon ('UNDERSTANDING — diffusion'). It front-loads a category label rather than the core action, but it is efficient and conveys the key concept without excessive length. Slightly jargon-heavy but still readable.

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

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

For a simple read-only tool with 3 optional parameters and no output schema, the description explains the core output (share per dimension) and pricing context. It does not specify the exact return format or pagination behavior, but given the tool's simplicity and the presence of page/limit parameters, the description is largely sufficient.

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 description). The description does not mention page, limit, or context at all, so it fails to compensate for the low schema coverage. An agent gets no guidance on how pagination works or what the context parameter is for beyond the minimal schema text.

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 function: for each agent-readiness dimension, it returns the share of scored providers that satisfy it. It also adds context about the denominator's importance, distinguishing it from sibling tools like get_agent_readiness (single provider) and find_agent_readiness (search). The purpose is specific and non-tautological.

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 needing the proportion of providers meeting a dimension ('the denominator every claim needs'), but it does not explicitly name alternatives or conditions for when to use this versus get_agent_readiness or find_agent_readiness. It gives context but no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond that: the federated multi-section return, per-section limit semantics, and the disclosure that the `context` parameter is never used in ranking. It does not mention pagination or output format details, but the core behaviors are well 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?

Three sentences, front-loaded with 'START HERE' and the core purpose, followed by the routing to alternatives. No wasted words; every sentence carries information an agent needs to select and call the tool correctly.

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 14 parameters and no output schema, the description adequately explains the return shape (top matches per section with counts) and the main filtering options, and routes to more specific tools for deep dives. It doesn't enumerate all filter values or the full response structure, but for an initial overview tool this is sufficient; an agent can infer the rest from the schema and tool naming.

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 roughly 50% (8 of 14 params documented). The description adds meaning by naming the filter dimensions (tags, artifact types, industry, region, rating band) and clarifying that `limit` is per section, which partially compensates. However, several parameters (area, providers, min_score, industry, artifact_types) are left without explanation in either the schema or description, so the coverage gap is only partially addressed.

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

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

States a specific verb ('search') and resource ('APIs.io catalog') and clearly describes the federated overview behavior (returns APIs, providers, tags with counts). It explicitly distinguishes itself from sibling tools find_apis/find_providers/find_tags and get_api/get_provider, making its scope 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?

Opens with 'START HERE' positioning it as the entry point, and explicitly tells the agent when to use alternatives: 'To page/sort the full list of ONE type, use find_apis / find_providers / find_tags; for one entity, get_api / get_provider.' This gives clear routing guidance and conditions.

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

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

Annotations already mark readOnlyHint=true; the description adds a plan requirement, pricing under pay-as-you-go, plan inclusion, and the fact that reviewer notes are returned. It does not describe failure behavior for unknown ids or rate limits, but given the read-only annotation, the added context is meaningful and non-contradictory.

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

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

Dense but each sentence adds information: status list, plan requirement, error-reporting path, and pricing. The leading 'INFLUENCE —' and the trailing 'See apis://prices' are slightly extraneous, but the overall length is appropriate for the behavioral and cost information conveyed.

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 operation is simple; the description covers what is returned (statuses and notes), the required plan, pricing, and an error-handling alternative. With no output schema, it reasonably explains the return shape, though it omits behavior for invalid or unknown ids and any polling guidance.

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

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

The schema documents context but not id (50% coverage); the description says 'The id identifies the request,' which adds only minimal semantics and no format or example. The context parameter is already fully described in the schema, and the description does not add to it. Thus the description partially compensates for the missing id documentation but not richly.

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?

Clearly identifies the resource as 'a check request by id' and enumerates the possible statuses (queued, in_review, running, done, rejected, needs_info), so an agent can tell this is a status lookup. The opening 'INFLUENCE —' is stylized and lacks an explicit verb like 'retrieves' or 'returns', and it does not contrast with sibling lookups such as my_checks or request_check, 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?

States the precondition that the Influence plan is required and explicitly says to use report_correction or the api-evangelist repo for error reporting, giving a when-not and an alternative. It does not spell out when to prefer this over related check-management tools (e.g., my_checks, request_check), so usage guidance is strong but not exhaustive.

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

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

The description goes well beyond annotations by revealing that this is a human-mediated, asynchronous operation returning 202, requiring DNS or file publication, and ending with manual email verification. It also discloses pricing model and that no further API calls are needed. This is rich behavioral context that the annotations (readOnlyHint=false, destructiveHint=false) do not convey.

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

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

The description is dense but efficient, front-loading the core purpose and then walking through the asynchronous flow in a compact way. Every sentence adds information; the pricing and no-further-call notes are relevant. The 'INFLUENCE —' prefix is slightly opaque but not wasteful.

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

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

For a tool with no output schema and a non-trivial human workflow, the description covers the key elements: status code, token, hosts, verification steps, expected email follow-up, tracking via check_status, and pricing. The main gap is that 'slug' is never defined or tied to how an agent should discover the correct listing identifier.

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%: the required 'slug' parameter is undocumented in the schema, and the description does not explain it beyond the general concept of a listing. The context parameter is well-described in the schema, but the description adds no parameter-level meaning. The token/hosts details refer to the response, not to how arguments should be supplied.

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 ('ask to claim a listing as yours') with a clear resource (listing) and outcome (verification token). It is distinguishable from sibling tools like watch_listing or check_status because it centers on claiming ownership, not watching or status-checking.

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 tells the agent when to use it: when you want to claim a listing you own. It also provides clear post-invocation guidance ('there is nothing else to call', 'Track it with check_status'), which effectively scopes the workflow. It does not name alternative claim-related tools or explicitly state when not to use it, 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?

Annotations provide readOnlyHint=true, so the safety profile is known. The description adds valuable behavioral context: pagination behavior (byte-budgeted chunks, complete flag, next_cursor), pricing tier, and the fact that large cohorts are chunked. It also clarifies the 'context' parameter is never used for ranking. This goes beyond the annotation without contradicting it.

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

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

The description is dense but well-organized: purpose first, then pagination, then pricing. Every sentence earns its place. It is slightly long but each clause carries information. The front-loading of 'UNDERSTANDING' and the core purpose is effective. Minor deduction for the pricing sentence being somewhat tangential to tool invocation.

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

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

For a read-only paginated list tool with no output schema, the description covers the essential invocation flow: what it returns, how to paginate, and how to handle the context parameter. It does not describe the exact shape of the response items, but the absence of an output schema makes that a minor gap. The pricing and inclusion info is a bonus. Overall, an agent can call this tool correctly with the information given.

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 have descriptions; kind and slug do not). The description compensates by explaining the pagination semantics of cursor ('call again with cursor set to next_cursor') and the purpose of context ('why you are asking... never included in the answer'). It does not explain kind/slug values, but those are fairly self-evident from the enum and the tool's purpose. The description adds meaning beyond the schema for the pagination flow.

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 clear verb and resource: 'UNDERSTANDING — what every member of a cohort actually publishes: artifact counts by type plus the agent-readiness dimensions each one satisfies.' It names the specific output (capability matrix) and distinguishes it from sibling tools like cohort_stats or cohort_scores by focusing on artifact counts and agent-readiness dimensions. The title 'Cohort capabilities' is reinforced, not merely restated.

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

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

The description gives explicit pagination instructions ('while complete is false, call again with cursor set to next_cursor') and pricing context ('Priced B2... $0.05 per call... included in Understanding and Influence'). It does not explicitly name alternative tools or when-not-to-use, but the context of 'capability matrix behind a market report' implies its use case. Slight gap: no explicit exclusion of when to use cohort_stats or cohort_scores instead.

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

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

Annotations already declare readOnlyHint, so no mutation risk needs restating. The description adds a meaningful limitation ('Named checks only — facet rollups cannot name the checks underneath them') and a detailed cost model with a cap and plan inclusion, which is useful context beyond annotations. It does not describe return formatting, but the read-only safety profile is already covered.

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

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

The description front-loads the core purpose and then adds the gap_analysis contrast, a limitation, and pricing – all useful. However, the rhetorical 'Turns fix your OpenAPI...' line and redundant 'See apis://prices' after 'Estimate first' add fluff, so not 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?

With no output schema, the description only loosely suggests the return is named failing checks ranked by cohort-mean impact; it does not state record fields or sorting beyond 'ranked'. It also never explains how to resolve a valid slug or where the cohort/market identifier comes from. Pricing and read-only safety are covered, but invocation-critical semantics are 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?

Only the context parameter has schema description coverage (20%), and the description adds no explicit guidance for kind, slug, page, or limit. It hints at 'industry' and 'market', but never maps those hints to the required slug/kind semantics or to pagination. With low schema coverage and no descriptions in the text, this is a clear 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 defines the tool as revealing the agent-readiness checks a cohort's members most commonly fail, ranked by potential impact on the cohort mean. It distinguishes itself from gap_analysis by naming it as the inverse, which pinpoints the resource and the analytic angle. This makes the purpose concrete even without an 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?

It explicitly contrasts this tool with gap_analysis: under-served markets go there, rubric failures go here. This gives an agent a clear decision rule for its closest sibling. It does not cover other sibling tools, but the key alternative is handled.

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

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

The readOnlyHint annotation is reinforced rather than contradicted. The description goes further by disclosing that membership changes over time, that results are means over members present on each date, and that movements cannot be attributed to scores alone without considering population change. It also adds pricing/plan 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?

The description is dense but front-loaded with the core definition. The narrative about the missing middle and pricing information both earn their place by aiding tool selection and cost awareness, though the text is slightly longer than strictly necessary.

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

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

The description covers output, caveats, and read-only behavior well. However, the required kind and slug parameters remain under-specified and there is no output schema to clarify them further. An agent can probably infer usage from the example, but the definition is not fully self-sufficient for correct invocation.

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

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

Only the optional context parameter is described in the schema. The required kind and slug parameters are not explained — the description only hints at slug through the 'banking' example and never defines how the enum values map to cohorts. With schema description coverage at 33%, the description needed to compensate but largely 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 states exactly what is returned — a set-level time series of Kin Score and agent readiness, with the mean over members present per date and members_scored. It also differentiates itself from per-provider and whole-dataset series, so it is clearly distinguishable from siblings like cohort_scores or get_rating_history.

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

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

The description gives a concrete motivating use case ('how has banking moved over six months') and frames the tool as the missing middle between per-provider and whole-dataset series. It does not explicitly name sibling tools or state when not to use it, so it falls just short of full guidance.

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

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

Annotations already mark readOnlyHint=true, so safety is covered. The description adds meaningful behavioral context: returns two distinct orderings, emphasizes the rank gap as the key takeaway, and discloses per-result pricing with caps and plan inclusion. This goes beyond the bare annotation without contradicting it.

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

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

The purpose is front-loaded in the first sentence, and the interpretation note about rank gaps earns its place. The pricing details are somewhat redundant with the inline 'See apis://prices' pointer, but the description remains compact and well ordered.

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 low schema coverage, the description should explain return shape and parameter mapping, but it does not describe what fields a result contains beyond two ranks. It is usable because read-only safety is annotated and the purpose is clear, but meaningful gaps remain around response format and pagination behavior.

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

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

Schema description coverage is only 20%, so the description must compensate, but it does not explain how `kind` and `slug` select the market/cohort, nor what `page` and `limit` control. The only parameter-adjacent detail is per-record pricing, which is about cost rather than 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 concrete resource, 'the leaderboard for a market', and specifies its two ranking axes, which distinguishes it from generic score/stats siblings like cohort_scores or cohort_stats. A verb is implied rather than stated, and the relationship between 'cohort' and 'market' is left undefined, but the object is clear enough for selection.

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 it: for market leaderboards and cross-ranking 'gap' analysis. However, it names no alternatives, exclusions, or when-not-to-use conditions, and the pricing/estimate guidance is operational rather than a usage-selection rule.

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

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

Annotations provide readOnlyHint=true, and the description does not contradict it. Beyond the annotation, the description adds significant behavioral context: a detailed pricing model ($0.005 per request + $0.0002 per record, capped at $0.50, pay-as-you-go, included in certain plans), billing category 'UNDERSTANDING', and a pointer to estimate costs first and to apis://prices. This goes beyond what the annotation supplies.

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 moderately sized but every component earns its place: the purpose is front-loaded, the illustrative sentence aids comprehension, and the pricing and estimation details are essential for safe invocation. It is not as tight as a two-sentence ideal but contains no pure filler.

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

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

The description explains the core return concept (facet-level scores with cohort average and delta) and pricing behavior, but it omits how to identify a cohort (the slug parameter origin) and does not mention pagination behavior or defaults for 'page' and 'limit', despite the schema having explicit bounds. Given no output schema, it could have linked to find_cohorts or clarified the cohort reference.

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 tool description does not explain what 'slug' refers to or how 'kind' interacts with it, nor does it clarify defaults or behavior of 'page' and 'limit.' Since the schema is under-documented and the description does not compensate, an agent would have to infer that slug is a cohort identifier and know to use find_cohorts to obtain it.

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

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

The description opens with 'UNDERSTANDING — facet-level scores for every member of a cohort, each with the cohort average and the delta against it.' This names the specific resource (cohort scores), the action (fetch facet-level scores), and the output shape (scores with cohort average and delta). The analogy ('A 60 in governance means nothing until you know the market sits at 45') further differentiates it from siblings 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 description establishes clear context: this endpoint is for understanding how a cohort's facet-level scores compare to the average, and is explicitly framed as 'the endpoint that says so.' However, it does not name sibling alternatives (e.g., cohort_rankings for rankings, cohort_stats for aggregate stats) or state when not to use it, so it stops short of full exclusion 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?

Beyond the readOnlyHint annotation, the description discloses crucial behavioral details: it always includes a 'coverage' block indicating how much of the roster is scored and enrichment depth, and it warns that cohort enrichment depth spans ~42 points of catalog_gap, meaning part of any cohort number reflects coverage rather than market reality. It also provides pricing information. This goes far beyond the annotation and is essential for correct interpretation.

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 somewhat long but well-structured: it front-loads the purpose, then adds the live-computation context, the coverage caveat, and pricing. Each sentence serves a purpose, though some redundancy exists (e.g., 'computed live' and 'market-stats sheet' could be combined). Overall, it is efficiently organized and not 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?

Given that there is no output schema, the description adequately covers the expected output (statistics and coverage block) and the critical caveat about coverage affecting the mean. It also includes pricing. However, it lacks explicit parameter guidance and does not describe the output format in detail, which is a minor gap for a tool with no structured output definition.

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 does not explain the parameters 'kind' or 'slug' beyond what the enum implies. With only 33% schema description coverage (only 'context' has a description), the description should compensate, but it offers no guidance on how to specify cohort type or slug. It adds no value for parameter usage, leaving agents to guess from the enum values.

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

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

The description explicitly states it provides 'the DISTRIBUTION for a whole market' with a specific list of metrics (mean, median, min/max, stdev, etc.) and identifies itself as the 'market-stats sheet from a Trend Report'. This is a clear verb+resource statement that distinguishes it from sibling cohort tools like cohort_scores (individual scores) or cohort_rankings (rankings) by focusing on aggregate distribution statistics.

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 it (for market-level distribution stats) but does not explicitly state when not to use it or name alternative tools. The phrase 'UNDERSTANDING — the DISTRIBUTION' suggests a use case, but there is no explicit guidance on selecting this over other cohort tools, leaving the agent to infer from context.

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

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

Annotations only carry readOnlyHint=true and a title, so the description carries the transparency burden. It adds meaningful operational traits beyond the annotation: the tool performs cross-catalog synthesis ('Priced B2 (cross-catalog synthesis)'), has a concrete per-call cost ($0.05), and a pointer to authoritative pricing ('See apis://prices'). For an agent making cost-aware decisions, this is valuable behavioral context that the readOnlyHint alone does not provide. The 'UNDERSTANDING' framing is consistent with read-only semantics, so no contradiction.

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

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

The description is compact at three sentences, with the core purpose front-loaded before pricing details. Each clause earns its place, and the pricing pointer is the only auxiliary sentence. It loses a point for the cryptic 'UNDERSTANDING'/'Priced B2' jargon, which requires proprietary knowledge to fully parse, but overall it is efficiently organized and free of redundancy.

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

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

With no output schema, the description carries the burden of explaining returns, and it does convey the return concept ('weakest investment dimensions'). However, the output shape remains structurally vague (list of dimensions? scored?), the required input semantic for 'slug' is never made explicit, and no behavioral guarantees (e.g., nothing about how the synthesis is computed) are given. It is adequate for a simple read-only tool but leaves the agent to infer what the result actually looks like.

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%: the required 'slug' parameter has no description in the schema, while 'context' is well-documented. The description partially compensates by implying slug identifies the company ('A company's weakest investment dimensions'), but it never explicitly states that slug is the company identifier or describes its expected format. The 'context' parameter is fully covered by the schema, so description credit is only needed for slug, which it only half-provides.

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

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

The description states a specific output concept: 'A company's weakest investment dimensions — where it is thin and a vendor could sell in.' This identifies both the resource (a company) and the synthesized result (weakness dimensions with vendor sell-in opportunities), which is more specific than a generic name like 'company_gaps'. It earns a 4 rather than 5 because the verb is implicit (the 'UNDERSTANDING' prefix is a category label, not an action verb) and it doesn't distinguish itself from siblings like gap_analysis, industry_gap_analysis, or get_company_insight.

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 only usage-adjacent content is the pricing model ('$0.05 per call under pay-as-you-go; included in Understanding and Influence'), which hints at cost considerations but says nothing about when to choose this tool versus alternatives. With highly similar siblings present — gap_analysis, industry_gap_analysis, insights_dimensions, get_company_insight — the absence of any when/when-not routing is a real gap.

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

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

Annotations only declare readOnlyHint=true, so the description carries the full behavioral burden. It exceeds expectations by disclosing the depth_confounded caveat, pricing structure (per result, per record, cap, included plans), and the purpose of the context parameter. It also clarifies that context is never used for ranking. This is rich, non-obvious 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?

The description is front-loaded with the core purpose, then adds returns, a unique value proposition, a critical caveat, and pricing. While it is somewhat verbose, every sentence adds value—pricing and estimate guidance are useful for an agent. It is not overly redundant, though the pricing details could arguably be moved to an external reference. Still, it is well-structured.

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

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

Despite the lack of an output schema, the description tells an agent exactly what to expect: distributions, deltas, and the depth_note field. It also explains the depth_confounded caveat, pricing, and context usage. For a 3-parameter tool with no output schema, this is complete: an agent knows what it does, what it returns, and how to interpret 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 coverage is 100% and the schema already describes both a and b parameters with examples. The description does not add any additional parameter semantics; it only mentions parameter behavior indirectly (e.g., context purpose), which is already in the schema. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description clearly states 'two markets side by side on one rubric' and lists exactly what it returns (distributions, deltas on score, agent readiness, facets, adoption rates). It distinguishes itself from sibling tools like cohort_scores (single cohort) and compare_providers (providers rather than cohorts) with a specific verb and resource.

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: it is the tool for comparing two cohorts, and even illustrates with a concrete question ('is US payments further along than UK banking?'). It implies when to use it (when a cross-market comparison is needed) but does not explicitly name alternatives or exclusions, so it falls short of a 5.

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

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

The readOnlyHint annotation already covers safety, so the description needs less behavioral disclosure. It adds useful non-obvious context: the pricing tier, per-call cost, and billing inclusion, as well as the shape of the synthesized output. It does not contradict the annotation.

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

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

Two sentences carry the full definition with no filler. The first sentence front-loads the tool's purpose and output, while the second adds pricing context. Every phrase 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?

Given the simple two-parameter schema and readOnly annotation, the description is largely complete: it explains what results to expect and the cost implications. Minor jargon like 'composite/band' and 'per-facet leaders' could be clearer, but an agent can still select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description only implicitly reinforces the '2+' constraint on providers and adds no new meaning beyond the structured 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') with a clear resource ('2+ providers') and enumerates concrete output components: composite/band, per-facet leaders, and artifact-coverage matrix. This clearly differentiates it from siblings like compare_cohorts, which target a different resource.

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 context for when to use the tool: comparing 2+ providers side by side. It does not explicitly mention alternatives or when-not-to-use cases, but the '2+' condition and 'providers' resource establish the core use case without 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?

Annotations (readOnlyHint=false, destructiveHint=false) are neutral, but the description adds significant behavioral context: it returns 202, is applied by a human, score and band are ignored, and payment is never from prepaid balance. This goes beyond annotations and prepares the agent for asynchronous, human-mediated execution.

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

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

The description is dense but efficient; each sentence adds value—purpose, human review, pricing, alternative. It is front-loaded with the primary action. It could be slightly trimmed for brevity, but it avoids redundancy and is well-structured for an agent scanning for key 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?

Despite having 8 parameters and no output schema, the description covers the essential behavior: async human application, return code 202, pricing, and the free alternative. It does not specify the response body format, but for a correction proposal that is acceptable. The context is sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is only 13% (only context is described), so the description must compensate. It names the key editable fields (name, description, url, industries, tags) and notes that score/band are ignored, adding meaning beyond the schema. However, it omits the 'contact' parameter and doesn't elaborate on how 'context' is used (though schema covers it). Overall, it addresses most parameters but not all.

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 proposes corrections to a listing's name, description, url, industries, and tags. It uses the specific verb 'propose corrections' and identifies the resource ('what we say about you'). It also differentiates from siblings like report_correction (free for own company) and dispute_finding, making its role 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 explicitly explains when to use this tool versus the alternative: 'If this is your own company and our data about it is wrong, report_correction is free.' It also clarifies the pricing model and that it is a paid influence action, giving agents clear selection criteria without 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?

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description carries the burden of explaining side effects. It goes beyond the annotations by stating that the list is 'persistent', that the caller owns it, that an API key is required, and that this is a priced 'single-entity synthesis' call. This gives agents meaningful behavioral context without contradicting the annotations.

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

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

The description is concise and front-loaded with the essential action and object. The pricing and API-key details are useful but are appended without bloat. The 'UNDERSTANDING —' prefix is a minor structural oddity but does not detract from readability.

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

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

For a simple 3-parameter tool with no nested objects and no output schema, the description is reasonably complete. However, it does not mention what the caller receives after creation (e.g., list ID or confirmation), which is relevant since no output schema provides that information. The mention of persistence and ownership helps, but the post-conditions are left implicit.

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

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

Schema description coverage is 67%, with 'context' and 'members' well-documented in the schema itself. The description adds little beyond the schema for parameters; 'providers or APIs' loosely maps to the members field, but there is no additional detail about how name is used or how members should be formatted. This is adequate but not compensatory.

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

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

The description clearly specifies the verb ('Create'), the resource ('a named, persistent list'), and the domain ('providers or APIs'). It also adds useful qualifiers—'shortlist / stack you own'—that distinguish this from broader search/read tools like find_apis or get_list. The purpose is immediately recognizable from the first sentence.

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

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

The description communicates preconditions (requires an apis.io API key) and pricing context, but does not explicitly state when to use this tool versus alternatives like add_to_list or delete_list. Usage is implied by the name and the act of creating a new list, but there is no explicit when-not-to-use guidance or direct comparison to siblings.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the core behavioral traits are covered. The description adds pricing context (B1, $0.01) and the ownership requirement, but does not disclose side effects like permanence of deletion or typical responses. With annotations carrying the safety profile, this is acceptable but not enriched beyond them.

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

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

The description is concise and front-loads the purpose. The pricing information is extra but not verbose. It could be slightly tighter (dropping the 'UNDERSTANDING —' prefix), but overall it wastes little space.

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

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

The tool is a simple delete with one required parameter and two parameters total. Annotations cover destructive/idempotent behavior. However, the description does not explain what happens on success (e.g., response structure) or address the ownership constraint in detail (e.g., error handling if not owned). For a low-complexity tool, this is adequate but leaves minor gaps.

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

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

Schema description coverage is only 50% because the 'id' parameter lacks a description, while 'context' is fully described in the schema. The tool description does not mention either parameter, leaving 'id' entirely undefined in both the schema and the description. This is a significant gap that the description fails to compensate for.

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'), a resource ('a list'), and an ownership constraint ('you own'). It clearly differentiates from siblings like create_list, get_list, and list_lists, leaving no ambiguity about what this tool does.

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

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

The description implies a prerequisite (ownership) but provides no explicit guidance on when to use this tool versus alternatives like delete_saved_search or other deletion tools. It also doesn't state conditions such as 'only delete if the list is no longer needed' or mention possible errors. Some context is given via pricing, but usage guidance is minimal.

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

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

Annotations already carry destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the description does not need to restate those. It adds the authorization scope 'you own' and pricing context, but does not expand on what destruction entails or error behavior. No contradiction with annotations.

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

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

The core action is expressed in a short, front-loaded phrase, and the pricing/ownership details are compact. The 'UNDERSTANDING —' prefix and 'B1 (single-entity synthesis)' jargon add minor noise, but the description remains fast 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 one-required-parameter destructive idempotent operation, the description plus annotations cover safety and ownership. Still, it omits how to retrieve the saved search id and what the result of a successful deletion looks like, so an agent must infer these from sibling tool names or error handling.

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%: the required 'id' parameter has no schema descriptionable text, and the tool description does not explain where the id comes from or what format it takes. Since the schema already documents the optional context parameter, the description adds no semantic value for parameters over the schema.

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

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

States the specific verb 'Delete', the resource 'saved search', and the ownership constraint 'you own'. This clearly distinguishes it from siblings like delete_list, save_search, and run_saved_search without requiring schema inspection.

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 a key precondition: only saved searches you own can be deleted. However, it does not explicitly guide the agent on when to choose this over alternatives or how to obtain the id, such as via list_saved_searches. Usage is implied from the tool name and ownership phrase rather than fully specified.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context: results are ranked across all providers, pricing is per request and per record with a cap, and the data source is provider-published OpenAPI deprecation markers. It does not describe response fields, but no output schema exists and the ranking statement implies the core return 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 dense but efficient: it front-loads the core purpose, then adds usage context, the drill-down alternative, and pricing. The statistics and pricing URL are arguably optional but relevant for a paid catalog view, so no sentence is wasted.

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

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

For a paginated, paid, read-only catalog tool with no output schema, the description covers purpose, ranking, alternatives, and cost. It would be more complete with an explicit statement of the response format or fields, but the ranking description and schema constraints make invocation feasible.

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%: context is well described, but page and limit have no textual descriptions. The tool description does not compensate for page/limit semantics; it only obliquely references per-record pricing. The agent must rely on conventional meaning of pagination parameters, which is a real gap for low 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 opens with a specific resource and action: every provider publishing at least one deprecated operation in its own OpenAPI, ranked by count. It clearly differentiates this catalog-level view from per-provider drill-down tools by noting that a provider's own deprecated filter requires you to already suspect the provider.

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

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

It explicitly explains when this tool is valuable ('which nothing could see before') and names the alternative drill-down path: get_provider_operations(deprecated=true). This gives the agent a concrete routing rule between siblings.

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

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

Annotations only say it is not read-only and not destructive; the description adds substantial behavioral context beyond that: it returns 202, a human fetches and checks the evidence, and the caller is emailed either way — making the async human-in-the-loop nature explicit. It also discloses auth expectations (no ownership proof) and pricing/billing behavior. No contradiction with annotations.

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

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

The description is dense but efficient, front-loading the core action ('Send the claim in words and a URL') before pricing and alternatives. Every sentence carries information. The stylistic 'INFLUENCE —' opener and quoted framing are slightly oblique but don't waste words; the apis://prices pointer is a reasonable way to defer pricing detail.

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

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

With no output schema and sparse parameter descriptions, the description carries a heavy burden. It covers the overall flow well (submit → 202 → human review → email either way) and pricing, but leaves 'slug' undefined (what does it identify — the finding? the listing?), which an agent needs to invoke correctly. The evidence_url requirements are also unstated.

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

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

Schema coverage is only 20% (only 'context' has a description), so the description must compensate. It maps 'claim' to the claim-in-words and 'evidence_url' to the evidencing URL, and 'emails you either way' implies the role of 'contact.' However, the required 'slug' parameter is completely unexplained in both schema and description, and 'contact' format is not specified — a real gap for a required param.

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

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

The description states a concrete action — send a claim in words plus an evidence URL to dispute a finding — and the title adds 'Dispute a finding on a listing you own.' It names the sibling it is not (report_correction), which helps disambiguation. Minor deductions: 'finding' assumes internal vocabulary, and the title's ownership framing slightly conflicts with the description's explicit statement that ownership proof is not required.

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

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

The description gives explicit when/when-not guidance: any paying caller can use this to dispute data, and if it's your own company, report_correction is free instead. It also states eligibility ('open to any paying caller... should not have to prove ownership') and pricing conditions (included in Influence vs. $49 one-off, never from prepaid balance). This fully routes an agent to 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?

Annotations declare readOnlyHint=true, and the description adds meaningful behavioral context: it resolves a slug OR any identifier, returns exactly the requested groups, and mentions the 2026-08-31 plan migration. It also discloses pricing and plan inclusion. It doesn't describe error behavior or rate limits, but the read-only annotation plus the explicit scoping covers the main behavioral surface.

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

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

The description is compact and front-loaded: the core value proposition is in the first sentence, followed by the group list, the migration note, and pricing. Every sentence earns its place, and there is no fluff.

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 enrichment tool with a clear schema and no output schema, the description covers the essential decision factors: what it does, when to use it, what groups are available, and cost. It doesn't describe the return shape, but since there is no output schema and the tool is a data-fetching aggregation, a brief note on the response format would be a minor improvement.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the 'field groups' concept and the default set, and by clarifying that 'id' accepts a slug or any identifier resolve() accepts. The 'context' parameter is already well-described in the schema, so the description doesn't need to repeat it.

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

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

The description states a specific verb ('enrich'), a resource ('provider'), and a precise mechanism: one call that resolves a slug or identifier and returns only the requested field groups. It explicitly contrasts itself with chaining four sibling get_provider_* tools, which makes its 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 explicitly says to use this instead of chaining get_provider + get_provider_rating + get_provider_artifacts + get_provider_onboarding, and it lists the available field groups. It also includes pricing and plan context, 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?

Annotations declare readOnlyHint=true, and the description aligns with that by describing an export/read operation. The description adds meaningful behavioral context beyond the annotation: the dataset exceeds one response, pagination is cursor-based with a complete flag, chunks are byte-budgeted, and attribution is required. It does not contradict the annotation. A small gap is that it doesn't explicitly state the response shape, but the pagination behavior is well covered.

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

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

The description is dense but front-loaded with the most important fact (whole dataset, not a page) and then flows through dataset options, pagination, attribution, and pricing. It is longer than ideal, but every sentence carries information an agent needs to call the tool correctly. The pricing detail is arguably extra, but it supports the licensing use case. Slight deduction for length and for burying the pagination protocol mid-description.

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

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

For a tool with no output schema, the description does a good job of explaining what comes back (chunks of data, complete flag, next_cursor) and how to handle it. It covers the three datasets, the pagination loop, attribution, and pricing. It doesn't describe the exact structure of each chunk or the movement summary format, but the description is sufficient for an agent to invoke the tool and handle the response correctly. The licensing/pricing context is a bonus that helps the agent decide whether this tool is appropriate.

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 75%, and the description adds meaning beyond the schema by explaining the dataset enum values in detail (what each dataset contains) and by describing the cursor pagination contract. The context parameter is explained in the schema, and the description reinforces the licensing/attribution context. The co_brand parameter is only lightly touched ('stamps the attribution'), but the schema already covers it. This is above the baseline 3 because the description enriches the dataset and cursor semantics.

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

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

The description states a specific verb ('export') and resource ('the WHOLE dataset'), and enumerates the three dataset options (ratings, providers, history) with what each contains. It also distinguishes itself from page-limited views by explicitly saying it is not a 100-row page, which differentiates it from sibling tools like get_rating_history or find_ratings.

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 intended audience ('media outlets and analysts licensing the data to publish rankings and trends'), explains the pagination protocol ('while complete is false, call again with cursor set to next_cursor and concatenate data'), and gives pricing/licensing context. It also warns that history is the one dataset that cannot be reconstructed after the fact, which is a strong when-to-use signal.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to repeat that. It adds value by disclosing the output type (APIs.json with an Arazzo hint), the pricing model (B3, $0.002/row, $0.50 minimum), and pointing to apis://prices for details. This goes beyond the annotation's safety profile and clarifies the operational context, though it does not mention failure modes or pagination.

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

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

The description is a single, dense sentence that front-loads the primary action and output, then adds pricing and a reference. Every clause earns its place — no fluff, no redundancy. It is well-structured for an agent to quickly parse the core purpose.

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

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

Given the tool has 3 parameters (all schema-documented), a readOnlyHint annotation, and no output schema, the description covers the essential aspects: what it produces, the pricing, and the domain context. It doesn't explain what 'adoptable' or 'Arazzo hint' means, but these are likely domain terms an agent would understand. The main omission is a note on any limits (e.g., max capabilities), but overall it is sufficiently complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds little beyond what the schema states — it implies the capabilities parameter maps to the 'designed capability stack' but doesn't elaborate on region or context semantics. With full schema coverage, the baseline of 3 is appropriate; the description does not significantly enrich 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 states a specific verb ('Export'), a precise resource ('designed capability stack'), and the output format ('adoptable APIs.json document with an Arazzo hint'). It clearly distinguishes this from sibling tools like export_dataset (different output) and find_apis_json (search vs. export) by naming the deliverable and the team-facing intent.

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

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

The description implies when to use the tool: when you have a designed capability stack and want an exportable APIs.json document. It does not explicitly name alternatives or give 'when not to use' conditions, but the context is clear enough for an agent to route correctly. A minor gap is the lack of explicit contrast with export_dataset or find_apis_json.

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?

readOnlyHint already marks this safe; the description adds substantial value beyond that: pricing behavior ($0.005 per request, $0.0002 per record, $0.50 cap), included plan tiers, an estimate endpoint, and the return contents ('agent score + band alongside the Kin Score'). No contradiction with annotations.

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

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

The description is dense but efficient: the 'UNDERSTANDING' category and scope are front-loaded, the examples earn their place, and pricing is relevant for cost-sensitive calls. It is slightly long, but no sentence is wasted.

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

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

For an 8-parameter tool with no output schema, the description covers the core result shape, filter semantics, and pricing. It could be more complete on alternate sibling routing and the exact return structure, but the schema covers most parameters and the main behavior is well specified.

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 description still carries some weight. It adds real semantics for the two primary filters — has and missing — with worked examples and implicit AND behavior. It does not explain page or limit, but those are largely self-evident from schema defaults and constraints.

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 — 'Rank providers by agent readiness' — over a clear resource ('the agent-readiness leaderboard across the whole catalog'), and distinguishes itself from sibling find_agents or get_agent_readiness by emphasizing whole-catalog ranking and cohort filtering with has/missing.

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

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

It gives clear context and concrete use cases: has='mcp_server,protected_resource_metadata' is the OAuth-capable MCP cohort; missing='agent_card' is the addressable market for a fix. It does not explicitly name alternatives or say when not to use this 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?

Annotations already mark readOnlyHint=true, and the description adds meaningful behavioral context: no account is required, only self-registered agents appear, and each row carries verification details such as grade, protocol version, and transport. This goes beyond what the annotation alone conveys, though it does not discuss pagination behavior.

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

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

The description is compact and front-loaded with the most operationally relevant fact ('FREE, no account'). The two sentences are information-dense, though the final metaphor ('the door...') adds rhetorical color rather than strictly necessary specification.

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 list tool with only three optional parameters and no output schema, the description covers the essential facts: access requirements, data source, eligibility, and returned row fields. It is slightly thin on exact output format and ordering, but the tool is simple enough that the description is largely sufficient.

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 explain page or limit parameters at all. The context parameter is already well documented in the schema, so the description adds nothing to parameter understanding 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 specifies a clear resource ('the A2A agent registry'), the population ('agents that registered THEMSELVES by serving an agent card and calling register_agent'), and the row contents. It does not explicitly name a sibling alternative, but the registry framing and self-registration mechanism differentiate it from the many other 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 implies when to use it by calling it 'the door an unattended agent can walk through unaided' and contrasting it with options that need 'a person or a voucher.' However, it stops short of naming a specific alternative tool or stating a clear when-to-use versus when-not-to-use rule.

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

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

The readOnly annotation already signals safety, and the description adds substantive behavior beyond it: matching is 'LEXICAL', q only searches the API's own name/description, provider-name matches are excluded by default, and meta.query.via_provider reports the added rows. This is genuinely useful non-obvious behavior.

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

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

Three dense sentences, front-loaded with purpose, followed by differentiating semantics and routing advice. Every sentence earns its place; there is no filler or repetition of the tool name.

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

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

For a read-only, filterable list tool, the description covers core behavior, result-count semantics, and sibling routing. It lacks a general outline of the response shape, but the schema documents view/fields/limit, and the description reveals the key meta field, so the remaining gap is minor.

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

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

With 59% schema coverage, the description compensates well by naming the filter families (tag, provider, artifact type, industry, region, rating band) and by clarifying q and include semantics. It does not enrich every undocumented parameter, but it adds meaningful context where the schema is silent or ambiguous.

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: 'Paginated, sortable list of APIs across providers.' It names the filtering dimensions and immediately contrasts itself with apis_io_search, so an agent can distinguish this tool from its closest sibling without inspecting the schema.

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

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

The description gives explicit routing guidance: 'Use apis_io_search first for a cross-type overview.' It also explains exactly when to pass include=["via_provider"] to match apis_io_search's larger count, turning a likely source of confusion into an actionable choice.

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

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

Annotations already declare readOnlyHint=true, covering safety. The description adds that include=['content'] inlines bodies, which is a useful behavioral detail. However, it doesn't describe pagination behavior, sorting defaults, or output format. With annotations covering the read-only aspect, the description adds some value but not deep 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?

Three concise sentences with no fluff. The purpose is front-loaded, then filter options, then the sibling alternative. Every sentence adds value, and the structure is 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?

For a search tool with 9 parameters and no output schema, the description gives essential info: what it searches, filters, include behavior, and a sibling pointer. It doesn't explain pagination or sorting defaults, but those are in the schema. The description is adequate for an agent to call it correctly, though it could mention limit/page defaults. A 4 is reasonable.

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 44%, so the description must compensate. It mentions q, tags, providers, and include, adding meaning for those. However, it omits page, sort, limit, match, and context (context has a schema description, but others don't). It partially compensates but doesn't fully cover the undocumented parameters. A 3 is appropriate given partial 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 states it indexes APIs.json discovery documents across the catalog, using the verb 'find' implicitly through the name. It clearly names the resource type (APIs.json) and mentions filtering by q/tags/providers and include parameter, distinguishing it from generic artifact search. It's specific enough, though 'The APIs.json discovery documents themselves' is slightly awkward but understandable.

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 directs the agent to 'Use find_artifacts for cross-type search', naming the alternative tool and the condition that selects it. It also lists the filterable fields (q/tags/providers) and the include option, giving clear guidance on what this tool is for versus its sibling.

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?

ReadOnlyHint already covers the safety profile, and the description adds one useful behavioral trait: include=['content'] inlines bodies. But it says nothing about pagination, default response shape, or empty-result behavior, so transparency is adequate rather than 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?

Four concise sentences lead with the object type and scope, then filters/inclusion behavior, then the sibling alternative. No word is wasted and the most decision-relevant information is front-loaded.

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

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

For a nine-parameter tool with no output schema, this is serviceable: core filters and the main alternative are present, and defaults/enums cover page/limit/sort/match in the schema. But the missing provider input semantics, pagination behavior, and return format leave clear gaps an agent may have to infer.

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 44%, so the description must add meaning. It does identify q/tags/providers as the primary filters and explains that include inlines bodies, which goes beyond the schema. However, provider value format and the interaction of match/filters are still left implicit, so it only partially compensates.

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?

Defines the resource precisely as Arazzo workflows across the catalog and adds the distinguishing trait 'multi-step API workflows chaining operations.' The closing pointer to find_artifacts further separates it from a sibling, so there is no ambiguity about what this tool returns.

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

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

Gives an explicit conditional alternative: 'Use find_artifacts for cross-type search.' This tells an agent when not to reach for this tool and where to go instead, which is exactly the routing guidance needed.

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

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

Annotations already declare readOnlyHint=true, so the safe read-only nature is covered. The description adds that the areas are 'curated, scored provider indexes' and that it supports text search and sorting by provider count, but it does not mention pagination behavior or what happens when no results match. With annotations covering safety, 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?

Two sentences communicate the tool's essence: the taxonomy resource, its curated/scored nature, and the search/sort operations. There is zero fluff and the most important behavioral details are front-loaded.

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

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

For a browse/search tool this description covers the core purpose, but with no output schema it leaves the result shape implied by 'provider indexes' rather than explicit. The allowed sort value for 'provider count' is also unspecified, which an agent must infer or experiment with.

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% (context). The description compensates partially by clarifying that 'q' is free-text search and that 'sort' can be by provider count, but it leaves page and limit under-specified (the schema only provides defaults/ranges) and does not enumerate accepted sort values or the meaning of the response.

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: 'Browse the API Evangelist areas taxonomy', with concrete examples (authentication, webhooks, payments) and the ability to 'Search by text; sort by provider count.' This distinguishes it from sibling find_* tools that search different entities, though it stops short of explicitly naming a sibling alternative.

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

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

The description gives no explicit guidance on when to use find_areas versus alternatives like find_providers or get_area. It states the tool's capability but not the decision context or exclusions, so an agent cannot tell when this tool is the right choice over nearby siblings.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds meaningful behavioral context: it is cross-type, supports a defined list of artifact types, and include=['content'] inlines bodies. However, it does not clarify pagination, limit behavior, or the meaning of 'PRO: scopes, security', and the type string format is ambiguous.

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 rings. The type list is long but functionally useful Newton. The only waste is the cryptic 'PRO: scopes, security' phrase, which adds little without further explanation.

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

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

The description covers primary purpose, type values, and the include behavior, and it has no output schema to document return values. But with 8 parameters and only 13% schema description coverage, the lack of clarification for q, tags, providers, pagination, and exact type format leaves meaningful gaps for correct invocation.

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

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

Schema description coverage is only 13%, so the description must compensate. It adds meaning for type by listing valid artifact types and for include by explaining 'inlines bodies', but it leaves q, tags, page, limit, and providers unexplained. The listed type names also use hyphens (e.g., 'rate-limits', 'apis-json') which may not match the actual string values expected by the schema.

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

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

Description uses a specific verb ('Find'), a clear resource ('artifacts'), and scope ('across the catalog'), plus explicitly labels this as the 'cross-type entry point'. It also distinguishes itself from the dedicated find_<type> siblings, so the agent knows exactly what this tool does and how it differs.

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 directs usage: 'prefer those when you know the type' in reference to the dedicated find_<type> tools papers. It also names the sibling alternative pattern and the condition for choosing it, which is clear routing guidance.

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

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

readOnlyHint already covers safety; the description adds the include=content inlining behavior, which is useful. It does not mention pagination, response shape, or sorting defaults, but for a read-only search tool the annotations plus basic filter info are sufficient.

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

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

Two sentences, front-loaded with the tool's purpose and then the key usage guidance. No filler, no repeated schema content; 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 read-only search tool with 11 parameters, the description covers the essential scope, filtering, and the sibling for broader search. No output schema exists, but the definition gives enough context to select and invoke the tool correctly in most 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 55%, and the description clarifies the meaning of q, tags, providers, and especially include=content (inlines bodies). Other parameters like match, limit, and page are left to the schema or are self-evident, so the description adds marginal but useful value.

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

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

Identifies a specific artifact type (AsyncAPI/event-driven specs) with catalog scope and explicitly distinguishes from find_artifacts. The phrasing 'Event/streaming APIs' reinforces the resource kind, leaving no ambiguity about what this tool searches.

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

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

Provides concrete filtering options (q/tags/providers) and the include=content behavior, and names find_artifacts as the cross-type alternative. It doesn't contrast with every find_* sibling, but the one alternative given is the most relevant.

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

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

Beyond the readOnlyHint, the description discloses meaningful behavioral traits: the default filters to catalog-covered capabilities, the all=true mode produces a 'real answer rather than a gap' by explaining that most enterprise activity runs on internal systems, and it provides full pricing mechanics with a cap and estimate endpoint. No contradiction with annotations.

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

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

The description is front-loaded with purpose and default behavior, but the pricing block is dense and contains the confusing juxtaposition 'Free. Priced per result —'. It conveys necessary cost information but would benefit from tightening and removing the contradictory-sounding opening.

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 6-parameter tool with no output schema, the description covers the domain, default behavior, the all-mode interpretation, and cost implications. It partially describes return content (capability counts per provider) but never details the return shape or pagination behavior, which would make it fully complete.

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

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

Schema coverage is 67%, so the schema already documents most parameters. The description adds valuable interpretation for the all parameter ('real answer rather than a gap') and gives model context for q/industry, but it does not add meaning for page, limit, or context beyond the schema. This is acceptable but not exceptional.

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 'START HERE for what can a business do with these APIs' and then defines the exact resource: a business-capability model with 333 capabilities across 28 industries and per-capability provider counts. This is a specific verb-plus-resource statement that clearly separates it from detail-lookup siblings like get_capability or get_provider_capabilities.

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 'START HERE' instruction gives clear context: use this tool as the entry point for capability questions, and the all=true guidance explains how to include zero-coverage capabilities. However, it never names alternatives or states when not to use it, so it stops short of full exclusion/alternative guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds behavior about the include=['content'] inlining bodies, which is useful. But it doesn't describe return format, pagination, or any side effects—though for a read-only tool, this is acceptable. The description doesn't contradict annotations.

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

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

Two sentences, no fluff. The first sentence states the resource and core filters, the second points to the alternative. Information is front-loaded and every word 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?

Given 11 parameters and no output schema, the description is adequate but not exhaustive. It covers the main intent and the include behavior, and the schema documents the rest. However, it doesn't describe the return structure or any nuance about how filters interact (e.g., match=any/all), which could be relevant. It's complete enough for a basic call but not for advanced usage.

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

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

Schema coverage is 55%, and the description mentions q, tags, providers, and include, but only summarizes them without adding deeper meaning beyond what the schema already provides for q and tags. The include behavior is clarified, which is a plus. However, parameters like page, sort, match, context, version, and protocol are not touched in the description, so it doesn't 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 states a specific verb ('find') and resource ('AsyncAPI event channels'), and clarifies it's for individual topics/streams. It also differentiates from find_artifacts by naming the alternative for cross-type search, so an agent can immediately tell which tool fits.

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

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

It explicitly names find_artifacts as the alternative for cross-type search, which is a clear when-not-to-use signal. It also mentions the key filters (q/tags/providers) and the include option, giving enough context for typical usage. However, it doesn't enumerate other find_* siblings or state exclusions beyond find_artifacts.

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

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

Annotations already mark readOnlyHint: true, and the description adds significant behavioral detail: pricing per result, a cap, inclusion in specific plans, and the 'context' parameter is explicitly stated as never used in ranking and only read on wrong results. This goes well beyond the annotations and gives the agent a fuller picture of costs and 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 dense two-sentence block, but every clause carries weight: purpose, filters, next steps, pricing, and a pointer to estimation. It's slightly long but not padded; the front-loading of 'START HERE' is effective. A 4 reflects that it is well-structured though not perfectly laconic.

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 7 parameters and no output schema, the description covers purpose, usage, filters, pricing, and follow-up calls. It doesn't explicitly state the return format (though 'browsable index' implies a list) or pagination semantics, but these are standard and not critical given the richness of the rest. It feels complete enough for correct invocation.

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

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

Schema coverage is 71%, so the schema describes most parameters. The description adds a summary of filter options ('by kind, minimum population, or promotion tier') but does not clarify standard pagination parameters (page, limit) or the context parameter, which remains under-explained. It adds minimal value beyond what the schema already provides, so a 3 is appropriate.

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

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

The description opens with 'START HERE for market-level questions' and specifies exactly what the tool does: 'Every scored population of providers in the catalog — tags, industries, regions, areas and VC portfolios — as one browsable index.' It clearly distinguishes it from siblings like cohort_stats and cohort_rankings by positioning it as the entry point and listing the next calls to make.

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

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

Explicitly tells the agent when to use it: 'START HERE for market-level questions' and then directs to 'call cohort_stats for the distribution, cohort_rankings for the leaderboard.' It also provides pricing context and a reference to an estimate endpoint, giving clear conditions for when this tool is appropriate versus alternatives.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds useful behavioral context about 'include=["content"] inlines bodies,' but does not discuss pagination, return format, or error behavior. This is similar to the get_calls calibration example where annotations carry the core safety information and the description adds a scoping detail but not a full behavioral profile.

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

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

The description is four short, information-dense sentences with no filler. It front-loads the core purpose and then quickly covers filters, behavior, and the alternative. 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 9 optional parameters and no output schema, the description gives the essential search/filter guidance but leaves gaps around pagination, sort behavior, and result structure. It is adequate for simple use but not fully complete; agents may need to inspect the schema or make assumptions about response format.

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 does clarify the main filters (q, tags, providers) and the special behavior of include=["content"], which adds value. However, it omits semantics for page, limit, sort, match, and context, which are either undocumented or only partially documented in the schema. It partially compensates but does not fully cover the parameter space.

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

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

The description names a specific resource ('Postman / Open collections') and clarifies they are runnable request collections. It also explicitly differentiates from the sibling tool find_artifacts, saying 'Use find_artifacts for cross-type search,' which makes the tool's scope 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?

It provides clear guidance on when to use this tool (when searching for runnable collections) and when not to (cross-type searches should use find_artifacts). The filter capabilities are summarized, giving an agent enough context to decide between this and the many sibling find_* tools.

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

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

Annotations only provide readOnlyHint=true, so the description carries most behavioral disclosure. It adds meaningful traits: pricing per request and per record, a request cap, plan inclusion, matching across all rosters, and a pointer to estimate pricing. It does not add potential caveats like result ordering or response shape, but the added detail is substantial.

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

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

The description is dense but each sentence adds value: purpose, industry vocabulary disambiguation, and pricing/plan guidance. It is front-loaded with the core purpose before cost details. Slightly heavy on pricing specifics, but still economically written for the information conveyed.

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 browse/list tool with no required parameters and no output schema, the description gives enough to invoke it correctly: what it returns conceptually (profiled companies ranked by technology-readiness), how to filter, and cost behavior. It does not describe the exact response fields, but that is unlikely to block correct invocation.

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

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

Schema description coverage is only 20% (only `context` is described), so the description must compensate. It does explain `q` as name search and `industry` as an insights industry name with a specific example and vocabulary warning. Page and limit are not described but their schema defaults/max are self-evident. Overall, it adds meaning where it matters most.

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

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

Description states a specific verb ('Browse') and resource ('profiled companies (Fortune 1000)'), with clear filtering dimensions (name or industry) and ranking ('ranked by overall technology-readiness signal'). It also distinguishes itself from find_providers by explicitly calling out the different industry vocabulary, so an agent can tell them apart.

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

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

The description gives concrete context: industry must come from insights_industries, not the catalog slugs used by find_providers, and it matches all rosters a company sits on. It also mentions pricing, plan inclusion, and where to estimate cost. It does not explicitly contrast with get_company_insight, but the usage context is clear enough for selection.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds a valuable behavioral caveat: 'Membership is derived and known to be partial: read a count as a floor, not a census.' This is beyond annotations and informs how to interpret results. No contradiction. Could mention pagination but not necessary for a browse 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?

Two sentences with no fluff. The first sentence establishes purpose and sibling context; the second gives usage and the critical caveat. Well front-loaded, efficient, and every clause earns its place. Slightly dense but appropriate.

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 browse/search tool with 6 parameters and no output schema, the description covers purpose, usage context, sibling differentiation, and the partial-data caveat. It does not describe the return format or pagination behavior, but these are less critical for a read-only search tool. The annotation covers read-only nature. Overall complete enough for an agent to invoke correctly.

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

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

Schema description coverage is low (33%), with only `type` and `context` described. The description compensates partially by explaining 'Search by text' (maps to `q`) and 'sort by provider count' (maps to `sort`). It does not clarify `page` or `limit`, but these are standard and self-explanatory. Given the low coverage, the description adds some meaning but not complete 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?

States a specific verb ('Browse'), resource ('the country dimension'), and a clear use case ('who is in Germany'). Explicitly distinguishes from siblings by naming find_industries / find_regions / find_areas and positioning this as the finest taxonomy and the one a buyer names. Purpose is unambiguous and differentiates from sibling tools without opening 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?

Gives clear context for when to use ('the one a buyer usually names') and names the peer tools as alternatives. Does not explicitly state when NOT to use or provide exclusion conditions, but the context is strong enough for an agent to infer the right choice. No misleading guidance.

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

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

Annotations already declare readOnlyHint=true,Skip and the description adds useful non-obvious context about the aggregation concept and ranking by member count. However,Skip it does not disclose the return shape,Skip pagination behavior,Skip or how q affects results,Skip so the behavioral picture is only partially filled in.

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

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

The description is three tight sentences: concept,Skip concrete examples,Skip ranking behavior,Skip and a targeted use case. Every sentence earns its place and the most important framing 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?

There is no output schema,Skip so the description must carry information about what the caller gets back,Skip but it never describes the result fields or list structure. It also leaves q,Skip page,Skip and limit semantics mostly implied rather than stated. For a 4-parameter tool with no output schema,Skip these are meaningful 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 25% and only the context parameter is documented in the schema. The description implies q relates to slugs ('two slugs look like separate vendors') but never explicitly explains q,Skip page,Skip or limit semantics. With such low schema coverage,Skip the description needed to compensate and did 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 defines an 'estate' as one company spread across multiple provider records)Skip and gives concrete examples (Amazon 237, Salesforce 27, Cisco 37). It states the tool browses these ranked by member count)Skip but it does not explicitly name or contrast sibling tools like get_estate or find_providers,Skip so it stops short of full sibling differentiation.

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

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

The description includes an explicit use case: 'Use this when two slugs look like separate vendors and you need to know whether they are one company.' This gives a clear when-to-use signal,Skip but it does not mention when not to use it or name alternatives,Skip leaving some guideline value on the table.

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

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

Annotations include readOnlyHint=true, which already discloses that this is a safe read operation. The description adds useful behavioral context: examples are 'real request/response' and include=['content'] 'inlines bodies'. However, it does not describe pagination, output shape, or what happens when no examples match, which would strengthen transparency.

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

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

Three sentences, each with a distinct job: state the resource, list key filtering/behavior, and route to the 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?

For a read-only search tool with no output schema, the description is largely sufficient: it names the domain, the main filters, a key include behavior, and the sibling to use for broader search. It could be more complete by hinting at pagination or sort defaults, but those are partially covered by the input schema and the tool's simple read-only nature.

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 carries some responsibility for parameter meaning. It usefully names q, tags, and providers as filters and explains that include=['content'] inlines bodies, which goes beyond the schema. However, it omits guidance for page, limit, match, and sort, leaving meaningful gaps for a 9-parameter tool.

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 ('example payloads across the catalog') and its distinctive value ('Real request/response examples'). It also explicitly names find_artifacts as the alternative for cross-type search, so an agent can distinguish this tool from the large sibling family.

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

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

The description provides concrete filtering guidance ('Filter by q / tags / providers') and points to find_artifacts for cross-type search, which serves as an explicit alternative. It does not go into depth about when to prefer examples over other find_* tools, but the key alternative route is clearly stated.

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

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

Annotations carry readOnlyHint=true, so the safety profile is already established. The description adds context about what data it covers (x- extensions catalog-wide) and what dimensions it returns (publisher, document count, location, value shape), but it does not disclose pagination behavior, result ordering beyond 'sort', or whether search matches keys, purposes, or both. It discloses the provenance aspect that the OpenAPI Initiative registry lacks, which is useful context beyond annotations.

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

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

Two sentences, front-loaded with the core value proposition, followed by concrete search/sort affordances. Every sentence earns its place 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?

For an opinionated read-only search tool, the description is strong: it defines scope, distinguishes from a registry, lists the added provenance fields, and states search/sort capabilities. No output schema exists, so a sentence about result format/pagination would make it complete; the slight absence of search-behavior detail keeps it from a 5.

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

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

Schema description coverage is only 20% — only the 'context' parameter is described in the schema. The description does not explain what 'q' accepts, what values 'sort' takes, or what pagination params mean. Baseline 3 is appropriate because the parameter names are semi-self-explanatory, but the description does not compensate for the 80% undocumented schema. It does add semantic context: 'Search by key or purpose; sort by occurrences' maps loosely to q and sort, which helps.

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 is precise: 'Browse every OpenAPI x- specification extension harvested across the catalog...' It clearly identifies the resource (OpenAPI x- extensions), the action (browse/search), and what makes this tool distinct from the sibling get_extension — a catalog-wide aggregate with provenance rather than a single extension lookup.

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

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

The description implies a search/browse use case with 'Search by key or purpose; sort by occurrences.' It contrasts with the OpenAPI Initiative registry to position its unique value. However, it does not explicitly say when to prefer this over get_extension or find_openapis; the browser-like framing is clear context but lacks direct exclusion/alternative guidance.

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

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

Annotations already mark readOnlyHint=true, so the safety profile is covered. The description adds the behavior that include=['content'] inlines bodies, which is useful operational context. No contradiction; it goes beyond annotations by explaining the metering/billing scope and the inline option.

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

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

Two sentences with no fluff. The core purpose is front-loaded, followed by key filtering options and the sibling alternative. Every clause adds value; it is concise and well-structured.

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 search tool with no output schema, the description is relatively thin. It covers the domain and the include option but does not mention pagination (page/limit), match semantics, or what the return structure looks like. Given the readOnly annotation and simplicity of the tool, it is adequate but not fully 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 50% (5 of 10 params have descriptions). The description partially compensates by mentioning q, tags, providers, and include, but it does not clarify page, limit, match, or context beyond what the schema already says. For instance, it says 'Filter by q / tags / providers' which gives some meaning to providers but leaves pagination and match semantics unexplained.

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

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

The description states the resource domain ('FinOps / billing models across the catalog') and the action is implied by the tool name 'find'. It also explains the purpose ('How usage is metered and billed') and notes a distinguishing alternative ('Use find_artifacts for cross-type search'), though it doesn't differentiate from other find_* siblings like find_apis or 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 explicitly tells the agent to use find_artifacts for cross-type search, providing one exclusion. However, it does not specify when to prefer this tool over other domain-specific find_* tools (e.g., find_apis, find_providers), nor does it give context about when billing-model search is appropriate versus alternatives.

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

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

Annotations provide readOnlyHint=true, so safety is covered. The description adds behavioral context beyond that: the include=['content'] parameter 'inlines bodies' and the scoping to 'across the catalog'. It does not mention pagination, sort behavior, or match semantics, but these are less critical for a read-only 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?

Three short sentences, each earning its place: scope, filter/inlining behavior, and alternative routing. No fluff or repetition of schema defaults. Front-loads the resource and catalog scope.

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 9 parameters und no output schema, the description is adequate for basic calls but leaves gaps: no explanation of providers semantics, match any/all, pagination, or what the returned objects contain. The explicit cross-type alternative helps, but an agent would need to infer or inspect the schema for several parameters.

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

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

Schema description coverage is low (44%), so the description must compensate. It adds meaning for include (inlines bodies) and lists providers as a filter, but does not explain providers' value semantics, match any/all, page/limit behavior, or output format. The schema already documents q, sort, and tags well, so the description fills some gaps but not all.

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 and scope ('GraphQL schemas across the catalog', 'GraphQL type systems') and distinguishes from 'find_artifacts for cross-type search'. It lacks an explicit verb like 'search', relying on the tool name and title, so it is clear but not a fully self-contained statement.

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

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

Explicitly names an alternative for a specific condition: 'Use find_artifacts for cross-type search.' It also gives concrete filtering instructions (q / tags / providers, include content). It does not compare against other find_* siblings like find_openapis or find_apis, so the guidance is partial but useful.

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

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

The readOnlyHint annotation already establishes this as a safe read operation. The description adds some behavioral context by mentioning sortability by provider/API count, but it does not disclose pagination behavior, default ordering, or what the returned items look like. It does not contradict the annotations.

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

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

The description is a single, front-loaded sentence that communicates the core action and a key capability without waste. However, it is so terse that it omits useful operational details, so it falls short of a perfect score for structure.

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 five parameters, no required fields, and no output schema, this description is not complete enough for an agent to invoke the tool confidently. It does not explain what q does, how sorting works, whether results are paginated, or what the response structure is. The description covers only the basic browsing idea.

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%, and most parameters (q, page, sort, limit) lack descriptions in the schema. The description only hints at sorting by provider/API count, which partially explains the sort parameter, but it does not clarify q search semantics, pagination, limits, or valid sort values. The description fails to 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 uses a specific verb ('Browse') and resource ('industry verticals'), and adds a meaningful capability ('sort by provider/API count'). It clearly indicates this is a list/browse tool rather than a detail or analytics tool, though it does not explicitly differentiate it from similar sibling tools like insights_industries or get_industry_leaders.

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 about when to use find_industries versus alternatives such as get_industry, get_industry_leaders, or insights_industries. The description implies use for browsing and sorting, but does not state exclusions, prerequisites, or when another tool would be more 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?

Annotations only state readOnlyHint=true; the description adds meaningful context about the free count vs. the paid named-firms result and the Understanding requirement. However, it does not disclose return shape, pagination, or behavior on unknown slugs, so behavioral transparency is 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?

The description is compact and starts with the core purpose before moving to pricing and entitlement details. Every sentence carries useful information, though the repeated 'UNDERSTANDING' branding and pricing URI add minor noise for an agent primarily deciding what the tool does.

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-parameter read-only lookup, the description gives enough to invoke the tool: pass a provider/company slug to get backing VC firms. However, there is no output schema and no description of the response format, empty-result behavior, or error cases, leaving some ambiguity.

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 leaves 'slug' undocumented, and the description compensates by identifying it as the provider/company slug. The 'context' parameter is already well described in the schema, so the description adds fair but not complete parameter-level value given 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 states the tool's purpose: it returns which VC firms back a given provider/company identified by slug. The phrase 'reverse portfolio edge' hints at how it differs from portfolio-oriented siblings, though it does not explicitly name those 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 explains pricing and entitlement conditions but not when to choose this tool over siblings like find_vcs, vc_portfolio, or get_vc. An agent must infer the use case from the phrase 'reverse portfolio edge' rather than receiving explicit when-to-use or when-not-to-use 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?

readOnlyHint=true covers the safety profile, and the description adds one behavioral detail: include=['content'] inlines bodies. However, it does not disclose response shape, pagination behavior, or whether `content` is excluded by default. This is acceptable 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 short sentences carry purpose, filters, an inclusion behavior, and a sibling pointer with no filler. The most important facts are front-loaded.

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

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

For a read-only, no-required-parameter search tool, the description provides the essential domain, filters, include behavior, and sibling fallback. The schema supplies defaults/enums. It stops short of describing the return shape, but nothing critical blocks correct invocation.

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

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

Schema description coverage is only 44%, so the description must compensate. It adds meaning for include (inlines bodies) and names providers/tags as filters, but leaves page, limit, match, and context semantics to their schema defaults; it does not fully fill 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 names a concrete resource ('JSON-LD contexts') and scope ('across the catalog'), and the title reinforces the 'find' verb. It also explicitly distinguishes itself from find_artifacts, so an agent can select it without opening 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 tells the agent the available filter dimensions (q, tags, providers) and when to escalate to a sibling ('Use find_artifacts for cross-type search'). This gives both usage context and an explicit alternative.

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

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

Annotations declare readOnlyHint=true, and the description adds that include=['content'] inlines bodies, which is a behavioral detail not in the schema. It doesn't contradict annotations and discloses the key filtering behavior.

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

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

Two sentences with no fluff. The resource type is front-loaded, and the alternative is stated efficiently. Every clause adds value.

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

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

For a 9-parameter tool with no output schema and low schema coverage, the description covers the essential filtering and the inline behavior but omits pagination, sorting, match semantics, and return format. These are left to the schema, which is incomplete for several params. It's adequate but not fully complete.

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

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

Schema coverage is low (44%), and the description mentions only q, tags, providers, and include. It adds meaning for include (inlines bodies) but doesn't explain page, limit, match, or providers in detail. The schema descriptions for tags are oddly provider-focused, but that's not in the tool description. The description partially compensates for coverage 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 tool finds JSON Schemas, specifying 'standalone data schemas' to distinguish from schemas embedded elsewhere. It names filtering options and explicitly differentiates from find_artifacts for cross-type search, so the purpose is unambiguous.

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

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

Provides a clear alternative for cross-type search with find_artifacts, and implies this tool is for JSON schemas specifically. It doesn't explicitly mention when not to use it for other find_* variants, but the resource type makes the intended use 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?

The readOnlyHint annotation already covers safety, and the description adds behavioral detail that include=['content'] inlines bodies. This goes beyond the annotation and is useful. No contradictions found.

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

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

The description is a single, well-structured sentence that front-loads the core purpose, then lists key filters, the include option, and an alternative. 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 10-parameter tool with no output schema and many siblings, the description provides the essential purpose and a key alternative, but it omits important details like return format, pagination, and several parameter semantics (e.g., context, struct_type). It is adequate but not thorough.

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 should compensate for undocumented parameters. It adds meaning for include (inlines bodies) and clarifies that filtering by q/tags/providers is possible, but it does not explain context, struct_type, sort, match, or pagination, leaving 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 states a clear purpose: finding JSON structures (data structures behind APIs) in the catalog. It also names an alternative tool for cross-type search, which aids differentiation. However, it does not explicitly distinguish itself from similar siblings like find_json_schemas, leaving some ambiguity.

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

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

It explicitly says 'Use find_artifacts for cross-type search,' providing a clear when-not case. It also mentions filtering by q/tags/providers and the include option, which gives basic usage context. However, it lacks guidance on when to prefer this over other find_* tools beyond the single alternative.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral details: it mentions filtering by q/tags/providers, the include=['content'] option to inline bodies, and the context parameter's non-ranking, non-answering behavior. This adds value beyond annotations without contradiction.

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

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

The description is a single, dense sentence with no fluff. It front-loads the resource and scope, then lists filtering options, and closes with an alternative. Every word 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?

Given the tool has 10 parameters, no output schema, and only 50% schema coverage, the description provides the core purpose and a sibling reference but omits details about pagination, match semantics, and output format. It is adequate for a simple search tool but not fully 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 50%, and the description adds some meaning by highlighting key filters (q, tags, providers) and the include parameter's 'inlines bodies' behavior. However, it does not compensate for the undocumented parameters (page, limit, match, providers) beyond a brief mention. It partially bridges the gap but not fully.

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 finds MCP servers across the catalog, with a specific resource and scope. It also distinguishes itself from a sibling tool ('Use find_artifacts for cross-type search'), making its purpose 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?

It explicitly names find_artifacts as the alternative for cross-type search, giving a clear usage boundary. However, it does not contrast with other find_* tools (e.g., find_providers, find_apis), leaving some implicit context. The overall usage is clear from the domain and 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?

Annotations provide readOnlyHint=true, so the safety profile is covered. The description adds that include=['content'] inlines bodies, implying default returns metadata without bodies. It does not describe pagination, response shape, or default ordering, but given the annotation covers the mutation risk, the extra context 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?

Two sentences with no filler. The purpose is front-loaded, and the key differentiators (get_openapi, find_artifacts) are mentioned efficiently. Every sentence contributes 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?

With 9 parameters, none required, and no output schema, the description is too sparse. It does not specify what the response contains (list of spec metadata? URLs?), pagination defaults, or how parameters like match and sort interact. An agent would have to guess the return format, which is risky for correct invocation.

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

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

Schema coverage is 44%, and the description compensates partially by explaining that q, tags, providers are filters and include inlines content. However, it does not explain page, limit, sort, match, or context beyond what the schema already states. The description adds some value (especially the include behavior) but does not fully cover the 56% 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 clearly states the tool lists OpenAPI specifications across the catalog, and distinguishes it from get_openapi (single spec) and find_artifacts (cross-type search). The verb 'find' plus resource 'OpenAPI' and scoping is specific and immediately distinguishable from many siblings.

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

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

It explicitly tells the agent to use find_artifacts for cross-type search and implies get_openapi for a single spec. This covers two key alternatives, though it doesn't address other find_* tools like find_apis or find_asyncapis. Still, the guidance is concrete and actionable for the most likely confusions.

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 only a readOnlyHint annotation, the description carries the behavioral disclosure burden and exceeds it: it explains segment matching semantics, one-row-per-operation deduplication, spec splitting across tags, the `apis` list field, `max_providers` cap and truncation flag (`meta.query.truncated`), plus detailed pricing and estimate guidance. This is far beyond what annotations provide.

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

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

The description front-loads the purpose immediately, then delivers dense, high-value behavioral details with zero fluff. Every sentence adds essential information (matching semantics, deduplication, truncation, pricing), making the length justified.

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

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

Given the tool's complexity (7 params, no output schema), the description covers query semantics, filtering, deduplication, truncation, and pricing. It leaves the exact response shape (operation fields list) unspecified, but it does mention `apis` and `meta.query.truncated`, giving enough for an agent to interpret results. A brief output-structure sentence would make it fully 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 57%, and the description compensates well for the undocumented parameters: it explains `method` (not described in schema), reinforces `q` with segment semantics, and adds context to `deprecated` and `max_providers`. `page` and `limit` remain unexplained, but they are standard pagination parameters and the description covers the most important ones.

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: catalog-wide operation search matching path segments. It clearly distinguishes itself from tag-based searches ('tags are what a company says about itself, a path is what its API accepts') and implies it answers questions no other sibling tool could ('had no answer before this').

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 on when to use the tool: to find which providers expose a specific API path, narrowable by method and deprecation status. It implies a contrast with tag-based search, but does not explicitly name sibling tools or state when not to use this tool (e.g., 'for per-provider operations use get_provider_operations').

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds the 'include=["content"] inlines bodies' behavior, which is useful context beyond the schema. It doesn't mention pagination, sorting defaults, or return format, but these are either in schema or not critical for a read-only search tool. No contradiction with annotations.

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

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

Four short sentences, front-loaded with purpose, then filtering guidance, then an alternative. Every sentence earns its place; no filler or repetition. Efficient and well-structured.

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 9 parameters and no output schema, the description covers the core purpose, key filtering options, and the primary alternative. It doesn't explain the return format, but that's a minor gap for a tool that likely returns a list of plans. Given the annotations and schema defaults, it is reasonably complete for an agent to invoke correctly.

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

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

Schema coverage is 44% (<50%), so the description must compensate for undocumented params. It explains q, tags, providers, and include via the filtering sentence, adding meaning beyond the schema for those. However, page, limit, and match are not addressed in the description, leaving them under-explained. The context param is documented in the schema itself. It partially compensates but not fully.

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

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

States a specific verb (find) and resource (pricing plans), clarifies scope ('across the catalog', 'An API's pricing tiers'), and distinguishes itself from find_artifacts by naming it as an alternative. The purpose is unambiguous and differentiates from siblings without opening 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?

Explicitly names find_artifacts for cross-type search, giving a clear when-not-to-use condition. However, it doesn't elaborate on when to prefer this over other find_* tools like find_apis or find_providers, though the specific scope (pricing plans) implicitly guides selection. No prerequisites or exclusions beyond the one alternative are mentioned.

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

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

Annotations already mark readOnlyHint=true. The description adds useful behavioral context: results are 'by reference' and include=['content'] inlines bodies, so the agent understands default vs enriched responses. It doesn't discuss pagination, but that is partly covered by schema defaults.

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

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

The description is short and front-loads the core scope. The first two sentences are slightly redundant ('Postman collections' vs 'Postman-format collections'), but overall every clause earns its place and the sibling routing is efficiently packed.

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 9 parameters and no output schema, the description covers purpose, filter dimensions, inlining behavior, and the key sibling alternative. It omits match semantics, pagination behavior, and any return-shape expectations, making it adequate but not fully 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 low (44%), so the description must compensate. It partially does by naming q/tags/providers as filters and explaining include semantics ('inlines bodies'). However, it leaves match, page, limit, and the exact meaning of providers undocumented in both the 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 the resource ('Postman collections'), the catalog-wide scope, and the Postman-specific format ('Postman-format collections (by reference)'). It also explicitly contrasts with find_artifacts, so an agent can distinguish this tool from a sibling without opening schemas.

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