agentery

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

With no annotations provided, the description fully discloses behavior: exact-match resolution ('NEVER silently swapped for a fuzzy match'), edge cases for one or zero valid inputs, mixed_provider_types warnings, and the meaning of reported_success (null until 5+ distinct correlated reporters in 90 days). This is exceptionally transparent.

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

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

The description is a single dense paragraph with many clauses, semicolons, and parentheticals, making it hard to scan. Key output details are buried mid-paragraph. While every sentence carries technical importance, the lack of bullet points or front-loading hurts cognitive parsing for an agent.

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 there is no output schema, the description thoroughly covers return structure: cards with observed price, community upvotes, provider type, how_to_connect object, reported_success, and specific comparison_status values. It also addresses edge cases and follow-up actions (report outcome), making it highly complete for invocation.

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

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

The input schema covers provider_ids at 100%, but the description adds critical details: accepted aliases ('handles, ids') and that a comma-separated string is also accepted. This goes beyond the schema's array type and improves invocation flexibility.

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 directive: 'Call this to decide between shortlisted providers.' It further specifies the output as 'Full evidence-scored cards for 2-6 handles side by side,' distinguishing it from single-provider tools like get_provider and from search/research tools like search_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?

The description explicitly states it should be used after search_providers or research_capability, and notes when inline suggested_alternatives will appear. It does not explicitly exclude scenarios like querying a single provider, but the workflow context is clear enough.

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

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

