Agentery

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

Despite readOnly/non-destructive annotations already covering the safety profile, the description discloses substantial behavior: resolution order (exact handle, then exact name, never silent fuzzy swap), unresolved_inputs with suggested_matches and corrected_call, single-valid-input peer comparison, insufficient_valid_providers status, mixed delivery-type warning, and the concise-vs-full return modes. This is exactly the edge-case context an agent needs before calling.

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?

Front-loaded with purpose before behavioral detail, and nearly every clause carries decision-relevant information (resolution rules, statuses, delivery-type warning). It is dense and long for a single paragraph, but trimming would lose substantive edge-case guidance.

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 comparison tool with an output schema, the description covers what the schema cannot: input resolution failure modes, peer-comparison fallback, mixed delivery-type caveats, and suggested_alternatives with over-budget matches. An agent can call it correctly and interpret degenerate outcomes without further documentation.

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 nevertheless adds real value by documenting that provider_ids accepts aliases (handles, ids, or a comma-separated string) and by clarifying that detail:"full" expands every field. Remaining params (task, service, optional, request_ref) are left to the schema, which already documents them fully.

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

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

States a specific verb and resource ('compare 2–6 shortlisted listings side by side') and enumerates exactly what is compared: plan-level prices, capabilities, deployment, licence and how to connect, plus quote-vs-alternatives. It also names the sibling tools that produce its inputs (search_providers/market_gaps), so an agent can place it in the workflow without opening any schema.

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

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

Clear about the intended situation: shortlisted listings (2–6) or checking a quote against alternatives, with the prerequisite that handles come from search_providers/market_gaps. It does not explicitly say when NOT to use it (e.g. for open-ended discovery, where search_providers belongs), which keeps it from a 5.

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

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

Annotations already declare non-readonly, non-idempotent, non-destructive, closed-world behavior, but the description adds crucial context the agent would otherwise lack: the benchmark is PRIVATE, it returns a one-time secret benchmark_id token that is the sole key for later operations, ambiguous names are returned as candidates rather than auto-resolved, and unresolved inputs block creation unless allow_partial:true. It also reassures that canonical market data is never changed, which matters for a create operation.

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: the primary purpose and trigger condition come first, followed by the two modes and then the return-value/error-handling details. Every sentence carries useful information, though the single-paragraph form is long enough that mode details and secret-token guidance compete for attention; light structuring (e.g., explicit 'Mode A / Mode B' labels, which are present) keeps it readable.

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

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

Given six optional parameters, an output schema that covers return values, and rich annotations, the description fills the remaining gaps an agent needs: the two creation modes, ambiguity handling, the one-time secret benchmark_id and its downstream uses, and the allow_partial behavior. Nothing needed to call this tool correctly or interpret its result is missing.

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

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

Schema description coverage is 100%, so the schema already explains each parameter. The description nonetheless adds mode-level semantics the schema cannot convey: which parameters belong to Mode A vs Mode B, that product names/domains resolve only when unambiguous, and the precise effect of allow_partial (creating with resolved members only). This cross-parameter logic materially reduces invocation error risk.

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

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

States a specific verb+resource (creates a private custom benchmark / saved peer cohort) and immediately distinguishes it from siblings like get_custom_benchmark, update_custom_benchmark, and delete_custom_benchmark by naming where the returned benchmark_id is later used. The framing 'Use when someone wants to keep watching the prices of products they choose' makes the intent unambiguous.

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

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

Explicitly defines two modes with the exact parameter that selects each (members for Mode A, base_niche plus optional remove/add for Mode B) and states no account is needed. It also specifies downstream usage (get/update/delete, market_report, get_price_index) and the allow_partial fallback when inputs don't resolve, leaving no ambiguity about when to use this tool versus its siblings.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely new context by clarifying this is a soft disable that retains only a minimal audit record and touches no underlying Agentery data — a meaningful qualification of 'destructive'. It stops short of stating whether the disable is reversible or what permissions are required.

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

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

Three short sentences, front-loaded with the core semantics (disabling, not deleting) before the reassurance about data safety and the parameter note. Nothing is redundant.

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

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

