agentery

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial undisclosed behavior: deterministic resolve order (exact handle, then exact name, never fuzzy), the unresolved_inputs + suggested_matches + corrected_call contract, delivery-type non-equivalence warnings, and suggested_alternatives for over-budget matches. This goes well beyond the safety profile.

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

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

Front-loaded with purpose and scope before the resolution edge cases, and virtually every clause carries operative information. It is dense to the point of being a wall of text, but the ordering makes it scannable and nothing is pure filler.

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

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

No output schema exists, yet the description compensates by enumerating the return shape (fit, plans and prices with source and date, job cost, requirement verdicts, unknowns) and the failure/degradation statuses. For a 7-parameter comparison tool 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 coverage is 100%, so baseline is 3; the description adds value by documenting the accepted alias forms for provider_ids ('handles, ids, or a comma-separated string') and by clarifying the concise/full detail switch and its default. It does not add much on task/service/requirements beyond the schema, keeping it short of a 5.

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

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

Opens with a specific verb+resource+scope ('compare 2–6 shortlisted listings side by side') and lists what the comparison covers (plan prices, capabilities, deployment, licence, connection). This clearly distinguishes it from singular getters like get_provider and from search_providers/market_gaps, which it explicitly names as the source of handles.

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

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

States the two triggering scenarios ('compare shortlisted listings' and 'check a quote against alternatives') and routes the agent to search_providers/market_gaps for obtaining inputs. It also spells out fallback conditions (one valid input → nearest market peers; none valid → insufficient_valid_providers), which is exactly the when-to-use/when-not guidance an agent needs.

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 leave gaps that the description fills well: no account needed, the result is private, the return is a one-time secret cb_ token that must be stored as the only key, ambiguous names come back as candidates and never silently resolve, unresolved inputs block creation unless allow_partial:true, and canonical market data is never mutated. That is unusually rich behavioral context for a create tool.

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

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

Front-loaded with the trigger condition and mode breakdown, and every sentence carries information (modes, token storage, resolution policy). It is dense and abbreviation-heavy, but nothing is redundant padding; slightly tighter phrasing would earn 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?

No output schema exists yet the description still states the return value (the one-time cb_ benchmark_id token) and its downstream uses, covers both creation modes, and disambiguates the failure/partial-resolution behavior. An agent has everything needed to invoke it correctly on the first try.

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 100% schema coverage the baseline is 3, but the description adds real meaning the terse schema strings omit: it frames members as Mode A versus base_niche as Mode B, specifies that members accept exact handles (preferred) with names/domains resolving where unambiguous, and explains what allow_partial actually changes (create with only resolved members). This goes meaningfully beyond the schema descriptions.

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

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

States a specific verb (Creates) and resource (a PRIVATE custom benchmark / saved calculated peer cohort), and immediately differentiates itself from siblings by naming get/update/delete and the read-side tools that consume its output. An agent can tell what this tool produces and where it fits in the lifecycle without opening any other 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?

Explicitly opens with 'Use when someone wants to keep watching the prices of products they choose' and then enumerates the two selection modes (A explicit members, B fork a market) with the exact parameters that select each. It also routes the agent to the follow-up tools the returned id feeds into, so both when-to-use and next-step are 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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real context beyond them: no underlying Agentery data is touched and only a minimal audit record is retained. This refines what 'destructive' actually means here (soft-disable, not data loss), which is exactly the sort of disclosure the annotations cannot 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?

Three short, front-loaded sentences: effect first, then the data-safety caveat, then the parameter. No wasted words, though the final 'Pass benchmark_id' sentence is largely redundant given the single required parameter.

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

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

For a one-parameter mutation with no output schema, the safety profile (annotations) plus the description's soft-delete clarification cover what an agent needs. Minor gaps remain around reversibility and permission requirements, but nothing blocking.

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 itself carries the useful 'cb_ token' format hint. The description's 'Pass `benchmark_id`' merely repeats the required parameter name without adding syntax or constraint detail, so the schema does the heavy lifting and 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 ('Disable access to a custom benchmark') and, notably, clarifies that the delete is actually a soft-disable rather than a hard removal. This distinguishes it from what the name alone implies, though it does not explicitly contrast with siblings like update_custom_benchmark or get_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?

