agentery

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

With no annotations, the description carries the full burden and delivers: exact-match resolution policy, no silent fuzzy swapping, three-way status outcomes for unresolved inputs, mixed-provider-type warnings, peer fallback behavior, and machine-reported success caveats. It even explains corrected_call and recovery_note fields.

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

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

The content is front-loaded with purpose and packed with valuable edge-case detail, but it is a single dense run-on paragraph with heavy parentheticals; restructuring into bullets would improve scannability. It is more exhaustive than concise.

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 no output schema, the description enumerates nearly every important output field and state: comparison_status values, unresolved_inputs, suggested_matches, corrected_call, compared_against_peers, recovery_note, mixed_provider_types, comparability_warning, reported_success, and how_to_connect. It also covers the count constraints and post-use reporting, so an agent can invoke and interpret results without guessing.

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 meaningful input semantics: provider_ids aliases ('handles, ids'), comma-separated string acceptance, and the 2–6 handle constraint tied to search_providers/market_gaps. It does not re-describe all params, but that is already covered in 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?

Opens by identifying itself as 'Step 3 of the buyer path' and states the core action: 'Side-by-side capability + plan-level prices for 2–6 providers.' It then describes 'Full evidence-scored cards for 2-6 handles side by side,' making the deliverable unambiguous and distinct from siblings like search_providers or market_gaps.

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

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

The description explicitly positions the tool in a sequence ('Step 3', 'Use after search_providers or research_capability') and mentions inline 'suggested_alternatives' for over-budget or weakly matched providers. It does not explicitly list when-not-to-use scenarios or contrast with rank_providers_for_workflow, 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?

The description discloses critical behaviors: returns a one-time secret ID, ambiguous names are not silently resolved but returned as candidates, unresolved inputs block unless allow_partial is true, and that all prices/history are computed from immutable observations (no mutation of canonical data). This is comprehensive given no annotations were provided.

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 yet information-dense, with clear structure using (A), (B), and note sections. It avoids redundancy and every sentence adds value, making it easy to parse despite its length.

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

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

Given there is no output schema, the description adequately explains the return value (one-time secret benchmark_id) and how to use it later with get/update/delete and other tools. It also covers edge cases (ambiguity, partial allowance) and ensures the user understands the tool's behavior completely.

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?

Each parameter is explained in context: members for mode A, base_niche for mode B, add/remove as optional for forking, allow_partial for partial resolution. The description adds meaning beyond the schema by clarifying the mode-specific usage and the semantics of each parameter.

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

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

The description clearly states the tool's purpose: creating a private custom benchmark (peer cohort) over Agentery's data, with explicit mention of two modes (A and B). It distinguishes from sibling tools by focusing on creation and using terms like 'PRIVATE' and 'custom', which are unique.

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 when to use the tool (to create a custom benchmark) and how to use it, including both modes with specific parameters. It also clarifies the return value and mentions that it can be used later with other tools, providing clear usage context.

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

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

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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses data limitations, what the signals do not prove, response behavior for empty results, and that the data is never sourced from search popularity, page views, or trending queries.

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?

Every sentence earns its place: the core purpose is front-loaded, caveats follow, and response semantics close it out. The description is dense but not bloated, with no filler or repetition of schema fields.

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 optional parameter and no output schema, the description explains the important empty-response contract and the nature of the returned signals. It does not detail the exact shape of a non-empty signal list, but enough is provided for correct invocation and basic interpretation.

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 fully describes the only parameter (limit: 1-50, default 20) with 100% coverage. The description adds useful invocation context for empty args but does not need to expand on parameter semantics further.

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 ('Inspect') and a precise resource: eligible zero-result or weak-match capability queries aggregated and ranked by miss count. It also separates itself from market-intelligence tools by clarifying these are limited coverage signals from Agentery's own callers, not proof of product non-existence or paying demand.

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 clear operational context: empty args return the current list, empty response means insufficient qualifying evidence, and this is explicitly not a prerequisite for choosing a product. However, it does not name or direct the agent to any alternative sibling tool, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses that pricing-intent boilerplate is stripped before matching, that match_certainty is 'confident' vs 'uncertain', that pricing is WITHHELD when nothing is close, and that the tool returns status no_match or thin_coverage with a next_step. It also states 'Read-only.' A small gap: it doesn't detail rate limits or auth, but for a read-only mapping tool the behavioral disclosure is strong.

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

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