An output schema exists and annotations carry safety/idempotency, so the description only needs to cover intent and side effects — which it does well. It omits whether the benchmark can be re-enabled and what the audit record entails, minor gaps 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 single parameter is documented as 'Your cb_ token'. The description's 'Pass `benchmark_id`' merely restates the schema rather than adding format or sourcing guidance, 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?

Names a specific operation on a specific resource ('Disable access to a custom benchmark') and immediately resolves the ambiguity of 'delete' by clarifying it is a soft disable that preserves an audit record. It does not explicitly contrast itself with siblings like update_custom_benchmark or get_custom_benchmark, so it falls just short of a 5.

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

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

The purpose implies when to call it (when a benchmark should no longer be accessible), but there is no explicit when-to-use/when-not-to-use statement and no alternative named — an agent must infer that update_custom_benchmark is the choice for modification and that this is the terminal removal path.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real context beyond them: the 90-day/0.62 thresholds, the single-caller interpretation warning, and the fact that an empty response returns insufficient_evidence + next_step rather than being backfilled. However, it never explains ordering beyond "ranked by distinct callers" interplay with limit/pagination, and the "generalised job labels" output shape is only loosely described.

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

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

The core definition is front-loaded in the first sentence, and every subsequent clause carries a caveat an agent would otherwise get wrong (single-caller leads, insufficient_evidence, no popularity fallback). It runs long and stacks several parenthetical qualifications, but none is 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?

An output schema exists, so return-value structure needn't be described, and the description covers the one output case an agent must handle (empty response meaning insufficient evidence). With annotations, thresholds, sibling routing and the include_own default caveat all present, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so both limit (1-50, default 20) and include_own (default false, counted in your_own_only_excluded) are already documented. The description adds only the empty-args case, which the schema does not state; it says nothing new about limit range or the effect of include_own. 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?

"Lists searches that found nothing good" gives a specific verb and resource, then sharpens it with a precise definition (external callers, last 90 days, no provider or best relevance below 0.62). It explicitly contrasts itself with market_gaps, so an agent can separate the two sibling tools without reading either schema.

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

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

States when to use it ("when you want searches Agentery could not answer well"), when not to lean on it ("not a prerequisite for choosing a product"), and names the alternative for the adjacent case (market_gaps). It even specifies the empty-args invocation behavior, leaving nothing to inference.

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

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

Annotations already cover the read-only, non-open-world, non-destructive profile, so the description's value is the extra behavior it discloses: matching is semantic with no fixed categories, and when coverage is weak it returns no_match or thin_coverage and withholds pricing rather than fabricating a market. That negative-path behavior is exactly what an agent needs to interpret an empty-looking result.

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

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

Front-loaded with purpose and trigger before the return-value detail, and every sentence is load-bearing. The long enumeration of return fields is slightly redundant given a declared output schema, which is the only real trimming opportunity.

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?

Covers trigger conditions, semantic matching model, fallback states, and sibling routing, which is ample for a two-parameter read tool. The extended return-value narration overlaps with the existing output schema, so it is complete with a little duplication rather than a gap.

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

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

Schema description coverage is 100%, and the schema already documents both the required task string, the empty-call behavior, and the query back-compat alias. The description adds only an illustrative example ('tools that monitor competitor pricing'), which the schema already supplies in kind. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb and resource ('Maps a task to its market') and immediately enumerates the scope: who competes, how many are priced, price level per buyer tier. The description of the semantic nearest-provider matching ('nearest providers by meaning, no fixed categories') distinguishes it clearly from category-browsing siblings like search_providers or market_report.

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

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

Gives an explicit trigger ('when someone asks who competes in a space or what a kind of product costs') with a concrete example query. It then routes to three named alternatives with the condition that selects each: market_report for the full measured breakdown, research_capability for market plus shortlist, price_benchmark to judge a specific price.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description goes beyond that with real behavioral constraints: headline medians/quartiles appear only with ≥3 comparable priced members and monthly/per-seat/per-call prices are never blended, which tells the agent what results can look like and why.

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 report contents are front-loaded in a single dense sentence, followed by the argument instruction. Efficient overall, though the final sentence largely repeats the benchmark_id guidance already present in the 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 an output schema present, return-structure detail is unnecessary and annotations carry the safety profile. The description supplies the one non-obvious caveat (aggregation threshold) and covers the read path adequately for a 4-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 coverage is 100%, so as_of, version, benchmark_id, and response_mode are already documented, including the enum. The description only reinforces that benchmark_id is a cb_ token passed as an argument, adding little beyond the schema; 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?