With no annotations provided, the description carries the full disclosure burden and excels: it reveals the private nature, no-account requirement, one-time secret benchmark_id (store it, it's your only key), ambiguous-name resolution behavior, blocking on unresolved inputs unless allow_partial, and immutability of underlying data. This far exceeds baseline expectations.

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

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

The description is information-dense yet well-structured: front-loaded purpose, then mode breakdown, security note, downstream usage, resolution behavior, and data guarantees. Every clause adds critical operational knowledge without redundancy or 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?

Given the tool has 6 optional parameters and no output schema, the description fully compensates by explaining the return value (benchmark_id token), both creation modes, error handling for ambiguous names, partial-degenerate behavior, and post-creation usage. Nothing essential is left to guesswork.

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?

Although schema coverage is 100%, the description adds significant semantic value beyond field names: it explains how `members` accepts exact handles or resolvable product names/domains, how `base_niche`/`remove`/`add` work together in Mode B, and the exact effect of `allow_partial`. This clarifies parameter relationships and edge cases not evident from the schema.

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

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

The description opens with a specific verb and resource: 'Create a PRIVATE custom benchmark (a saved, calculated peer cohort)' and then details two distinct creation modes (explicit members vs. forking a niche). This clearly differentiates it from sibling lifecycle tools like get_custom_benchmark, update_custom_benchmark, and delete_custom_benchmark.

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 describes two modes (A and B) and when to use each, and notes downstream usage with other tools (get/update/delete, market_report, etc.). It lacks a direct 'when not to use' statement, but the mode guidance and mention of alternatives like fork vs. explicit membership provide sufficient 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?

With no annotations, the description carries full burden. It discloses that only a minimal audit record is kept and no underlying data is touched, providing useful behavioral context beyond the tool name.

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

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

Two concise sentences: the first states purpose, the second adds behavioral nuance and parameter instruction. No extraneous 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 single-parameter tool with no output schema, the description covers purpose, side effects, and parameter. It could mention reversibility or error states, but overall it is sufficiently complete.

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

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

Schema coverage is 100% and the schema describes 'benchmark_id' as 'Your cb_ token'. The description merely repeats 'Pass benchmark_id', adding no additional meaning beyond the schema.

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

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

The description uses a specific verb 'disable access' and resource 'custom benchmark', clearly distinguishing it from sibling tools like create, get, and update. The purpose is immediately clear.

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

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

The description implies usage for disabling a benchmark, but does not explicitly state when to use this tool versus alternatives. No exclusion criteria or context is provided, only a simple instruction to pass the ID.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It explains that results are aggregated and ranked by miss count and that empty args return the current ranked list. However, it does not explicitly mention whether this is a read-only operation or any potential side effects, leaving slight ambiguity. Still, the described behavior is transparent enough for a simple query tool, so a 3 is appropriate.

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

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

The description is two sentences long, front-loaded with the primary purpose, and every clause contributes value. It avoids unnecessary detail, states the output type, and gives a pairing recommendation without waste. This 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?

Given the tool's simplicity (one optional parameter, no output schema), the description adequately explains the return concept (zero-result queries ranked by miss count) and the default invocation. It does not detail the exact fields of the returned list, but for a read-only ranked list this is sufficient for an agent to use correctly. It could be slightly more explicit about output structure, hence 4.

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

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

Schema coverage is 100% for the single 'limit' parameter, so the baseline is 3. The description adds meaningful extra semantics by specifying that empty args ({}) return the current ranked list, which is not evident from the schema alone. This supplements the schema's default value hint and clarifies the zero-parameter invocation behavior, justifying a 4.

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

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

The description clearly states a specific verb+resource: 'see what providers are being SEARCHED FOR but don't exist yet' and defines the core concept as capability queries returning zero results. It distinguishes this from sibling tools by focusing on unmet demand signals and explicitly references complementary tools (market_report/market_gaps), making the purpose unmistakable.

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

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

The description provides clear context on when to use: to surface live unmet demand for founders and investors. It suggests pairing with market_report/market_gaps to size gaps, which implies complementary usage but does not explicitly list when-not-to-use or direct alternatives. This is clear context without explicit exclusions, earning a 4.

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

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

No annotations are provided, so the description carries full behavioral burden. It discloses read-only status, stripping of pricing-intent boilerplate, the canonical pricing engine, and the withholding of pricing when match_certainty is 'uncertain'. This is rich behavioral context beyond a simple 'read-only' flag.

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 lengthy but information-dense. Every clause earns its place (output fields, pricing behavior, alias, sibling pointer). It's structured in a readable stream, though a few bundled clauses could be split for scanning. Not overly verbose given the tool's complexity.

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

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

With no output schema and no annotations, the description must explain return values, and it does: market label, counts, nearest, pricing_by_tier with statistical details, match_certainty behavior. It also explains canonical pricing and read-only nature. This is a complete picture for selecting the tool.

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

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

Schema description coverage is 100% – both task and query parameters already have clear descriptions with an example. The description adds the alias relationship (query, q), though 'q' is not present in the schema, which is a slight inconsistency. Still, the schema alone suffices; description adds marginal value.

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

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

The description uses a specific verb ('Map') and clearly identifies the resource ('live MARKET' – semantic neighbourhood of providers). It states the core function unambiguously and differentiates from the sibling research_capability by noting that tool covers a full market read + shortlist in one call.

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 explicit contexts: buyers, sellers, or sizing a space. Names research_capability as an alternative for a fuller combined call, giving a clear when-to-use-it-instead. It doesn't enumerate exclusions for all 18 siblings, but gives enough direction for typical use.

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

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

With no annotations, the description carries full burden. It discloses important behavioral traits: stats only shown when ≥3 comparable members, pricing never blended, and includes cohort breakdowns. Missing details on auth requirements or error handling, but the token requirement is mentioned.

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

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

The description is a single sentence that front-loads the main purpose. It is information-dense but slightly cluttered with parenthetical details. Efficient overall, though could be slightly more streamlined.

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

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

Given no output schema and four parameters, the description covers the report's contents thoroughly, including conditional stats. It lacks explicit mention of the return format but compensates with specific details about what the report contains. Nearly complete for the complexity level.

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%, providing a baseline of 3. The description adds value by explaining that benchmark_id is a 'cb_ token' and clarifying the as_of parameter's usage ('reproduce exact stats'). It does not fully repeat schema but provides contextual nuance beyond parameter descriptions.

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

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

The description clearly identifies the tool's purpose: retrieving a private custom benchmark's current report, and enumerates the exact contents (members, stats, cohorts, historical index, data coverage). It effectively distinguishes from sibling tools like create_custom_benchmark or delete_custom_benchmark.

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

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

The description implies usage context (for viewing a report) but does not explicitly state when to use this tool versus alternatives like price_benchmark or get_price_index. No exclusions or 'when not to use' guidance is provided.

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

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

With no annotations, the description carries the transparency burden. It discloses that the tool reads the same canonical series as the /aepi page, returns an index rather than a market price, and outlines the returned fields. It does not explicitly state there are no side effects, but the read-only nature is strongly implied.

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

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

The description is longer than minimal, but every sentence adds value: it explains what is returned, how the index is constructed, and how to choose among filters. It is front-loaded with the primary purpose, so it is efficiently 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?

Since there is no output schema, the description fully documents return values (change_1d/change_7d/change_30d, as_of, pair count, status, methodology version, plus tier breakdowns) and the meaning of each filter. This is comprehensive for a tool of this complexity.

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

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

Schema coverage is 100% and all three schema params have descriptions. The description adds context for provider_type and response_mode, but it also references a benchmark_id parameter that is not present in the input schema, which could mislead an agent. This inconsistency prevents a higher score.

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 'Call this for the CURRENT level of the Agent Economy Price Index (AEPI)' – a specific verb, resource, and scope. It clearly distinguishes from get_price_index_history by emphasizing 'current' and from market_report/price_benchmark by stating those are for capability-specific pricing.

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 explicit guidance on when to use and when not to: 'The economy index is whole-market by design — for pricing on a specific capability use market_report or price_benchmark.' It also explains when to use provider_type ('an MCP buyer should read the mcp index') and the role of response_mode.

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

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

With no annotations, the description does the heavy lifting. It honestly discloses that points are index levels (base 100) never prices, that insufficient data returns an honest status rather than a fabricated series, and that summary/full modes differ. Minor omission: no explicit statement about side effects or permissions, but the read-only nature is strongly implied, so this is not a serious gap.

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

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

The description is longer than average but each sentence carries information: defaults, distinctions, alternative tools, and behavioral caveats. It is well-structured with clear clauses, though it could be trimmed slightly—e.g., the benchmark_id note feels appended but is still relevant.

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

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

Given no output schema, the description adequately explains the return content (date + index_level, window change, gap flags) and the insufficient_history status. It does not fully define 'gap flags' or return format, but for a history-retrieval tool this is reasonably complete, especially with the alternative-tool 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?

Although schema covers all four parameters, the description adds significant meaning: 'team' = Team/SME, provider_type returns a standalone series with its own base 100, and response_mode 'summary' returns date+index_level plus window change while 'full' adds gap flags. It also mentions a benchmark_id parameter not present in the schema, which is extra guidance.

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

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

The description clearly specifies the tool retrieves a canonical dated index series for the AEPI, distinguishing it from price-related tools. It explicitly says the series is what the /aepi page plots and contrasts with market_report or price_benchmark for capability-specific pricing.

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 states exactly when to call this tool (for charting/analysing movement) and when not to, explicitly naming alternatives: 'for pricing on a specific capability use market_report or price_benchmark.' It also explains parameter-based selection of the series (tier, provider_type, period) with defaults.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It lists the output fields and notes that the structured profile is included 'when available,' which adds transparency about conditional data. However, it does not disclose what happens if both handle and regNum are omitted, which takes precedence, or error behavior when a provider is not 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 concise sentence that front-loads the purpose ('Call this for the public directory card') and then efficiently enumerates the included data. No redundant words or information; every segment 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 simple getter with no output schema, the description adequately explains the return content and its conditionality. It lacks explicit error-handling details and interaction rules for the two parameters, but given the tool's simplicity, it covers the essential context sufficiently.

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

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

The schema already describes both parameters (handle and regNum), so baseline is 3. The description adds semantic value by explicitly stating 'by handle or registration number,' clarifying that the two parameters are alternatives rather than complementary, which is not apparent from the schema alone.

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

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

The description clearly states that the tool retrieves a public directory card for one provider, listing the included fields (bio, source URLs, X-verification status, etc.). It specifies the resource (provider) and the action (get by handle or registration number), but does not explicitly differentiate from sibling tools like get_provider_profile.

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

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

The phrase 'Call this for...' provides a direct usage context. However, it does not mention when NOT to use it or suggest alternative tools (e.g., search_providers for finding providers), leaving the when-to-use guidance implicit rather than explicit.

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

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

With no annotations provided, the description carries the full burden and excels: it discloses that fields are null when the vendor publishes no endpoint ('never guessed'), explains the reported_success threshold (5+ distinct reporters in 90 days), and details the null behavior. This is rich behavioral detail beyond the schema.

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

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

The description is long but dense and front-loaded with the purpose. Every sentence provides distinct value (field list, null policy, reported_success explanation, follow-up instruction). It is structured logically, though slightly sprawling.

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

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

There is no output schema, so the description must convey return structure. It enumerates all major fields, explains the how_to_connect object, and covers edge cases like null endpoints and reported_success. This is fully complete for a one-parameter tool.

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

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

Schema description coverage is 100% and the schema already states the provider_id is returned by search_providers or compare_providers. The tool description repeats this context but adds no new parameter-level meaning, so the baseline 3 applies.

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

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

The description uses a specific verb phrase ('drill into ONE provider') and clearly identifies the resource (a single provider profile). It also distinguishes itself from siblings by explicitly positioning it as a follow-up to search_providers or compare_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 states when to use the tool ('after search_providers or compare_providers') and provides a follow-up action ('call report_outcome afterwards'). However, it does not mention alternative tools like get_provider or specify when not to use it.

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

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

With no annotations, the description carries the full burden and succeeds: it discloses the data source (live MCP search telemetry), the computation approach (raw text-embedding, demand-first), the gap definition, return fields, and the honest behavior that few gaps appear at low volume and it sharpens with usage. This is exemplary behavioral disclosure.

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

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

The description is dense but well-structured, leading with the core purpose, then explaining the algorithm, outputs, and caveats. At roughly 80 words, it is longer than minimal but every sentence adds unique value, earning 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?

Despite lacking an output schema, the description fully enumerates return fields (demand phrasing, demand_mass, nearest_paid_similarity, etc.), covers behavioral expectations with low volume, and explains the data source and computation. This makes it highly complete for an agent to understand 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 coverage is 100%, but the description adds meaningful clarification by correcting the schema's 'Max niches' (which is inconsistent with gaps) to 'limit caps the list', and by stating no arguments are required to get a default result. This resolves ambiguity beyond the raw schema.

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

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

The description clearly states the tool finds unmet demand (market gaps) computed demand-first in raw text-embedding space, explicitly differentiating itself from niche-based tools with 'NO niches'. It also defines what constitutes a gap, making the purpose unmistakable.

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

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

The description does not name specific sibling alternatives, but the 'NO niches' clarifier steers agents away from niche-based tools, and the caveat about low query volume sets expectations for when results may be sparse. It implies usage context but lacks explicit when-to-use or when-not-to-use guidance relative to alternatives.

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

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

With no annotations provided, the description carries the full burden. It discloses the methodology (nearest providers by text embedding, no fixed niche), that all fields are measured, the exact statistics computed, and what output to expect (pricing benchmark, counts, top providers). It also mentions the 'canonical pricing engine' and accepts 'niche' as an alias. This goes beyond a generic report description, though it doesn't mention auth, rate limits, or performance.

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 with useful information and is front-loaded with purpose and method. While it is long, each sentence adds value, and it concludes with a clear sibling pointer. It loses one point for being slightly verbose and introducing jargon like 'canonical pricing engine' without elaboration.

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

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

The tool has only 2 params, no output schema, and no annotations. The description explains the methodology, the fields included, and the alias behavior. It also provides a pointer to a sibling tool for a combined use case. This is fairly complete for a single-market report tool, though it could briefly mention what triggers the response_mode difference or any prerequisites.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds semantic meaning to 'query' by explaining it as a natural-language capability or market with an example, but the schema already covers this. For 'response_mode', the description does not add beyond the schema's enum description. Overall, the description reinforces but does not significantly extend the schema.

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

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

The description clearly states the tool's purpose: 'Deep-dive ONE market before building or investing', which is a specific verb+resource. It also defines what a 'market' means in this context (semantic neighborhood via text embedding). It distinguishes from siblings by explicitly pointing to research_capability for a combined market+pricing+shortlist use case.

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 usage context ('before building or investing') and provides an explicit alternative: 'For market + pricing + a ready shortlist in one call, use research_capability.' It also explains the query input format with an example. However, it doesn't compare against other sibling tools like find_market or price_benchmark, so the guidance is 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 discloses key behaviors: semantic neighbourhood selection, separation by provider type and buyer tier, cohort statistics, and the resolved:false fallback with no fabricated figures. Since no annotations are provided, the description fully carries the burden and does so well.

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

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

The description is information-dense and every sentence contributes, but it is long and uses heavy formatting (caps, dashes) that slightly hampers readability. It is appropriately sized for the tool's complexity, though it could be streamlined.

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 six parameters, no output schema, and no annotations, the description covers input semantics, output statistics, fallback behavior, and data source consistency. It provides enough context for an agent to select and invoke the tool correctly, aside from the parameter naming discrepancy.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds aliases and cohort behavior, but it mentions 'query' and 'task' as parameters that are not present in the schema, which can mislead an agent. The added value is offset by this inconsistency.

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 provides fair-price benchmarks for a capability described in natural language, using a semantic neighbourhood approach. It distinguishes itself from siblings by emphasizing per-type/per-tier cohort separation and explicitly stating that a blended default is never used.

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

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

Provides explicit guidance on when to supply provider_type and buyer_tier, and describes the fallback behavior when neither is known. It does not name alternative tools, but the use case is clear. Minor ambiguity exists around 'pass query' versus actual schema parameters.

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

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

With no annotations, the description carries full burden. It explicitly discloses the Bearer-key requirement, that it reads analysed site profiles, never invents capabilities, and returns 'unclear' when evidence is missing. This is a high level of 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, first sentence is an imperative statement of behavior, second gives audience, third gives data-safety guarantee. 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 moderate-complexity tool with no output schema or annotations, the description adequately covers purpose, auth, return format, and behavioral constraints. It is sufficient for an agent to select and invoke.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a general mapping of business context and workflow steps to inputs, but no additional details beyond schema descriptions. Thus 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 clearly states the tool ranks provider candidates for each workflow step, with specific deliverables (match_score, match_reasons, cautions). This distinguishes it from sibling tools like search_providers and compare_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 states it is built for app builders assembling automations, providing clear context for when to use. However, it does not explicitly name alternative tools or state when not to use, 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?

With no annotations provided, the description fully carries the behavioral disclosure burden. It discloses matching rules, weighting (unmatched stored but unweighted), aggregate surfacing thresholds (5+ reporters, 90-day window), rate limit doubling, and the x-agentery-key header hashing. This is comprehensive and beyond what annotations would typically provide.

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

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

The description is dense but well-structured: it opens with a summary of purpose and benefits, then details matching rules, aggregate behavior, rate limits, and authentication. Every sentence adds unique value, and it is front-loaded with the core action.

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 6 parameters and no output schema, the description explains the tool's behavior comprehensively: how reports are matched, weighted, surfaced, and rewarded. It even mentions the reported_success aggregate representation, covering return value expectations without needing an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some contextual meaning (e.g., agent_id must come from specific retrieval tools) and clarifies the outcome enum semantics ('Did the provider accomplish the task you hired it for?'), but it does not introduce substantial new parameter-level detail beyond the schema.

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

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

The description clearly states the tool's purpose: 'report whether it worked' for a provider you used. It uses a specific verb ('report') and resource (outcome of using a provider), and it distinguishes itself from sibling tools by being the only reporting tool among search/compare/benchmark tools.

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

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

The description provides clear context for when to use the tool ('After you use a listed provider') and explains the conditions for meaningful reporting (matching to your recent retrievals within 48h). It does not name alternative tools, but no direct alternative exists among siblings, and the usage context is unambiguous.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses that retrieval is 100% nearest-neighbour by text embedding, that there is no fixed niche/category, that it reuses canonical pricing/search engines, that it does NOT run the comparison, and that `result_fingerprint` and `cached` make repeat calls cheap.

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

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

The description is longer than average but front-loaded with the key starting point and structured output list. Every sentence adds value, though some redundancy could be trimmed (e.g., aliases repeated). It remains focused and scannable.

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

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

Given no output schema, the description thoroughly explains the three main output components, mentions `suggested_alternatives`, `result_fingerprint`, and `cached`, and clarifies the workflow handoff. It is comprehensive enough for an agent to invoke the tool correctly and 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% with detailed parameter descriptions, so baseline 3 is appropriate. The description itself adds little parameter-specific meaning beyond what the schema already states (e.g., aliases are already in the schema).

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

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

The description opens with 'START HERE for provider procurement' and explicitly states the three outputs (market, pricing context, shortlist), making the tool's purpose unmistakable. It also distinguishes itself from siblings by naming lower-level tools (find_market, market_report, price_benchmark, search_providers) and compare_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 says to start here for procurement, tells the agent to use lower-level tools for finer control, and instructs to pass `compare_ready` to compare_providers once finalists are chosen. This gives clear when-to-use vs alternatives.

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

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

With no annotations, the description carries the burden and does well: it discloses ranking with match_score and match_reasons, inclusion of observed-price objects, the how_to_connect field, and error handling for unknown query keys. It also mentions that report_outcome sharpens rankings and raises rate limits, which is a meaningful system behavior. However, it doesn't explicitly state whether the operation is read-only, though 'search' strongly implies 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?

Despite being detailed, every sentence earns its place: use case, alternative, ranking, pricing filters, result fields, follow-up, and query aliases. It is front-loaded with purpose and well-structured without redundancy, with only minor repetition of the research_capability recommendation that adds a distinct nuance.

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

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

Given 7 parameters (including a nested filters object) and no output schema, the description sufficiently covers expected result fields (match_score, match_reasons, observed-price, how_to_connect), directs to get_provider_profile for full details, and explains the follow-up report_outcome. It provides enough context for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for all 7 parameters, so the baseline is 3. The description adds value by listing query aliases (q, text), explaining that unknown query keys are never silently ignored, and providing usage hints like combining max_monthly_usd/billing with price_asc sorting. These additions go slightly beyond the schema, justifying a 4.

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 'Targeted provider search when you already know roughly what you want', clearly stating the tool's verb (search) and resource (providers/directory). It distinguishes itself from research_capability for unknown markets and from get_provider_profile for full details, 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?

Explicit guidance is provided: use this when you know what you want, call research_capability first for unknown markets or for a one-call market+pricing+shortlist, and use get_provider_profile for full MCP config snippets. It also instructs to call report_outcome after using results, clarifying the follow-up workflow.

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

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

With no annotations, the description carries the full burden. It discloses the ranking method (embedding nearness), output fields (price, endpoint liveness, upvotes, how_to_connect), and the cheaper_only filter behavior (free/freemium always qualify, no-price excluded). While it doesn't explicitly state the tool is read-only, the behavior is thoroughly described.

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 paragraph but front-loaded with the trigger condition and uses semicolons and em-dashes to structure related ideas. Every sentence adds unique information, though it is slightly longer than absolutely 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?

Given no output schema and no annotations, the description fully covers the trigger, input, output contents, ranking rationale, and relationship to sibling tools. It leaves no major gap for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds aliases for agent_id ('handle, id') and clarifies when to set cheaper_only, which goes slightly beyond the schema. Limit is not expanded, but the added context justifies a 4.

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: finding substitutes for a known provider, ranked by embedding nearness to the provider's own profile. It differentiates from siblings by noting 'NO niche lookup' and explaining that alternatives are also surfaced inside research_capability and compare_providers, making its unique role explicit.

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 opens with explicit trigger conditions ('too expensive, unreachable or a poor fit') and provides exclusion guidance ('so you rarely need to call this separately'). It also gives conditional parameter advice ('Set cheaper_only to shop down from the subject's price'), making when-to-use vs alternatives very clear.

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

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

No annotations exist, so the description carries full responsibility. It discloses key behaviors: creating a new immutable version while preserving reproducibility of the previous version, and returning exact change-impact on median/quartiles/index. However, it does not mention permissions, reversibility, or rate limits.

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

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

The description is two sentences long, front-loads the primary action, and adds crucial behavioral information in the second sentence. Every word earns its place; no unnecessary content.

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

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

For a tool with 4 parameters, no output schema, and no annotations, the description covers core behavior (modification with immutability) and the nature of the return value. It lacks details on prerequisites and error conditions, but overall is sufficiently complete for its complexity.

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

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

Schema coverage is only 25% (only benchmark_id described). The description adds meaning by explaining that 'add' and 'remove' manage members and 'rename' changes the name, but it does not specify the format of member strings or provide detail on the benchmark_id token. It partially compensates for low schema coverage but leaves ambiguity.

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 actions: 'Add/remove members or rename a custom benchmark.' It identifies the specific resource type (custom benchmark) and differentiates from sibling tools like create_custom_benchmark and delete_custom_benchmark by focusing on modifications.

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

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

The description implies this tool is for modifying an existing benchmark (vs. creating or deleting), but it does not explicitly compare to siblings or specify when not to use it. The instruction 'Pass `benchmark_id`' provides basic usage guidance but no exclusions or alternative recommendations.

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