The description is dense but every sentence earns its place: it defines the core behavior, the audience, the matching mechanism, the return fields, the certainty semantics, the alternative tool, and the failure modes. It is front-loaded with the primary purpose and scoping. It is long, but the length is justified by the tool's complexity and the absence of annotations and output schema.

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

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

Given the tool's complexity, the lack of annotations, and the absence of an output schema, the description is remarkably complete: it names the return fields (market label, provider counts, nearest, pricing_by_tier with tier names), explains match_certainty, and describes the no_match/thin_coverage statuses. It doesn't spell out the exact JSON shape of `nearest` or `pricing_by_tier`, but it provides enough for an agent to invoke the tool and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that `task` accepts natural-language plain words, gives an example ('reconcile supplier invoices'), notes that an empty call returns needs_input, and clarifies that `query` is a back-compat alias. This is useful semantic context that helps an agent construct a valid call.

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 ('Map') and a precise resource ('a natural-language task, capability or service to its live MARKET'), then defines the market as a semantic neighbourhood found by text-embedding nearness with no fixed category. It clearly distinguishes itself from siblings like research_capability and search_providers by naming them and stating the one-call 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 explicitly states when to use this tool: for buyers, sellers, or sizing a space, and names the alternative research_capability for a full market read plus shortlist in one call. It also explains the no_match/thin_coverage behavior and that it never invents a market, which helps an agent decide when this tool is appropriate.

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

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

With no annotations, the description carries 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?

There are no annotations, so the description carries full behavioral disclosure. It explains that the tool is read-oriented, returns a whole-economy headline index plus per-tier and per-provider-type series, treats standalone provider_type indices with their own base 100, and reads the same canonical series as the /aepi page so the MCP and website agree. It does not discuss access requirements or rate limits, but for a non-destructive data-read tool the behavioral context is strong.

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

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

The description is dense but front-loaded with the core purpose ('CURRENT level of AEPI') before diving into output fields and modes. Every sentence carries substantive information, though the return-field enumeration and long parenthetical make it slightly heavy. It is appropriately sized for a tool with four parameters and no output schema.

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

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

With no output schema, the description takes responsibility for explaining return values, and it enumerates the index fields, per-tier fields, provider_type variants, response_mode behavior, benchmark override, and the canonical-series guarantee. It is largely complete for correct invocation, but it does not state output formatting, field nesting, or potential parameter-combination constraints beyond what is implied in the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: response_mode 'full' adds exact sub-0.01% moves and repricing counts, provider_type returns standalone indices with their own base 100, and benchmark_id reads a private custom benchmark's current index. These clarifications help an agent choose parameter values correctly rather than merely knowing they exist.

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: 'Call this for the CURRENT level of the Agent Economy Price Index (AEPI)'. It then disambiguates the tool's domain by stating it returns an index level, not a market price or tradeable asset, and contrasts it with market_report and price_benchmark for capability-level pricing. This makes the tool's purpose and scope unmistakable, even among 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?

The description explicitly says when to use this tool (current index level), what it is not for ('not a market price or tradeable asset'), and when to use alternatives ('for pricing on a specific capability use market_report or price_benchmark'). It also gives buyer-type guidance, e.g., an MCP buyer should read the 'mcp' index and an agent buyer the 'agent' index. This provides clear operational selection criteria.

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

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

With no annotations provided, the description carries the full burden. It discloses that points are index levels, never prices; that response_mode 'summary' returns date + index_level points plus window change and 'full' adds gap flags; and that an honest 'insufficient_history' status is returned rather than a fabricated series. These are substantial behavioral traits 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 dense and front-loaded with the core purpose, followed by critical disclaimers (base 100, not price). Each clause adds value, but some statements echo schema info, such as the period enum values and benchmark_id acceptance. Overall it is efficient, but 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?

Given no output schema and no annotations, the description is remarkably complete: it explains parameter behavior, response modes, error handling, alternatives, and scope limitations. It covers everything an agent needs to decide when to call this tool and how to interpret its results. Minor omissions like authentication are likely handled at the framework 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%, so the baseline is 3. The description adds meaningful conceptual clarity beyond the schema: it explains the 'same chained like-for-like series', the distinction between tier (buyer tier) and provider_type (billing-lens series with own base 100), and that provider_type series 'cut across provider/mcp'. This goes beyond the schema's dry enum descriptions, though some details (e.g., benchmark_id) are redundant with 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: 'the canonical DATED index SERIES ... of the AEPI'. It explicitly states every point is an index level (base 100), never a price, and contrasts itself with the whole-market economy series versus specific-capability tools. This clearly distinguishes it from siblings like get_price_index (point-in-time) and market_report/price_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?