States a specific verb and resource ('Get a private custom benchmark's current report') and enumerates what the report contains: members, stats, cohorts, historical index, coverage. This clearly separates it from the create/update/delete_custom_benchmark siblings and from market-level tools like get_price_index.

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

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

Usage is implied — read the report for a custom benchmark you already own — but there is no explicit when-to-use or when-not versus siblings such as price_benchmark, compare_providers, or get_price_index. The only explicit instruction is passing benchmark_id as an argument.

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

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

Beyond the annotations, the description discloses important behavior: it returns medians of current published prices only, does not return individual listings, includes usage and one-time medians only where at least 3 listings publish them, and reports the group's 90-day price-index change. These details meaningfully tell the agent what to expect from the result.

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

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

The description is front-loaded with the core purpose and then covers alternatives and invocation modes. It is dense but mostly earns its length; some clauses could be trimmed, but none are irrelevant.

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 output schema exists, the description need not explain return values in full. It covers purpose, alternatives, thresholds, no-argument behavior, and scope limitations, so an agent has enough information to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that the no-argument case lists group IDs and that group_id can come from the group price league, supplementing the schema's references.

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

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

The description states a specific verb and resource: it gives a broad group-wide fair price for a product group, defined as the median entry monthly price per buyer tier. It explicitly distinguishes itself from price_benchmark and search_providers, so an agent can identify its role without inspecting the schema.

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

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

It gives explicit usage guidance: use this for a general price guide, use price_benchmark for checking a specific quote, and use search_providers for candidates. It also explains that calling with no arguments lists group IDs, covering the main invocation modes.

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

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

Annotations only cover the read-only/safe profile, and the description goes well beyond them: it defines the index as a chained quoted-price index (base 100 = 30 Jun 2026, an index level rather than a price) and states every response carries release_id, reference_currency and methodology_revision. It also discloses what response_mode=full unlocks (fx_attribution, currency_evidence), which the agent would otherwise only discover by calling.

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 trigger and the definition are front-loaded, and the closing routing sentence earns its place. The middle is one very long sentence with nested parentheticals (base 100, index level, log changes add / level factors multiply), which is dense but nearly all substantive rather than 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?

Given an output schema exists, the definition covers everything an agent needs to select and call correctly: trigger, index semantics, segment selection, response_mode effect, and sibling routing. Nothing material is left ambiguous.

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 already 100%, and the description still adds meaning: provider_type values are explained semantically ('standalone index over just that delivery type, own base 100') rather than just enumerated, and response_mode's added payload is spelled out. The benchmark_id guidance mentions a 'niche' parameter not present in the schema, which is a small inconsistency but does not obscure usage.

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

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

States a specific resource and scope: the Agent Economy Price Index with 1-, 7- and 30-day change and four buyer tiers. It explicitly distinguishes itself from get_price_index_history (trend over time), get_group_fair_price and price_benchmark (what a product costs), so an agent can separate it from siblings without reading schemas.

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

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

Opens with a concrete trigger ('Use when asked whether prices ... are rising or falling overall') and names the correct alternatives for adjacent questions. It also advises which index segment to read ('an MCP buyer should read the mcp index and an agent buyer the agent index'), which is a routing decision not obvious from the schema.

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?

Goes well beyond the readOnly/destructive annotations: points are index levels never prices, missing days are reported in `gaps` with reasons and never interpolated, thin data returns `insufficient_history` rather than an invented series, and 'full' mode adds attribution and currency-evidence splits. These are real behavioral contracts an agent cannot infer from annotations.

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

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

Front-loaded with the core purpose and the sibling redirect, and no sentence is pure filler. However the single dense paragraph with semicolon-chained parameter notes is harder to scan than it needs to be.

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

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

With a 100%-covered schema, full annotations, and an output schema, the description supplies exactly the missing layer: what the numbers mean, how gaps are handled, and when not to use it. Nothing needed to call it correctly is absent.

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 descriptions are themselves detailed (enum meanings, defaults, benchmark_id/cursor behavior), so the description largely restates defaults. It mentions tier, provider_type, period and response_mode but omits `since` and `benchmark_id` details that the schema carries. Baseline 3 fits.

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

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

States a specific verb+resource: 'show how AI agent and MCP prices have moved over time' and names the exact artifact (the dated Agent Economy Price Index, base 100 = 30 Jun 2026). It explicitly separates itself from get_price_index-adjacent siblings by pointing to price_benchmark and market_report for per-capability costs.

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

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

Gives explicit routing: 'For what one capability costs use price_benchmark or market_report,' plus when to use `tier`, `provider_type`, `period`, `response_mode`, and when to supply `benchmark_id`. The polling path is also spelled out via `since` semantics in the schema.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered by structured data. The description adds genuine context beyond that: this returns a deliberately *short* card, and the structured profile is only present 'when available' — warning the agent that fields may be missing. It doesn't discuss rate limits or lookup-failure behavior, which keeps it at 4 rather than 5.

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

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

A single sentence with zero waste, and the routing decision (prefer get_provider_profile; use this only for…) is front-loaded so the agent sees the disambiguation rule before the field list.

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?

An output schema exists, so return values needn't be explained, yet the description enumerates the card's contents anyway and flags that the structured profile is conditional. Combined with annotations covering the read-only, closed-world safety profile, an agent has everything needed to select and invoke this correctly.

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

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

Schema description coverage is 100% with both parameters documented (handle example, regNum example), so the schema carries the semantic load and the baseline is 3. The description reiterates the two lookup keys ('by handle or registration number') but adds no format, precedence, or mutual-exclusivity detail beyond what the schema already shows.

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

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

States a specific verb and resource (retrieve the short public directory card of one provider) and enumerates exactly what the card contains: bio, source URLs, X-verification status, entity type, community rating, structured profile. It explicitly names the sibling get_provider_profile as the tool for a different need, so an agent can disambiguate without opening either schema.

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

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

Gives an explicit when-to-use rule ('for buying decisions prefer get_provider_profile') and a restrictive when-to-use-this rule ('use this only for the short public directory card'), naming the alternative tool directly. Both the positive and negative conditions are spelled out rather than implied.

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

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

Annotations already mark this read-only, non-destructive and closed-world, and the description goes well beyond them: fields are null when the vendor publishes nothing and nothing is guessed, price_applies_to flags a stored price belonging to the vendor's platform rather than this connector, and reported_success stays null until 5+ distinct reporters in 90 days. These are exactly the data-quality caveats an agent needs before quoting a value to a user.

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?

It is front-loaded with the usage trigger before the field inventory, and every clause carries information (null policy, price_applies_to, the 5-reporter threshold). It is still a dense single block that spills return-field detail which partly duplicates the existing output schema, keeping it just shy of a 5.

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

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

An output schema exists, yet the description usefully adds semantics the schema cannot convey: what nulls mean, why price_applies_to exists, and the threshold behind reported_success. Combined with full schema coverage and clear annotations, an agent has enough to call and interpret this tool; the only real gap is disambiguation from get_provider.

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

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

With a single parameter at 100% schema coverage, the schema already explains that provider_id/handle comes from search_providers or compare_providers. The description only reinforces that this identifies 'one specific listing' and adds no format or syntax detail, so the baseline of 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?

States a concrete verb and resource: check one specific listing (plans, prices, integrations, deployment, licence, liveness, connection paths). That is far more specific than the title. It does not, however, distinguish itself from the sibling get_provider, which by name appears to fetch the same entity, so the agent is left to guess which listing-fetch tool to pick.

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

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

'Use to check one specific listing before recommending or connecting it' gives a clear trigger condition, and 'after actually using a listing, call report_outcome' explicitly hands off to the correct sibling. What is missing is guidance on when to prefer get_provider or compare_providers instead, so the alternatives are only partially covered.

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 adds substantial behavioral context beyond the read-only annotations: status and phase enumerations, polling cadence, and the guarantee that polling is free and never repeats work. It also describes the shape of the result and evidence, which helps the agent interpret responses 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 front-loaded with purpose and avoids filler, but it is a dense run-on paragraph. The status, phase, polling, and result details all earn their place, though clearer structure would improve scanability.

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 polling-based complexity, the description covers statuses, phases, polling behavior, and result contents thoroughly. With an output schema available to carry return-value details, this is complete enough for correct invocation.

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

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

Schema description coverage is 100%, and job_id is already documented as coming from request_research. The description reinforces the request_research relationship but adds no new syntax or format details 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 states a specific verb and resource: retrieving the status and result of a research job created by request_research. This clearly distinguishes it from the creation tool and from unrelated sibling tools.

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

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

It clearly establishes the usage context: call this after request_research and poll no more often than poll_after_seconds. It does not explicitly name when-not to use it or point to stop_research_updates as an alternative, so it falls short of full when/when-not guidance.

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

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

Adds real context beyond the readOnly/openWorld annotations: test traffic is excluded, small-sample results are normal, and the output is research leads rather than buyer counts or proof of a market-wide gap. The enumeration of returned fields partly duplicates the output schema, but the semantic gloss ('similarity low = under-served', headline = 2+ callers, weak_leads = one caller) is genuinely additive.

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?

Front-loaded with purpose, then routing, then returns, then caveats — a sensible order with no filler sentences. It is dense, though: the return-field list and the lead-tier definitions are packed into one long block, and the caveat about small samples is easy to skim past at the end.

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

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

An output schema exists, so return values needn't be re-explained, and the description still covers the interpretive caveats an agent needs to avoid overclaiming. The one material omission is any hint that results can be re-ranked by 'hot' or narrowed by sector, which changes what the tool produces.

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 each parameter is well described, so the baseline is 3. The description's only parameter-adjacent statement is 'No arguments needed', which understates the available controls — the rank enum (gaps vs hot) and the sector filter materially change results but are not mentioned or cross-referenced.

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?

Specific verb plus a precisely scoped resource: 'jobs callers ask for that few paid products serve ... clustered by meaning, that sit far from any paid provider.' It also names the sibling it is not (demand_signals) and the audience that asks for it, so an agent can route without opening any schema.

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

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

Gives an explicit trigger ('when a seller or investor asks where under-served opportunities are') and an explicit alternative with its own condition ('Use demand_signals instead when you want searches that returned no or only weak results'). This is the when/when-not/alternative pattern at full strength.

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

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

Annotations already declare readOnly=true, openWorld=false, destructive=false, so safety is covered. The description adds meaningful context beyond that: all fields are MEASURED (no synthetic data), the market is derived by text embedding with no fixed category, and it clarifies what each response_mode contains.

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?

Front-loaded with purpose and routing before detail, and every clause carries information. Slightly verbose with repeated emphasis ('ONE', 'MEASURED' three times) but not padded.

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?

Output schema exists so return shape needn't be explained, and the description nonetheless covers modes, paging, cohort reuse, and request_ref continuation. Complete for an agent to call correctly.

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

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

Schema coverage is 100%, so the bar is baseline 3. The description adds value by giving a concrete query example, clarifying the semantic-neighbourhood selection, and reinforcing the summary vs. full mode behavior beyond the schema text.

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

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

States a specific verb and resource ('Measures ONE market in depth') plus what it returns (price distribution by provider type/buyer tier, competing providers). Explicitly distinguishes from find_market, research_capability, and 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?

Gives the selecting condition ('when you need detailed market numbers, not a quick map') and names three alternatives with the use case for each. Routing 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?

Annotations already cover safety (readOnly, non-destructive, closed-world), and the description adds substantial context beyond them: results are never blended across incompatible pricing units, split by delivery type and buyer tier, and fall back to resolved:false with a note rather than an invented figure. It also sets expectations that a benchmark is an observed sample, not a quote or willingness to pay.

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?

Purpose and trigger are front-loaded before the return-shape and caveat sentences, and each sentence carries information. Slightly long for a single tool definition, with some overlap between the return-format and sibling-routing sentences, but 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 15-parameter analytical tool with an output schema, the description covers input intent, segmentation logic, degenerate-case behavior, and the interpretive limits of the result. Nothing an agent needs to call it correctly or read the output sensibly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining when to supply provider_type and buyer_tier and by naming the query aliases (task, niche). It does not add much for paging, currency, commitment, or cohort_ref, which the schema already handles.

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

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

States a specific verb and resource — judges a price/quote against comparable products — with the comparison basis ('by what they do, no fixed categories') and scoping (buyer tier, pricing unit). It explicitly distinguishes itself from siblings by naming get_group_fair_price for group-wide guides and find_market for competitor discovery.

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

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

Gives an explicit trigger ('Use this when asked whether a price is fair or what a capability typically costs') with a concrete example, plus named alternatives and the conditions that select them. Guidance on setting provider_type and buyer_tier when known further narrows invocation.

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

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

Annotations already declare this is non-read-only, destructive, non-idempotent, and closed-world. The description adds useful behavioral context: Agentery re-runs the search while keeping other constraints, returns the new answer plus what changed, only sees the request/correction rather than the wider conversation, and references expire after 24 hours. It does not fully detail what is destroyed or invalidated by the re-run, so it falls short of a 5.

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

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

The description is front-loaded with the core usage condition and correction examples, then moves into mechanics, privacy scope, task-answer protocol, and expiry. It is dense but appropriate for a multi-step continuation tool. There is some repetition, notably restating the source enum and 'plain words' guidance, which keeps it from being maximally 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?

The description is complete for an agent to call the tool correctly: it covers prerequisites (request_ref), correction format, source semantics, continuation behavior, privacy scope, and expiry. An output schema exists and annotations exist, so return-value details and safety traits are already covered by structured fields.

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 meaning beyond the schema by explaining the source values ('human' = user's words, 'agent' = your assessment/default, 'follow_up'), giving correction examples such as 'must integrate with Slack' and 'budget is $20/month', and clarifying that request_ref comes from the earlier answer.

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

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

The description states a specific action and resource: refine results by passing a request_ref and correction so Agentery re-runs the search with changed constraints. It explicitly names sibling tools (search_providers, research_capability) and distinguishes this tool as the correction/refinement path rather than a fresh search.

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 when-to-use guidance: 'Use when an earlier search_providers or research_capability answer missed what was meant.' It explains exactly what to pass (request_ref plus correction in plain words), provides examples, and names the alternative continuation path: pass the same request_ref to another task 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?

Despite the mutation annotation set (readOnlyHint=false), the description adds substantial behavior the annotations do not cover: self-reported evidence subject to eligibility checks, unmatched reports stored but unweighted, 5+ reporter aggregation with a 90-day window, doubled rate limit at 5+ correlated reports, and identity hashing via the x-agentery-key header. This is well beyond the annotation baseline.

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 critical distinction (real use vs. connection testing) is front-loaded, and most sentences carry policy the agent needs. It is dense and long for a single paragraph, but the incentive and identity details justify their space rather than padding it.

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 six-parameter mutation with an output schema, the description covers the one thing the schema cannot: the eligibility and correlation rules that determine whether the report counts. Return values need not be explained because an output schema exists.

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 still adds value by explaining what makes agent_id meaningful (it must correspond to a provider named in one of the caller's recent retrievals) and by framing outcome as a hired-task judgment. It does not detail latency_ms or error_class, but the schema already does.

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 first sentence names a specific verb and resource ('Report the result of ACTUALLY USING a listed provider') and immediately distinguishes this action from connection/retrieval testing. An agent can tell exactly what is being written and what is not.

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 both the positive case (you actually used the provider for a task) and the explicit exclusion (testing Agentery's connection or retrieval does not establish that the provider worked — do not report those). It further narrows valid use to reports matched against the caller's own retrievals in the last 48h via named sibling tools.

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

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

Adds substantial context beyond the annotations: typical latency (~15 s), the polling handoff, job deduplication for identical questions, that code is read but never executed, and an epistemic caveat that a found statement is the vendor's own claim, not independent verification. The readOnlyHint=false annotation is consistent with the description's disclosure that a job is created (a job_id is returned).

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?

Front-loaded with the trigger condition and free of filler, but it is one dense run-on paragraph carrying trigger, mechanics, async handoff, dedupe and caveat in a single breath. Splitting the async/dedupe/caveat sentences would improve scanability without adding 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?

An output schema exists, yet the description still supplies what the schema cannot: when the call is warranted, expected latency, what to do on timeout, job sharing, and how much to trust the result. For a paid, open-world, asynchronous research request this covers everything an agent needs before invoking it.

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 parameters are already documented, including provider_id provenance and requirement examples, so the baseline is 3. The description's sample payload restates the same information rather than adding new semantics such as how request_ref links to a prior answer or how to phrase requirements that the answer vocabulary (yes/no/partly/unknown) can resolve.

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

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

States a specific verb (request research), a precise scope (one specific fact about one listing that its profile does not settle), and the exact sources consulted (vendor pages, code repository read-not-run, pricing page buttons). The answer shape (yes/no/partly/unknown with quotes, URLs, observation dates) makes it unmistakable which sibling produces this output versus get_provider_profile 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?

The opening clause gives an explicit trigger condition and two concrete example questions, and the async path names the alternative: if not answered in ~15 s, call get_research with the job_id after poll_after_seconds. It also warns that identical questions share one job. It lacks an explicit 'do not use for' against broad siblings like research_capability or compare_providers, so the exclusion is only implied by 'one specific fact about one listing'.

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

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

Annotations already cover read-only safety, but the description adds substantive behavior: the response includes price range and median with sample size, market_position labels, compare_ready handles, and suggested_alternatives. It also discloses a scope boundary ('does not run the comparison'), though it omits latency or result-volume expectations. The added output-context value is strong, but not exhaustive.

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 return contents, then moves to alternatives. It is information-dense but slightly packed into two long sentences; every sentence carries useful routing or output information, with no filler.

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

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

With an output schema present, the description need not detail return values, yet it still summarizes the key outputs an agent needs to interpret the response. All required routing, scope boundaries, and workflow alternatives are covered, leaving no ambiguity for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all ten parameters, including enums, defaults, and aliases. The description only repeats the `task` parameter and its aliases, adding no syntax or usage detail beyond the structured schema. 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 uses a specific verb and resource ('one-call first overview of a buying task') and names exactly what it returns: market prices, a priced shortlist, and alternatives. It is clearly distinguishable from compare_providers, search_providers, and price_benchmark, which are named directly.

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 to use it ('when you want a quick picture') and explicitly says what it does not do ('It does not run the comparison'). It then redirects the agent to the alternative workflow (search_providers → get_provider_profile → compare_providers) for careful selection and to price_benchmark for judging a single price.

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?

Goes well past the read-only annotations by disclosing result semantics: fit labels with named mismatches, price status vocabulary with the key caveat that 'unknown is never free', and that thin coverage yields no_match rather than padding. It also states that requirements in the query are checked per result and unverified ones marked unknown. Minor gap: no statement of result volume or whether repeated calls are deterministic.

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?

Front-loaded with the core purpose and trigger before moving to output semantics and routing. It is dense but nearly every clause carries distinct information; the single run-on sentence structure makes it slightly harder to scan than it could be.

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

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

A 10-parameter tool with nested filters is fully covered: purpose, trigger, result-field semantics, empty-result behavior, and sibling routing are all present. With an output schema available, the description still adds the interpretive context an agent needs to trust the returned fit and price labels.

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 earns above that by explaining cross-parameter semantics the schema does not, such as the price-status taxonomy and the rule that unknown pricing is never treated as free. It does not add guidance on sort, limit, or request_ref beyond what the schema already says.

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

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

States a specific verb and resource ('Finds products ... that do a task') and defines the output shape ('ranked shortlist'). It also explicitly delimits scope against siblings by pointing cost questions to price_benchmark, find_market, and get_group_fair_price, and overview questions to research_capability.

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

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

Gives an explicit entry-point instruction ('start here to choose a product') plus a concrete trigger example ('MCP server to reply to Zendesk tickets'). It names both downstream steps (get_provider_profile, compare_providers) and the four sibling tools to use instead for cost or overview questions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=false. The description adds useful context beyond annotations by stating that the research result stays retrievable with get_research, clarifying that stopping updates does not delete the result. It does not address permissions or notification behavior.

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

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

The description is a single, front-loaded sentence with no wasted words. The parenthetical adds relevant retrieval context without bloating the definition.

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

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

The tool has a full input schema, output schema, and rich annotations, so the description need not explain return values or safety profile. It adds the key behavioral note that results remain retrievable, making the definition complete enough for an agent to invoke it correctly. Minor gaps remain around when exactly to stop watching versus other research lifecycle actions.

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 single job_id parameter is fully documented in the schema with format details. The description does not add meaning beyond the schema, so the baseline score of 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 states a specific verb and resource: stop watching a research job. It also clarifies that the result remains retrievable via get_research, which helps distinguish this tool from retrieval and job-starting siblings. It does not explicitly differentiate from request_research, but the core purpose is 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?

Usage is implied: call this when you no longer need live updates for a research job. The parenthetical points to get_research as the alternative for retrieving results, but the description does not explicitly state when to use this tool versus alternatives or any exclusions.

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

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

Goes well beyond the readOnly/non-destructive annotations: it discloses the ranking basis, the fields each result carries (observed price, endpoint liveness, upvotes, how_to_connect), and a genuinely important failure mode — that an empty cheaper_only response may mean a missing/incompatible reference price rather than no alternatives, with the response indicating which. That is exactly the kind of behavioral context annotations cannot express.

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?

Front-loaded with the core purpose and ranking method, and most sentences carry real information. There is mild redundancy — how_to_connect is introduced, then re-enumerated with install/repository and a version tag '(1.10.0)' that reads like changelog noise rather than decision-relevant 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?

Given an output schema exists, the description needn't document return values, yet it still summarizes what each alternative carries. Combined with ranking logic, the cheaper_only edge case, alias handling, and cross-tool routing hints, an agent has everything needed to call it correctly and interpret an empty 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, but the description adds value by documenting that agent_id accepts aliases (handle, id), which is not in the schema. The cheaper_only caveat also reinforces the parameter's edge-case semantics beyond the schema's own text.

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

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

States a specific verb and resource (find related alternatives to a known provider) plus the ranking mechanism (text-embedding nearness to the provider's OWN profile, explicitly NOT category lookup). That contrast with category-based discovery distinguishes it from siblings like search_providers and find_market without needing to open their schemas.

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

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

Clearly framed as the tool for finding substitutes when you already have a reference provider, and it notes these substitutes are also surfaced inside research_capability and compare_providers, which helps an agent route between overlapping tools. It stops short of an explicit 'use X instead when...' exclusion, so it falls just shy 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?

Goes well beyond the annotations by disclosing that a NEW immutable version is created, that the previous version remains fully reproducible, and that the response carries exact change-impact on median/quartiles/index. This adds meaningful mutation semantics (versioning/immutability) that destructiveHint alone does not convey.

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

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

Two tightly packed sentences with no waste; the operation and the required parameter are front-loaded before the versioning/return detail.

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

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

Output schema exists, so return-value explanation is unnecessary, and the description still notes the response carries change-impact. Versioning behavior, required param, and mutation nature are all covered; nothing critical for correct invocation is missing.

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

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

Schema coverage is 100% and every parameter is already documented, so baseline 3 applies. The description only reinforces 'Pass benchmark_id' without adding format or interaction details (e.g., whether add and remove can be combined) 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?

States specific verbs (add/remove members, rename) on a specific resource (custom benchmark), which clearly separates it from create_custom_benchmark, delete_custom_benchmark, and get_custom_benchmark. An agent can identify the operation without opening the schema.

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

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

Implies use for modifying an existing benchmark and instructs passing benchmark_id, which distinguishes it from creation. It does not explicitly name sibling alternatives (create vs. delete) or state prerequisites such as who may mutate a benchmark, so it stops short of full when/when-not routing.

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