No guidance on when to disable access versus updating or retrieving the benchmark, and no prerequisites or exclusions stated. Usage is only implied by the verb 'disable'. An agent gets no routing help among the custom-benchmark 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?

With annotations already declaring readOnly/openWorld=false/destructive=false, the description adds substantial behavior: the 90-day window, the 0.62 relevance threshold, caller-count ranking, and the empty-response contract (status insufficient_evidence plus next_step). It also rules out silent backfilling from search popularity, page views or trending queries, which is material trust context.

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

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

The definition is a single dense paragraph, front-loaded with the core operation before caveats and the empty-args contract. Nearly every clause earns its place, though the paired 'not proof... and not proof...' clause is slightly 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?

With no output schema, the description carries the return contract and does so well: it explains the returned form (generalised job labels, ranked by distinct callers) and the empty-evidence case with its status/next_step semantics. For a one-parameter read-only tool, nothing an agent needs to call or interpret it 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% and the single 'limit' parameter (1-50, default 20) is fully documented in the schema. The description says 'Empty args ({}) return the current list', which confirms default behavior but adds no further detail about the limit parameter. 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 gives a precise verb and resource: it inspects searches by external callers in the last 90 days that returned no or weak matches (relevance below 0.62), rendered as generalised job labels ranked by distinct callers. That is far more specific than the name/title alone. It never names or contrasts with a sibling (e.g. market_gaps), so it stops short of full sibling differentiation.

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

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

It offers interpretation guidance ('Most entries come from a single caller: treat those as leads') and a negative usage note ('Not a prerequisite for choosing a product'), implying context. However, it never states explicitly when to prefer this tool over alternatives such as market_gaps or find_market, leaving routing 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 declare this is a safe, closed-world read, so the safety bar is low. The description goes further with a behavioral trait the annotations cannot express: it withholds pricing and returns no_match/thin_coverage rather than inventing a market. It also describes the return payload (label, counts, nearest providers, pricing_by_tier percentiles), which is real disclosure beyond the safety hints.

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 usage trigger, then payoff, then failure mode, then the alternative — a logical order with no filler sentences. It is dense and slightly list-like in the returns enumeration, but each clause carries distinct information an agent needs.

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?