It gives explicit usage context: 'Call this for the canonical DATED index SERIES (to chart or analyse movement)'. It also provides direct alternatives and exclusions: 'The economy index is whole-market by design — for pricing on a specific capability use market_report or price_benchmark.' Additionally, it explains when to use benchmark_id for a private custom benchmark's history.

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 transparency burden. It discloses important behavior: fields are null when no vendor endpoint exists and are 'never guessed', reported_success is null until 5+ distinct correlated reporters in 90 days, and there is an expected follow-up call to report_outcome. This is substantive, though it does not mention auth or read-only guarantees.

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 tool's purpose and placement in the buyer path. The long field lists are justified because there is no output schema, but the single-paragraph wall of text makes it slightly harder to scan than ideal.

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 documents return content, null semantics, the reported_success threshold, the required prior step, and the follow-up report_outcome call. An agent has enough context to select, invoke, and interpret results 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%, and the sole parameter provider_id is already documented in the schema as the handle returned by search_providers or compare_providers. The description reinforces this provenance but adds no new semantic detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'get full profile for ONE provider' and identifies the tool as 'Step 2 of the buyer path'. It also enumerates the exact content (plans, pricing model, liveness, evidence, how_to_connect), clearly distinguishing it from search_providers, compare_providers, and get_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 says to use this tool after search_providers returns handles, and instructs the agent to call report_outcome afterwards if the listing is used. This provides clear sequencing and context, though it does not explicitly list when-not-to-use alternatives like get_provider or compare_providers.

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 of behavioral disclosure. It reveals that gaps are computed demand-first in raw text-embedding space (not fixed categories), defines what constitutes a gap (clusters far from paid providers), explicitly mentions that request counts are not buyer counts, and honestly notes that results are sparse when query volume is low and sharpen over time. This is exemplary transparency about limitations and computational methodology.

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?

Although the description is lengthy, every sentence contributes essential information: purpose, interpretation caveats, computational approach, definition of gaps, return contents, and behavior over time. It is front-loaded with the core purpose and structured logically. Minor redundancy (repeating 'not buyer counts' in different forms) slightly reduces efficiency, but overall it is well-organized and appropriately detailed for 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?

The description covers all critical aspects for correct invocation: it states the purpose, the input (no required args, limit cap), the output (demand phrasing, demand_mass, nearest_paid_similarity, closest provider, demand_queries, paid_supply counts), limitations (low volume yields few gaps), and usage precautions. There is no output schema, so the description adequately explains return values. For a tool of this complexity, the description is remarkably complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description clarifies that no arguments are required ({}), and mentions the limit caps the list, which adds a small amount of guidance beyond the schema. However, it does not elaborate on the 'rank' enum or 'sector' beyond what the schema already explains, so it does not exceed the baseline significantly.

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 specific verb ('Inspect') and resource ('query clusters with weak coverage among indexed paid providers'), and immediately differentiates it from buyer-count analysis ('research leads, not buyer counts'). It also distinguishes itself from sibling tools like demand_signals or rank_providers by focusing on gaps relative to paid providers. This makes the purpose unambiguous and distinct.

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 strong usage context: it says to use it for research leads rather than inferring buyer counts, and warns that gaps in the index do not prove gaps in the wider market. While it does not explicitly name alternative tools, it clearly advises on interpretation and when the tool is appropriate (i.e., for lead research with caution). This is more than adequate 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?

Despite no annotations, the description thoroughly discloses behavior: it explains the dynamic market definition ('semantic neighbourhood of your natural-language query'), the measured nature of every field (with specific statistical outputs: median, mean, stdev, p25/p75, min–max, n), and the pricing benchmark's architecture. It also implicitly warns that the market is not a fixed category, which is a critical behavioral nuance.

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 for the amount of content it covers. It front-loads the core action and scoping, then lists expected outputs, and ends with a parameter guidance and sibling exclusion. No wasted sentences; 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?

