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?

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?

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?

With no annotations, the description fully discloses behavior: it uses text-embedding nearness, has no fixed category, strips pricing-intent boilerplate, and withholds pricing when match_certainty is 'uncertain'. It also details what the output includes (market label, provider counts, pricing_by_tier stats) and that it is read-only. This is comprehensive behavioral 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?

The description is dense with information but well-structured, front-loading the purpose and then detailing outputs. Every sentence carries value, though it is longer than necessary; a few clauses could be tightened without losing meaning. Still, it is efficient 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?

There is no output schema, so the description fully explains return values, including the pricing_by_tier statistics and match_certainty behavior. It covers parameters, use cases, and output semantics comprehensively, leaving no critical gaps for an agent to infer. The tool's complexity is well matched by the description's completeness.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds a concrete example ('reconcile supplier invoices') and mentions the alias, but does not add significant meaning beyond the schema's existing descriptions. It is adequate but not additive beyond what the schema already provides.

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

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

The description clearly states the tool maps a natural-language task to its closest-matching market neighborhood, with explicit mention of buyers, sellers, and sizing. It distinguishes itself from sibling tools like research_capability by noting when to use that alternative. The verb 'map' and specific output details make 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 explicit when-to-use guidance for buyers, sellers, and sizing, and explicitly names research_capability as the alternative for a one-call full market read + shortlist. It also clarifies that pricing-intent boilerplate is stripped before matching, adding context. This is a clear usage directive with 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 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 provided, the description carries the full burden and does well: it explains the computation source (live MCP search telemetry), the output fields, the meaning of cosine similarity, and honestly cautions that it returns few gaps while query volume is low. It stops short of noting side effects or read-only guarantees, but the behavior is clearly observational.

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 well-structured: behavior first, then outputs, then honest caveat, then parameter note. Every sentence carries substantive detail, though the phrase 'No arguments needed ({}); `limit` caps the list' creates a slight tension with the three optional schema parameters.

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 compensates by listing the key returned fields and their interpretations. It also gives the low-volume behavior caveat and mentions live telemetry, giving the agent enough context to use the tool. It could more explicitly differentiate from the sibling demand_signals and market_report tools, but the core completeness is strong.

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?

All three parameters are fully described in the input schema, so the description adds only marginal value. It mentions that no arguments are required and that 'limit' caps the list, but rank and sector semantics are already covered by the schema. This meets the baseline but does not go beyond it.

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

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

The description clearly identifies the tool's purpose: finding unmet demand by computing gaps between user-request clusters and paid providers. It is specific about the method (raw text-embedding space, no fixed categories) and distinguishes itself from market-report or provider-ranking siblings by defining gaps explicitly.

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

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

The description provides a clear usage context: use when you need to discover demand clusters that are underserved by paid providers. It does not explicitly name alternative tools or say when not to use it, but the distinctive gap/under-served framing makes the intended scenario 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?

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 burden of behavioral disclosure. It explicitly reveals that the market is a semantic embedding neighbourhood, that the blended median is never default, that prices come from a canonical pricing engine, and that the tool returns resolved:false rather than fabricating a figure. It also flags the deprecated blended legacy block in full mode.

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

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

The description is front-loaded with purpose and organised by market definition, output stats, parameter guidance, and failure behavior. It is longer than strictly necessary, but every sentence adds substantive behavioral or usage detail, so it earns a high score despite some verbosity.

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

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

For a 6-parameter tool with no output schema and no annotations, the description is unusually complete: it covers the matching algorithm, cohort statistics, input conditions, pricing-engine fidelity, and failure semantics. It falls short of 5 only because of the query/niche parameter inconsistency and the lack of an explicit response structure 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 description coverage is 100%, giving a baseline of 3, but the description adds meaningful semantics: the query/task alias relationship, when to supply buyer_tier/provider_type, incompatible pricing units not being combined, and response_mode full-mode behavior. However, the instruction to 'Pass `query`' conflicts with the input schema where `niche` is the listed legacy alias and `query` is not actually a defined property, which weakens the guidance slightly.

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-resource statement: 'Fair-price benchmarks for a capability described in natural language.' It then distinguishes itself from siblings by emphasizing semantic neighbourhood, no fixed category, and per-provider-type/per-buyer-tier cohort separation, clearly differentiating from tools like get_price_index 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?

The description provides clear usage context: supply provider_type and buyer_tier when known, omit them to get the per-type/per-tier matrix, pass the natural-language query, and expect resolved:false when nothing priced is close. It does not explicitly state when-not-to-use or name alternative tools, though the context is otherwise strong.

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?

No annotations are provided, so the description carries the full burden, and it delivers: it discloses the 100% nearest-neighbour retrieval mechanism, the absence of fixed categories, reuse of canonical pricing/search engines, the soft-ranking/no-hard-filter behavior for provider_type, and that repeat calls are cheap via result_fingerprint/cached. It also explicitly states what the tool does NOT do (run the comparison), preventing misuse.

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 information-dense, front-loaded with 'START HERE', and every sentence conveys a distinct fact about behavior, outputs, or alternatives. It could be slightly better structured with bullets or more compact phrasing, but given the complexity of the tool, the length is justified.

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

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