No output schema exists, so the description correctly carries the burden of describing return values — and it does so in detail (market label, provider/priced counts, nearest providers with observed prices, pricing_by_tier medians/quartiles/range/n). Combined with the fallback behavior and the routing hint, 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%, with both `task` and its alias `query` fully documented in the schema, including the empty-call behavior. The description adds only the 'no fixed categories' framing for how `task` is interpreted, which is marginal semantic value. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('maps the task to its market') and immediately scopes it ('nearest providers by meaning, no fixed categories'). It also enumerates exactly what comes back, so the agent knows this is not a generic search tool. It differentiates from the closest sibling by naming research_capability and the condition that selects it.

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 an explicit trigger ('Use when someone asks what a kind of product typically costs or who competes in a space') backed by two concrete example queries. It names the alternative tool and the exact situation that should route there ('market plus shortlist in one call'). Edge-case guidance (no_match / thin_coverage) covers the failure path as well.

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 a safe read, but the description adds substantive behavioral context beyond them: the ≥3 comparable-member threshold gating headline medians/quartiles, the guarantee that monthly/per-seat/per-call prices are never blended, and the security rule that benchmark_id is a bearer secret passed as an argument rather than a URL. These are real operational constraints an agent would otherwise not know.

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-loads what is returned and packs thresholds, cohort types, and the token-handling rule efficiently into one sentence plus a short instruction. The enumeration is dense but every clause carries information; 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 no output schema, the description takes on the burden of describing returns and does so thoroughly, including statistical gating rules. Only minor gaps remain, such as when to prefer this over sibling read tools and pagination/response-size behavior.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the as_of reproducibility semantics and the response_mode enum. The description only re-emphasizes that benchmark_id is a cb_ token passed as an argument; it adds little parameter meaning beyond the schema, 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 verb (get) and resource (private custom benchmark's current report) and enumerates the exact payload returned: members, stats, cohorts, index, coverage. This is clearly distinguishable from siblings like get_price_index or compare_providers, which cover market-level data rather than a private 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?

Implies usage by scoping to a private custom benchmark (a cb_ token), but never states when to choose this over price_benchmark, get_price_index, or update_custom_benchmark, nor any prerequisites. The reader must infer the private-vs-market distinction from the word 'custom'.

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 readOnly/openWorld annotations, it discloses the data semantics that matter: medians of current published prices only, no raw listings, group membership defined by product behavior rather than price, usage/one-time medians only where at least 3 listings publish them, and a 90-day price-index window. These are material behavioral facts not derivable from annotations or 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?

Purpose is front-loaded and the closing sentences route the agent efficiently. The middle is a single very long em-dash-chained sentence enumerating outputs, which is information-dense but harder to parse 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 no output schema, the description carries the full burden of explaining returns — buyer tiers, median entry monthly price with range, payment models, usage/one-time medians, and price-index change — and it does so thoroughly, while annotations cover the safety profile.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: it clarifies that query and group_id are alternative entry points and points to two concrete sources for group_id (agentery.com/aepi/groups and get_provider_profile's product_group), which the schema does not state.

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 precise verb+resource+scope: retrieve a product group's fair price broken out by buyer tier. It also distinguishes itself from search_providers, explicitly noting that individual listings are not returned. An agent can identify the tool's job 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?

Opens with an explicit trigger ('Use to check what a product of a given kind typically costs') and names an alternative path (search_providers) for candidate-level results. It does not, however, differentiate itself from adjacent siblings like price_benchmark or get_price_index, which an agent might reasonably confuse it with.

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 destructiveHint=false, so safety is covered. The description adds genuine context beyond that: the index base (100 = 29 Jun 2026), the warning that it is 'an index level, not a price', and what the response contains (1/7/30-day changes plus four tiers). It omits rate limits or freshness/caching behavior, keeping it 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?

Four sentences, front-loaded with the trigger, then output semantics, then disambiguation. Every sentence earns its place, though the parenthetical about base-100 and index-level is dense enough to slow a quick read slightly.

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

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

With no output schema, the description carries the return-shape burden and does so: it names the metric, base, change windows, tier breakdown, and provider_type sub-indices. Combined with the sibling routing, an agent has everything needed to call and interpret 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%, so the schema baseline is 3. The description nonetheless adds interpretation the schema doesn't: 'agent'/'mcp' produce a standalone index with its own base 100, and it explains why a buyer should pick one (agents and MCPs price and move differently). That is real added meaning over the enum 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 (returns the Agent Economy Price Index) and explicitly distinguishes itself from siblings get_price_index_history, get_group_fair_price, and price_benchmark. An agent can route correctly 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?

Opens with an explicit trigger ('Use when asked whether prices ... are rising or falling overall') and names the alternatives plus the conditions that select them (trend over time vs. specific product cost). Nothing is left 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 safety profile (readOnlyHint, destructiveHint=false), and the description adds real behavioral value beyond them: thin data returns insufficient_history rather than an invented series, points are index levels (base 100) never prices, and response_mode=full adds gap flags. It stops short of auth or rate-limit context, so not a full 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?

Front-loaded with the core purpose and packed with meaning; each clause carries distinct information (scope, defaults, failure mode, alternatives). The dense telegraphic style and mid-sentence enum shorthand make it slightly harder to scan than an ideal 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?

With no output schema and six fully documented parameters, the description still supplies the semantic frame (index levels, base 100), the failure mode, incremental-polling behavior, and sibling alternatives. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: tier selects one buyer tier, period windows the series, response_mode=full adds gap flags, and since enables incremental polling. The only miss is that provider_type is abbreviated to 'agent|mcp' while the schema enum lists seven values.

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

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

States a specific verb+resource ('show how AI agent and MCP prices have moved over time: the dated Agent Economy Price Index series') and clarifies the scope is index levels, not prices. It explicitly separates itself from siblings like price_benchmark and market_report, so an agent can route without opening other schemas.

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

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

Gives explicit when-to-use ('show how prices moved over time') and names alternatives with the condition that selects them ('For what one capability costs use price_benchmark or market_report'). Also notes the private custom benchmark path via benchmark_id. Nothing is left 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by enumerating what is returned (bio, source URLs, X-verification, entity type, community rating, structured profile) and flagging that the profile is only 'when available' – signalling partial results. It does not cover not-found behavior or auth constraints, keeping it 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?

A single sentence that front-loads the most consequential information (the alternative tool and when to prefer it) before the return-field list. No filler or restated title.

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

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

With no output schema, the description compensates well by listing the returned fields and the shallow scope relative to get_provider_profile. It omits error/not-found behavior and any note that both parameters are optional, which is the only remaining gap for a two-param read 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%, so both parameters are already documented in the schema; baseline 3 applies. The description adds the useful but small clarification that either a handle or a registration number can serve as the lookup key, but says nothing about precedence or whether both may be supplied together.

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... one provider') and immediately scopes it as the 'short public directory card', explicitly contrasting with get_provider_profile. An agent can distinguish this tool from its closest sibling 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 routing rule: 'For buying decisions prefer get_provider_profile... use this only for the short public directory card.' Both the alternative and the condition that selects this tool are named, and the lookup keys (handle or registration number) are stated.

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

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

Goes well beyond the readOnly/non-destructive/openWorld annotations: nulls mean the vendor published nothing and 'nothing is guessed', deployment carries evidence, reported_success stays null until 5+ distinct reporters in 90 days, and price_applies_to flags prices belonging to the vendor's platform rather than the connector. This is uncommon, high-value disclosure about data trustworthiness and liveness.

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-loads the purpose before the field inventory, and every clause conveys a distinct return-value or trust signal rather than filler. The size is large but largely justified for a no-output-schema data tool, though the single run-on sentence is dense and slightly hard to parse.

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

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

With no output schema, the description compensates by enumerating the returned fields (plans/prices with billing units, integrations, deployment, licence, connection methods, price_applies_to, product_group, reported_success) plus their null semantics. An agent knows both what it will get and when to trust 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 the single provider_id parameter is fully documented as coming from search_providers or compare_providers, so the schema carries the load. The description adds no further meaning about the parameter beyond what the schema states, which is the correct baseline of 3.

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 action (check one specific listing) and enumerates exactly what the profile contains (plans, prices, deployment, licence, connection methods), which clearly separates it from aggregate tools like search_providers and compare_providers. It does not, however, differentiate itself from the similarly named sibling get_provider, leaving ambiguity between the two.

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 concrete usage context: 'before recommending or connecting it' and routes follow-up action to report_outcome after actually using a listing. No explicit when-not or direct alternative is named (e.g. vs get_provider), so it stops short of full routing guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false), but the description adds non-obvious behavior: polling is free, it never repeats the work, and it imposes a poll cadence via poll_after_seconds. It also enumerates status/phase transitions and describes the result payload's structure.

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 leading sentence is well front-loaded and the polling/cost guidance is valuable, but the trailing enumeration of result subfields (evidence formats, facts assessed, conflicts) is dense and runs long. Most sentences earn their place, though the result breakdown could be trimmed.

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

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

With no output schema, the description carries the full burden of describing return values, and it does so thoroughly: status and phase enum values plus the structure of result (answer, short_answer, evidence, facts, conflicts). Nothing an agent needs to interpret the response 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% – the job_id format (rj_ + 12 hex) and its source are already documented in the schema. The description reinforces the request_research origin but adds no new parameter syntax or constraints, 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?

States a specific verb+resource ('Status and result of a research job') and explicitly ties it to its counterpart 'created by request_research', cleanly distinguishing it from the creation sibling. An agent can tell this is the retrieval/read half of the research workflow 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?

It makes the usage context clear (poll a job created by request_research) and gives concrete polling guidance ('poll no more often than poll_after_seconds'). It does not name when-not to use it or point to siblings like stop_research_updates, so it stops short of full alternative routing.

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. The description adds real value beyond that though: it discloses that marked test traffic is excluded and that results are research leads, not buyer counts, with 'few or none is normal while volume is low' and 'low = under-served' semantics. This is genuine behavioral context, so a 4 is warranted.

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 usage trigger is front-loaded and the return-field explanations each carry distinct meaning. It is dense but every sentence earns its place; only the trailing 'No arguments needed' is marginal.

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

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

With no output schema, the description carries the return-shape burden and does so thoroughly: it defines headline, weak_leads, information_requests, distinct_callers, raw_requests, and the similarity semantics. Combined with the interpretation caveats, an agent has everything needed to call and read 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 coverage is 100% and the schema fully documents rank (gaps vs hot), limit, and sector, so the baseline is 3. The description's only parameter-related statement is 'No arguments needed,' which is true (all optional) but adds no 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 states a specific verb (clusters, returns) and resource (requests seen on this server far from any paid provider), so the agent can tell what it produces. It distinguishes itself conceptually from market sizing ('not buyer counts or proof of a market-wide gap') but never names a sibling like demand_signals or market_report, so differentiation from the closest alternatives is left to inference.

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 opens with an explicit trigger: 'Use when a seller or investor asks which tasks people look for that few paid products serve.' That is clear when-to-use context, but it offers no exclusions and does not point to an alternative tool for adjacent questions, which is what a 5 would require.

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 read-only, closed-world and non-destructive, so the safety profile is covered. The description adds substantial behavioral context: fields are 'MEASURED' via a canonical pricing engine, with the exact statistics (median, mean, stdev, p25/p75, min–max, n), provider counts, and top competitors. It does not cover rate limits or auth, but the computational semantics are unusually well disclosed.

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

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

The purpose and the definition of 'market' are front-loaded, and the alternative tool is named last. The middle sentence is a long run-on enumerating every return field, but each clause conveys a distinct measured dimension rather than filler, so the density is mostly earned.

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

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

With no output schema, the description must explain what comes back — and it does, listing the pricing benchmark fields, neighbourhood counts, and top competitors. Combined with the read-only annotations and fully documented schema, an agent has nearly everything needed to call it correctly; pagination behavior in full mode is the only thin spot.

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 six parameters including the response_mode enum and cohort_ref reuse semantics. The description reinforces query format ('customer support chatbot') and the summary-vs-full distinction, but adds little syntax or semantics the schema does not already carry. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Deep-dive ONE market') and immediately defines the key concept — the market as the semantic neighbourhood of a natural-language query with NO fixed category. It differentiates itself from a category-based lookup and names the sibling (research_capability) that bundles market + pricing + shortlist, so an agent can route without opening a 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 clear context ('before building or investing') and an explicit alternative: 'For market + pricing + a ready shortlist in one call, use research_capability.' The cohort_ref/request_ref descriptions also imply a continuation workflow with price_benchmark. It stops short of a full when-not-to-use statement, but the routing guidance is concrete.

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

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

With only readOnlyHint/openWorldHint/destructiveHint annotations, the description carries substantial extra load: it enumerates the returned statistics (median, p25/p75, range, mean, stdev, n), the split by delivery type and buyer tier, the no-blending-across-units rule, the comparables-selection policy, and the resolved:false no-invention failure mode. It even frames the epistemic limits ('not a quote and not evidence of 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?

The first sentence front-loads the use case and example, and the dense remainder is largely load-bearing given there is no output schema. Some enumeration of return statistics and aliases duplicates what the schema already documents, so it is efficient but not maximally tight.

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, zero-required, no-output-schema tool this covers what an agent needs: what goes in, what comes back, how results are segmented, and what happens when no comparables exist. Nothing essential to a correct invocation is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds cross-parameter behavior the schema states only per-field, e.g. that provider_type/buyer_tier splits are never blended, that a thin pricing_unit returns its own observations rather than a flat-monthly substitute, and that a percentile requires >=5 comparable providers. Minor overlap with schema text (aliases) keeps it from a 5.

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 ('judge whether a price is fair or what a capability typically costs') with a concrete example, so the function is unmistakable. It never names or contrasts with the nearest siblings (find_market, market_report, compare_providers), so an agent must infer routing rather than being told it.

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

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

Gives clear usage context ('use to judge whether a price is fair'), the input shape (pass the capability as `query`), and follow-up instructions ('Set provider_type and buyer_tier when known', reuse cohort_ref from an earlier call). It stops short of explicit when-not rules or direct routing to alternative tools for adjacent 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?

The description adds substantial context beyond the annotations: retention of unchanged constraints, a 24 h expiry on references, and a privacy disclosure that Agentery sees only the request and correction, never the wider conversation. It does not, however, address the destructiveHint=true / idempotentHint=false profile, so an agent gets no confirmation that re-running mutates remembered task state rather than user data.

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 one dense paragraph with the primary trigger front-loaded, which is good. But the source enum is stated twice ('source: human, agent, follow_up' and later 'source is one of human, agent, follow_up'), and several trailing sentences describe how sibling task answers are formatted to be answered, which is not this tool's input contract.

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 stateful refinement tool with no output schema and only three parameters, the description covers what is returned ('the new answer plus what changed'), the reference lifecycle, and the privacy boundary, which is what an agent needs. Minor gap: nothing on failure modes or what happens if the request_ref has expired.

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%, so the baseline is 3. The description exceeds that by giving concrete correction examples ('must integrate with Slack', 'budget is $20/month'), explaining the request_ref origin, and disambiguating the source enum values ('the user's words' vs 'your assessment, default' vs 'follow_up').

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 gives a specific verb and resource: it re-runs an earlier search with changed constraints, keeps the others, and returns the new answer plus what changed. It names the origin tools (search_providers, research_capability) and the task-tool family, so an agent can place it among siblings. The core 'what it does' is stated mid-sentence rather than up front, which costs a point.

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 opens with an explicit trigger ('Use when an earlier search_providers or research_capability answer missed what was meant') and tells the agent exactly what to pass. It also routes the alternative case ('Pass the same request_ref to another task tool to continue the task there'), so both when-to-use and when-to-use-something-else are 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?

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false); the description goes well beyond by disclosing eligibility checks, the 48h correlation window, that unmatched reports are stored but unweighted, the 5-reporter/90-day aggregation threshold, the doubled rate limit at 5+ correlated reports in 30 days, and identity handling via x-agentery-key stored as a hash. This is unusually rich behavioral context.

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

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

The purpose is front-loaded in the first clause, and the dense follow-up sentences all bear on the agent's decision to call and how much the report will count. It is longer than typical but nearly every clause earns its place; minor tightening of the rate-limit and header details would push it higher.

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

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

With no output schema, the description carries the return/effect burden itself and does so: it explains what happens to matched vs unmatched reports, how aggregates surface (reported_success once 5+ reporters exist), and the contributor incentive. Nothing an agent needs in order to call this 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 the schema already documents all six parameters, including the outcome enum and the note char cap. The description adds only tangential context (which sibling tools return agent_id) rather than new syntax or format meaning, so 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 (report) and resource (the result of actually using a listed provider) and explicitly excludes a near-miss action (testing Agentery's connection or retrieval). An agent can tell this apart from siblings like search_providers or compare_providers without opening a 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 explicit when-to-use ('after ACTUALLY USING a listed provider for a task') and when-not-to-use ('testing Agentery's connection or retrieval does not establish that the provider worked'), plus the matching condition that makes a report count (a retrieval naming that provider within 48h). Nothing is left 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?

Goes well beyond annotations: discloses exactly what sources are read (vendor pages, code repository read-never-run, pricing page buttons), the answer taxonomy (yes/no/partly/unknown with quotes, URLs, observation dates), latency (~15 s), job de-duplication ('identical questions share one job'), and the epistemic caveat that findings are the vendor's own claims, not verification. The idempotentHint is confirmed by the shared-job statement rather than contradicted.

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 'Use when...' trigger, then behavior, then the polling fallback and the dedup caveat. Dense but every clause carries actionable information; 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?

No output schema exists, so the description carries the full burden of explaining returns, and it does: the yes/no/partly/unknown taxonomy with quotes, URLs and observation dates, plus the synchronous-vs-async timing model. Nothing an agent needs to call or interpret it 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 documents all three parameters. The description nonetheless adds real invocation value with concrete examples (provider_id flux_operator, requirement 'Is there a Helm chart for Kubernetes?') that show the expected granularity of a question, going slightly beyond the schema's generic examples.

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 (request product research on one listing) and pins the exact scope: one specific fact a profile does not settle. It is immediately distinguishable from get_research (polling) and search_providers (source of provider_id), which it names.

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

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

Explicit when-to-use condition ('buying decision hinges on one specific fact about one listing that its profile does not settle') plus the alternative path when the answer is not immediate ('otherwise call get_research with the job_id after poll_after_seconds'). Both the trigger and the fallback are spelled out.

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 safety is covered. The description adds genuinely useful behavior beyond that: matching is functional with no fixed categories, the price band comes with a sample size n, and compare_ready handles are produced as the hand-off artifact for compare_providers. It stops short of describing pagination or response-size behavior, so not a full 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 purpose and return shape are front-loaded in the opening clause, and the exclusion plus preferred alternative follow immediately. The trailing 'Accepts `task` (aliases: query, q)' duplicates what the schema already states and is the one sentence that does not earn its place.

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

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

With no output schema, the description carries the burden of return-shape disclosure and does so by listing the concrete fields produced (price range/median with n, market_position values, compare_ready handles, suggested_alternatives). Given 10 parameters and four enums, the remaining input options are fully covered by the 100% schema coverage, so the gap is minor.

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

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

Schema coverage is 100%, so the baseline is 3 and every enum, default and alias is already documented. The description still adds cross-parameter meaning: it names `task` with its aliases and clarifies that compare_ready output is the input contract for compare_providers, which the schema itself does not express.

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+resource ('quick first overview of a buying task in one call') and enumerates exactly what is returned: closest-matching listings matched on function (no fixed categories), price range and median with n, plus a shortlist with observed prices, market_position and compare_ready handles. It explicitly distinguishes itself from compare_providers ('It does not run the comparison'), so an agent can separate it from siblings 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?

Names the precise condition for use ('quick first overview') and the alternative path when the goal differs ('For careful selection prefer search_providers → get_provider_profile → compare_providers'), including the excluded action ('does not run the comparison'). Both when-to-use and when-to-use-something-else are stated explicitly.

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 establish readOnly/non-destructive/openWorld=false, and the description adds substantial behavior beyond that: the exact result shape (fit label with named mismatch, delivery type, price status), the semantics that 'unknown is never free', per-result requirement verification with unverified items marked unknown, and the no_match honesty guarantee. That is the kind of context an agent cannot derive from structured fields.

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

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

The trigger and the primary workflow routing are front-loaded, and the return-shape sentence is dense but information-bearing. It is longer than strictly necessary for a search tool and could be trimmed, but nearly every clause carries a distinct operational fact.

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 10 parameters including a nested filters object, the description carries the return-format burden and does so fully: ranked candidates, fit labels, price status, links, and the no_match case. Combined with 100% schema coverage on inputs, an agent has everything needed to call and interpret this 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%, so the baseline is 3: enums, ranges and defaults are all documented in the schema itself. The description reinforces a few semantics (requirement checking per result, price-status meaning) but adds little parameter-level detail the schema does not already carry.

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 (search/shortlist AI products, agents, MCP servers, APIs) and gives concrete example queries, which makes it immediately distinguishable from siblings like get_provider_profile (deep dive) and compare_providers (comparison). It also scopes the input domain ('product job you are buying') and explicitly excludes Agentery meta-questions.

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 an explicit trigger ('Use when someone wants to find or shortlist...') and then routes downstream: 'open strong ones with get_provider_profile and compare finalists with compare_providers.' It also states the thin-coverage behavior (no_match, never padding), so the agent knows the failure mode rather than inventing results.

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 largely covered. The description adds genuinely useful context beyond that: it clarifies the destruction is scoped to the watch/subscription and that the result is not lost ('stays retrievable with get_research'), which tempers the destructive hint. Remaining gaps (auth requirements, whether a stopped watch can be resumed) are minor.

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?

One sentence, zero waste, front-loaded with the action and followed by the consequence/alternative in parentheses. Every clause 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, no-output-schema tool, the description covers what the tool does, what it does not destroy, and how to retrieve the result. It could have stated where job_id comes from (request_research), but nothing essential 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 description coverage is 0% for the single job_id parameter, so the description carries the burden of explaining it. It references 'a research job' implicitly, but adds no format, source, or provenance guidance for job_id, so it neither compensates for the gap nor misleads. Baseline 3 for a single obvious identifier.

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 ('Stop watching') and resource ('a research job'), and immediately distinguishes the operation from deletion by noting the result stays retrievable via get_research. An agent can tell it apart from get_research and request_research 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?

The description implies the usage context (you have an active watch on a research job and want to end it) and explicitly routes to get_research for retrieving the result afterward. It does not state when-not to use it or what happens to the underlying job, but the context is clear enough to act on.

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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial context beyond them: the ranking basis, the fields each result carries (price, liveness, upvotes, how_to_connect, deployment), and the important caveat about empty cheaper_only responses. This is genuinely useful behavioral disclosure.

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

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

Front-loaded with the core purpose and ranking basis, and every sentence carries information. It is dense to the point of being run-on, with heavy parenthetical asides and a slightly redundant second mention of how_to_connect, minor costs against otherwise tight structure.

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

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

With no output schema, the description carries the burden of describing return values and does so (price, endpoint liveness, upvotes, how_to_connect, deployment, install/repository). Combined with the cheaper_only caveat, an agent has enough to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema already documents limit and cheaper_only thoroughly. The description adds the alias mapping for agent_id ('aliases: handle, id'), which is meaning beyond the schema, plus elaboration on cheaper_only's comparison semantics.

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

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

States a specific verb and resource ('Find related alternatives to a known provider') and explains the ranking mechanism (embedding nearness to the provider's own profile, explicitly NOT category lookup). It also distinguishes itself from siblings compare_providers and research_capability, which surface the same substitutes in a different context.

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?

Explains that substitutes are also surfaced inside research_capability and compare_providers and gives interpretation guidance for cheaper_only (empty responses may mean a missing/incompatible reference price, not absence of alternatives). It lacks an explicit 'use this when / not when' statement versus those siblings, so the routing decision is still partly inferential.

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 the mutation profile (readOnly=false, destructive=true, idempotent=false), and the description adds genuinely non-obvious behavior: a NEW immutable version is created, the previous version remains fully reproducible, and the response reports change-impact on median/quartiles/index. It does not, however, mention authorization requirements or failure modes (e.g., invalid member ids).

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

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

Three short sentences, each carrying distinct information (operation, side-effect semantics, return content, required param), with the core action front-loaded. 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 no output schema, the description usefully describes the return value and the versioning side effect, and it flags the required argument. It is nearly complete for a 4-param mutation tool, lacking only error/permission behavior.

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

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

Schema description coverage is only 25% (just benchmark_id), so the description must compensate; it maps the three intent parameters to their purpose (add/remove members, rename) and explicitly says to pass benchmark_id. The remaining gap is value format — it never says whether add/remove take member ids, names, or tokens.

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 (a custom benchmark), and its immutability/versioning framing clearly distinguishes it from create_custom_benchmark, get_custom_benchmark, and delete_custom_benchmark without the agent needing to open 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?

Usage is implied rather than stated: requiring `benchmark_id` signals this operates on an existing benchmark (not creation), but there is no explicit when-to-use, when-not-to-use, or named alternative for editing vs. recreating vs. deleting. The agent can infer the niche but is not routed.

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