Given the complexity of the tool (dynamic market definition, multiple measured metrics), the description is remarkably complete. It covers what the tool does, how it's scoped, what outputs to expect, and when to use an alternative. The absence of an output schema is compensated by the description's detailed explanation of the response contents.

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 the schema already covers 100% of parameters, the description adds semantic value by clarifying the `query` parameter's role as a natural-language capability or market with concrete examples, and explicitly describes the `response_mode` effect. It doesn't add format details for response_mode beyond the enum, but it does confirm defaults, which is helpful.

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 unusually specific: it identifies a unique 'semantic neighbourhood' scoping (nearest providers by text embedding, no fixed category), names the resource (ONE market deep-dive), and clearly distinguishes from siblings like research_capability. The action ('Deep-dive ONE market') is precise with measurable outcomes listed.

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 states when to use: 'before building or investing'. Contrasts with the 'research_capability' sibling by stating that for 'market + pricing + a ready shortlist in one call, use research_capability'. This is clear guidance on when NOT to use this tool.

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

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

With no annotations, the description carries the full behavioral burden, and it delivers: it discloses that incompatible pricing units are never blended, results come from a semantic neighbourhood, the benchmark is not a quote, and it returns resolved:false without fabricating figures when nothing is close. This is unusually transparent about edge cases and output semantics.

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

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

The description is long but densely informative, covering purpose, aliases, market semantics, output statistics, interpretation caveats, parameter conditions, and failure behavior. Every sentence adds value for a tool with no output schema, though the prose is a single dense paragraph and could be structured more cleanly with minimal loss.

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 complex tool with 8 parameters and no output schema, the description is highly complete: it defines the query, aliases, optional filters, fallback behavior, statistical output per cohort, and the no-fabrication failure mode. An agent has enough context to call the tool correctly and interpret its result.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter context beyond the schema: `query` is natural language, `task` and `niche` are aliases, provider_type/buyer_tier are conditional, and pricing_unit must not be blended. It does not discuss sector or response_mode, but those are already well-described in the schema.

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

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

The description names a specific verb and resource: 'Summarise observed prices for products related to a capability', segmented by delivery type and buyer tier. It also clarifies what the tool is not ('not a quote and not evidence of willingness to pay'). However, it does not explicitly distinguish itself from siblings like get_price_index or compare_providers, so sibling differentiation is implicit rather than direct.

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 invocation guidance: supply the capability via `query`, use `task`/`niche` as aliases, and populate provider_type/buyer_tier only when the user makes them known. It also explains the fallback matrix behavior. It does not name alternatives or state when not to use this tool versus a sibling, so exclusion guidance is missing.

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, the description carries full burden of behavioral disclosure. It thoroughly covers: self-reported evidence subject to eligibility checks, correlation with recent retrievals, ranking impact, rate-limit unlocks (doubled per-minute limit with 5+ correlated reports in 30 days), aggregation threshold (5+ distinct reporters in 90 days), and header hashing. This is exceptional transparency for a side-effecting write tool.

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

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

The description is about 150 words but every sentence carries distinct, essential information. It is front-loaded with the core purpose and then layers eligibility, aggregation, rate limits, and header instructions. No redundancy; the structure follows a logical progression from purpose to caveats to incentives. This is appropriately sized for 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?

The description covers the essential operational details: what triggers weight, aggregation thresholds, rate-limit consequences, and identity handling. However, it does not mention what the tool returns (e.g., confirmation, report ID) despite having no output schema. Given the tool's complexity (6 params, 2 required) and that return value could matter to an agent, a brief note on response would make it fully complete. This is a minor gap in an otherwise thorough description.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantic context: it clarifies that the outcome parameter reflects actual use ('ACTUALLY USING') and explicitly states what NOT to report (connection/retrieval tests), which shapes how parameters like outcome and agent_id should be filled. It also clarifies that agent_id must come from the listed retrieval tools. This goes beyond schema 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 opens with a specific verb and resource: 'Report the result of ACTUALLY USING a listed provider for a task.' It explicitly excludes testing/connection checks, which sharply distinguishes it from sibling search/compare/rank tools. The purpose is unambiguous and differentiated from all 18 siblings.

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

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