This is a complex orchestrator tool with 8 parameters and no output schema, so the description carries the burden of explaining return values and behavior. It comprehensively enumerates the three main output groups, additional fields (suggested_alternatives, result_fingerprint, cached), provider labels, and relationships to sibling tools. An agent has enough context to invoke and interpret the result without additional lookups.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it explains that provider_type matching is soft-ranked with cross_type_alternative entries and no zero-result cliff, that max_monthly_usd drives suggested_alternatives, and that task supports aliases. These enrich the schema without replacing it.

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

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

The description opens with 'START HERE for provider procurement' and specifies a concrete verb+resource: one call produces market, pricing context, and a provider shortlist. It clearly distinguishes itself from siblings by explicitly stating it does not run the comparison and directing the agent to compare_providers and lower-level tools like find_market and 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?

The description gives explicit when-to-use guidance ('START HERE'), what to do after use ('pass compare_ready to compare_providers once you have finalists'), and explicitly names alternative lower-level tools for finer control. This makes the selection decision clear for an agent.

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

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

With no annotations, the description bears the full burden of behavioral disclosure. It discloses ranking by match_score/match_reasons, inclusion of observed-price and how_to_connect, filter/sort behavior (max_monthly_usd handling of unpriced providers), and that unknown query keys are never silently ignored. It also mentions rate-limit benefits from report_outcome. It doesn't explicitly state if the operation is read-only, but that's implied. Slightly more could be said about output volume or pagination, but it's quite 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 paragraph but front-loaded with purpose and usage guidance. It efficiently covers when to use, what results include, related tools, and provides at least one parameter hint (billing, sort). It's not overly verbose and each sentence adds value. Slightly long but appropriate 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?

Given 8 parameters with nested objects and no output schema, the description covers the essential context: how results are ranked, what fields they contain (match_score, match_reasons, observed-price, how_to_connect), how to filter/sort for value, and pointers to more detailed tools. It addresses the complexity well and leaves little ambiguity about what the tool does and how to use 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 coverage is 100%, so baseline is 3. The description adds value beyond schema: it explains the purpose of sort (price_asc for value shopping), the behavior of max_monthly_usd with unpriced providers, mentions query aliases (q, text), and clarifies that unknown keys are not silently ignored. It also ties parameters to usage outcomes (e.g., filtering by billing, requiring public price). This adds meaningful context.

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

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

The description clearly states this is a 'Targeted provider search' for when you roughly know what you want, and explicitly distinguishes it from research_capability for new tasks and get_provider_profile for full details. The verb 'search' plus resource 'providers' is specific, and it differentiates from sibling tools by pointing to research_capability when the market is unknown.

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 when-to-use: 'when you already know roughly what you want', and when-not-to: 'for a NEW task where the market isn't known yet, call research_capability first'. It also recommends get_provider_profile for a full version and report_outcome after usage, giving clear decision guidance and 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?

No annotations are provided, so the description carries the full burden. It discloses the output fields (price, liveness, upvotes, how_to_connect) and the ranking basis (text-embedding nearness), plus the cheaper_only flag behavior. However, it does not explicitly state whether this is a read-only operation, though it is implied. It lacks details on potential rate limits, auth, or error behavior, but for a suggestion tool this may be acceptable. Overall, the description adds meaningful behavioral context but could be more explicit about its non-mutating nature.

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 thorough but somewhat verbose, packing many details into a single run-on sentence. Still, every sentence adds value (use case, ranking method, fields returned, aliases, redundancy note). It could be split into shorter sentences for readability, but it is not wasteful. A 4 reflects good content with minor structure inefficiency.

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 trigger scenario, ranking approach, output fields, filtering option, and crucially notes that the same alternatives appear in other tools, saving the agent from redundant calls. This is a complete picture for selection and usage. The lack of an output schema is mitigated by describing what is returned. No obvious missing context.

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

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

All 3 parameters are documented with clear descriptions: agent_id is the required handle, limit controls count, cheaper_only filters by price. The schema coverage is 100%, and the description adds nuance about cheaper_only (free providers qualify, no-observed-price excluded). A minor gap is that agent_id aliases are mentioned only in the description, not the schema, but that adds clarity. Deduct a point for not specifying the return format or pagination, but overall strong.

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: suggest alternatives for a shortlisted provider when too expensive, unreachable, or poor fit. It specifies the ranking method (text-embedding nearness) and explicitly notes it is NOT category lookup, distinguishing it from sibling 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?

Explicitly states when to use: when a shortlisted provider is too expensive, unreachable, or a poor fit. It also provides exclusions: alternatives are already surfaced in research_capability and compare_providers, so calling separately is rarely needed. This clear guidance helps the agent decide when to invoke.

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.