The description gives explicit when-to-use guidance: only after actually using a provider, not for testing. It states eligibility conditions (must match your recent retrievals within 48h) and explains consequences of unmatched reports (stored but unweighted). It also instructs on the x-agentery-key header for identity consistency. This is a textbook usage guideline.

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 most of the behavioral burden. It discloses the retrieval method (100% nearest-neighbour embedding, no fixed category), the reuse of existing pricing/search engines, caching behavior via result_fingerprint, and the explicit negative that it does not run comparisons. It stops short of stating read-only status or any auth/rate-limit constraints, but is still substantive.

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

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

The description is dense and well-structured with enumerated result components, bolded caveats, and front-loaded purpose. It is somewhat long and repeats alias details already in the schema, but most sentences earn their place by conveying routing or behavioral constraints.

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 — 8 parameters, 4 enums, and no output schema — the description is remarkably complete. It enumerates the main outputs (market, pricing stats, compare_ready shortlist, suggested_alternatives, fingerprint/cached), explains retrieval semantics, and provides the recommended fallback path, giving an agent enough context to call it effectively.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters, including enums and defaults. The description adds output-oriented context and repeats the task alias already present in the schema, but does not materially enrich parameter meaning beyond what the input schema provides.

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

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

The description names a specific combined action: 'ONE call turns a task into' a live market, pricing context, and compare-ready shortlist. It also distinguishes the tool from siblings by explicitly stating it does NOT run the comparison and reuses the canonical pricing/search engines rather than adding new logic.

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 when not to use it ('It does NOT run the comparison'), what to do instead ('pass compare_ready to compare_providers once you have finalists'), and the preferred detailed-inspection path ('search_providers → get_provider_profile → compare_providers'). This gives concrete when-to/when-not routing guidance.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses mixed delivery types, the possibility of unpriced products, the need to inspect priced/observed_price/provider_type before treating results as recommendations, the 'never padding' no_match behavior, and the effect of require_public_price and max_monthly_usd.

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 front-loaded with purpose and usage, then behavior. Most sentences add useful guidance, though some details repeat schema descriptions and the paragraph style could be tightened.

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 (8 params, no output schema, no annotations), the description is unusually complete: it explains return-field semantics, honest failure modes, filtering behavior, and the route to richer evidence via get_provider_profile.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a few extras like query aliases (q, text) and reinforces spending filters, but most parameter semantics are already fully documented 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 a specific verb and resource ('Find candidates for a described task') and gives a concrete example. It also distinguishes the tool from siblings by naming get_provider_profile, compare_providers, and research_capability, so an agent can tell this is the candidate-discovery step.

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 the workflow: use search_providers to find candidates, check strongest matches with get_provider_profile before recommending, then use compare_providers for shortlisting. It also mentions research_capability as an optional combined route, giving clear when-to-use guidance against 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 disclosed important behavior about cheaper_only: an empty response may be due to missing/incompatible reference pricing, not the absence of alternatives, and that the response indicates which. This is valuable beyond the boolean flag description in the schema, helping agents interpret results correctly.

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 block of text, moderately long, but every sentence adds value. It front-loads the core function and output details, then explains the tricky cheaper_only behavior. The note about 'NO category lookup' is important but not over-elaborated. Slight room for better structure by splitting sentences into paragraphs, but acceptable.

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 3 parameters, no output schema, and no annotations, the description covers its purpose, output fields, and a key edge case. It does not explain the full return structure in detail (e.g., response format of how_to_connect), but given complexity is moderate, it's sufficient. Lacks mention of potential subject with no alternatives at all, but overall complete enough.

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 describes each parameter's meaning. The description adds context for cheaper_only by explaining the edge case for empty response, which is useful. However, it doesn't add significant new semantics for agent_id or limit beyond what the schema says, so baseline 3 is appropriate.

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

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

The description clearly states the tool finds related alternatives to a provider, based on text-embedding nearness to that provider's own profile, with a specific list of output fields. It distinctly differentiates from siblings by explicitly noting 'NO category lookup' and mentions that substitutes are also surfaced inside research_capability and compare_providers, helping an agent distinguish this tool from those.

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

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

It provides clear context on when to use this tool: when you need alternatives to a known provider, and the mechanism (embedding nearness vs category lookup). It implicitly differentiates from siblings by stating that this tool is separate from category-based lookup and that alternatives are also surfaced elsewhere. However, it doesn't explicitly say when not to use it or name a specific alternative to prefer in certain cases.

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

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

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.