Whirrwork

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the bar is lower. The description still adds real context beyond them: prices are USD-normalized, results are facts without ratings, and a 'last checked' freshness signal is returned — meaningful for judging the comparison output.

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 sentences, front-loaded with the core scope and the item cardinality, followed by a short constraint ('Facts only, no ratings'). No filler or redundancy.

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 structure needn't be spelled out, and the description is sufficient to call the tool correctly with ids and country. The only gap is the undocumented use_case parameter, which leaves one of three inputs semantically opaque.

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

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

Schema coverage is only 33%: country is well documented in the schema, but ids and use_case are not. The description restates the 2-10 id bound and ties the comparison to country coverage, yet adds nothing about how use_case alters the comparison.

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 ('Side-by-side comparison of 2-10 providers') and enumerates the compared facets (coverage, engagement models, prices, HQ, contact routes, shared jobs, last checked). This clearly separates it from single-provider siblings like get_provider and from discovery tools like find_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?

Usage is implied by the comparison semantics and the 'Facts only, no ratings' clause signals it is not a recommendation engine, but there is no explicit when-to-use versus get_provider/find_providers guidance and no stated prerequisites such as needing valid provider ids.

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, idempotent, non-destructive, closed-world), and the description adds real substance beyond them: defaults are sourced or flagged as assumptions via input_sources, and projections are modelled estimates that must be quoted as a range rather than a single year. It says nothing about auth, rate limits or latency, which keeps 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?

Scope is front-loaded in the first sentence and the caveats sit at the end, with examples last. The enumeration of return fields (NPV, verdict, tornado, crossover range) is largely redundant given an output schema exists and is the main thing that 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?

For a moderately complex tool with a nested inputs object and an output schema, the description covers the comparison model, the sourcing discipline and the projection caveat an agent needs to call and report correctly. Nothing critical is missing, though the country/region lists are duplicated with the schema.

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

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

Schema coverage is 100%, so the schema already documents every parameter, including the 0-1 fraction convention and the regional preset codes. The description only restates the 22-job/8-country bounds and shows a few example overrides without explaining any of the ~33 nested input fields, so it adds little 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?

A specific verb and resource: cost comparison of human labour against four robot options (buy, lease, RaaS, service provider) across 22 jobs and 8 countries. It is clearly distinct from siblings such as estimate_cost, compare_providers and get_prices because it names both the comparison axis and the job/country scope.

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?

Three concrete example invocations make the expected call shape and typical scenarios obvious, and the note on projections tells the agent how to present results. It never states when to prefer this over estimate_cost or compare_providers, so there is no explicit exclusion or 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?

Despite annotations already declaring read-only/idempotent/non-destructive, the description adds substantial behavioral detail: exact unit conversion pairs, region-matching preference, dated ECB currency conversion, the return shape including basis rows (source_url, as_of, region match) and caveats, and the null-with-reason failure mode. The 'never invents a number' guarantee is exactly the kind of trust signal an agent needs.

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?

Dense but front-loaded: the core operation and conversion policy come first, then return shape, then failure behavior, then an example. Every element serves a purpose, though the single run-on opening sentence could be split for readability.

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 operation, conversion and rounding policy, region preference, return contents, and failure semantics, plus a concrete example. Even though an output schema exists, the extra narrative about basis rows and caveats makes the agent fully prepared to call and interpret the result.

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

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

With 80% schema coverage the baseline is 3, but the description adds genuine meaning beyond the schema: currency is converted at a dated ECB rate, country drives region-match preference, and units are converted exactly across acre/hectare, sq ft/m², mile/km. The worked example also clarifies how the parameters combine.

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 framing ('Arithmetic on published prices: unit price × quantity'), making clear this computes an estimate rather than retrieving raw rows. It distinguishes itself implicitly from retrieval siblings like get_prices or get_stat by emphasizing arithmetic and basis rows, though it never names those alternatives.

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 usage context is implied (you need a cost estimate for a use case) and the fallback behavior (estimate=null with reason when no benchmark fits) tells the agent what to expect. However, there is no explicit 'use this instead of get_prices when…' routing among the many pricing siblings, leaving the agent to infer when this tool is preferred over raw price lookups.

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, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-schema behavior: the exact relevance ranking order, that HQ location is not a service area, that coverage is country-level unless regions are published, and that AND-combination applies across filters. Return-field enumeration overlaps the output schema, which caps it at 4.

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 ranking chain is a single dense but scannable sentence. The two JSON examples earn their place by demonstrating AND-combined filters. Slight density in the results sentence keeps it from 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?

For a 15-parameter search tool with annotations and an output schema, the description covers the hard parts an agent would otherwise get wrong: ranking, coverage level, HQ-vs-service-area, and filter combination. Pagination and sort semantics are left to the schema, which is acceptable but leaves a minor 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 coverage is 73%, and the description adds real meaning on top: the country/region/hq_country interplay and its effect on ranking, the semantics of worldwide-only providers in relation to include_global, and coverage granularity. It does not explain sort option meanings or limit/offset pagination behavior, so it is not fully compensatory.

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 states a specific verb and resource (shortlist providers) and immediately scopes it to a job and place. The ranking chain and result-field list make the tool's output shape unmistakable. It does not explicitly name the boundary with siblings like get_provider or compare_providers, so it falls 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?

Two concrete invocation examples (use_case+country, and use_case+country+region+engagement_model) plus the note that filters combine with AND give implied usage. However, there is no explicit guidance on when to prefer this over get_provider or compare_providers, nor any stated 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?

Annotations already cover read-only, idempotent, non-destructive, closed-world. The description adds real behavioral context beyond them: the data is append-only and never overwritten, the trend is defined as change_pct between first and latest, and observed_at vs as_of are distinguished. It does not mention the limit/cap behavior (default 100, max 500), which is the remaining gap.

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

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

Three dense sentences with the core claim front-loaded. The parenthetical about append-only and the trend definition earn their place; the trailing instruction about single-observation series is slightly meta but still useful.

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 structure does not need explaining, and the read-only annotations cover safety. What an agent still lacks is guidance on result size/pagination and the role of the use_case parameter, but the essential semantics for calling it correctly are present.

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

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

Schema coverage is only 40% (limit, provider, and use_case are undocumented in the schema). The description clarifies 'series' as a filtered view and explains time semantics relevant to 'since', but leaves 'limit' and 'use_case' unaddressed. It also says 'for a job and/or provider' while the schema exposes 'use_case' rather than a job parameter, which mildly muddies the mapping.

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: every recorded price observation for a job and/or provider, grouped into series with a trend metric. That grouping/trend framing implicitly separates it from get_prices and compare_providers, but no sibling is named explicitly.

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

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

The only directive is about output handling ('If every series has one observation, say so'), not about when to choose this tool over get_prices, compare_providers, or estimate_cost. No prerequisites, no when-not-to-use conditions are given.

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, idempotent and non-destructive, so the description correctly spends its words elsewhere: it discloses that every row carries source_url and as_of, that conversions are clearly labelled and FX-sourced, and that results are benchmarks rather than binding quotes. That provenance and caveat context is genuinely additive beyond the 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?

Four compact sentences, front-loaded with the resource and scope before the conversion and caveat clauses. The telegraphic fragments ('Benchmarks, not quotes.') are dense rather than wasteful, though the clipped style costs a little readability.

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 shape needn't be explained, and the description covers scope, provenance and conversion behavior. The remaining gap is behavioral detail on three undocumented parameters (limit paging, currency filtering, include_providers) for a six-parameter tool with no required 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 coverage is only 33%, so the description should compensate more than it does. It does add real meaning for convert (a labelled conversion with FX rate, date and source) and covers provider ('or for one provider') and use_case ('for a job'), but limit, currency and include_providers are left entirely to 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 a specific resource and scope: current sourced prices for a job or for a single provider, with provenance (benchmarks + provider-published). It implicitly contrasts with get_price_history via 'Current', but never names that sibling, so differentiation is inferred rather than explicit.

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

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

'Benchmarks, not quotes' is a useful exclusion that steers quote-seeking agents toward the RFQ flow, but the description never says when to use this versus get_price_history or estimate_cost, both of which are close siblings. Usage is implied by the word 'current', not 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?

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds provenance context (sources, last-checked date, prices with USD), which hints at data freshness, but says nothing about pricing variability, country-dependent results, or errors for unknown 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?

A single front-loaded sentence that leads with the resource and scope before the field list; the enumeration is dense but each item earns its place as a reason to call the tool.

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 long field list partly duplicates structured data, while the genuinely missing pieces — the id key format and the country parameter's effect — are left out. Adequate for a read-only getter but incomplete on inputs.

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

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

Schema coverage is only 50% and the description contributes nothing about either parameter. It never states that lookup is keyed by provider id (e.g. 'sky-elements' slug) nor that the optional country parameter changes the buyer-country context, so the undocumented id parameter and the country semantics must be inferred entirely from the schema.

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

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

States it returns the full public profile of a single provider and enumerates the concrete contents (website, HQ, service regions, jobs, robot types, prices, contact routes). The singular 'one provider' implicitly separates it from find_providers and compare_providers, though it never names those siblings.

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

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

Usage is only implied: an agent can infer this is the detail-lookup step after a search, but the description never says when to call it versus find_providers or compare_providers, nor any prerequisites.

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 (readOnly, idempotent, non-destructive, closed-world), so the description adds value by disclosing the required access-key credential and the fact that a status history is returned alongside the current state. It stops short of describing failure behavior for an invalid key or the response shape.

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 sentences, no filler. What the tool returns and its lifecycle values come first; the credential prerequisite follows. 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?

With an output schema present, return values need no prose, and the description still flags the status history. Credentials, lifecycle states, and the upstream dependency on submit_rfq are all covered; only error/invalid-key behavior is left unstated, which is minor for a read-only lookup.

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% – the only structured hint is an example value for 'id'. The description compensates well by explaining where both parameters come from: the id of the submitted RFQ and the key extracted from the 'key=' portion of status_url returned by submit_rfq.

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 the specific resource ('a submitted RFQ') and what it returns (status plus status history), even enumerating the lifecycle states. It is clearly distinct from submit_rfq, which it references as the credential source, though differentiation from the other siblings rests on the tool name rather than the description.

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 prerequisite is stated explicitly ('Needs the id and the access key returned by submit_rfq'), which is real usage guidance for the submit-then-check flow. However, no alternative or when-not-to-use condition is given, so selection guidance is only implied by the workflow.

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

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

Beyond the annotations, the description explains what the template contains, including required flags, formats, extra.{key} checklist items, regulatory notes, and an example. That is useful behavioral context for an otherwise simple read-only tool, though it does not discuss failure modes or response structure in detail.

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

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

The description is dense but well structured: it front-loads the template contents, explains the buyer workflow, and names the next tool call without 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 the description does not need to document return values, and the annotations cover safety behavior. The main remaining gap is the lack of explicit explanation for the required use_case input, though the schema example and 'job-specific' wording make the intent recoverable.

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

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

The language parameter is documented in the schema, but use_case has no schema description and the tool description only indirectly implies it via 'job-specific' template content. With 50% schema description coverage, the description provides some contextual meaning but does not fully compensate for the undocumented required parameter.

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

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

The description clearly identifies the resource as the RFQ template fields to collect from a buyer, and states the scope: core fields, job-specific checklist, regulatory notes, and a filled example. It also distinguishes the tool from submit_rfq by explicitly placing it before submission.

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 workflow guidance: use this before submit_rfq, ask the buyer for the fields, then call submit_rfq. It does not state when not to use the tool, but the primary usage context is unambiguous.

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

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

Annotations already cover read-only/idempotent/closed-world, and the description goes well beyond them: it discloses conditional content ('verbatim source passage (when licensing allows)') and an explicit CC BY 4.0 attribution obligation with the exact required string. That licensing obligation is a real behavioral constraint an agent must honor that no annotation conveys.

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 front-loaded sentence that identifies the resource first, then the returned fields, then the licensing terms. Dense but nearly every clause carries information; only the full enumeration of citation formats is mildly padded given an output schema exists.

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 listing return fields is largely redundant, but the description adds value the schema cannot: the conditional verbatim passage and the mandatory attribution text. What remains missing is discovery guidance (how to get a valid slug), which is the main completeness 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 0% for the single 'slug' parameter, so the description carries the burden; it only says 'by slug' without defining slug format, accepted patterns, or error behavior for an unknown slug. The schema's two examples partially compensate, keeping this at minimum-viable rather than failing.

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: retrieves one Whirrwork Research statistic by slug, and enumerates the payload the caller gets back. It is clearly distinguishable from search_stats by the singular 'one ... by slug' framing, though it never names the sibling that finds slugs.

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 never says when to use this tool versus search_stats, get_use_case, or any other sibling, nor does it state the precondition that a slug must already be known and where to obtain one. Only the phrase 'by slug' hints at usage context.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, but the description adds real behavior: prices arrive with source_url, as_of and USD conversion, price-history counts are included, and providers are ranked by who serves the given place with a stated reason. Those are meaningful traits beyond the annotations; only auth or failure behavior (invalid id, missing country) is left unsaid.

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, front-loaded with "Everything about one job:" and then a scannable list, closing with the one actionable instruction. It runs long and several list items duplicate what the output schema already declares, which keeps it short 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?

With a complete input schema, an output schema, and full annotations, the description only needed to convey scope and the country/region effect, which it does. It omits edge behavior (unknown id, provider list when no country is supplied), a minor gap given how much is carried structurally.

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, but the description adds semantics the schema lacks: country and region are optional inputs that change provider ranking and the ranking includes a rationale. It also frames country as the primary geographic argument with region as the finer-grained option, which is not spelled out in the schema.

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

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

The description enumerates exactly what a single-job lookup returns (robot types, purchase models, prices, RFQ checklist, providers) and how the result changes with country/region, so an agent knows this is the full-detail fetch for one job id. It does not, however, distinguish itself from siblings that surface overlapping data (get_prices, find_providers, get_rfq_template) whose content it bundles, leaving the boundary implicit.

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 only implied: the id parameter's schema note pointing to search_use_cases and the "Pass country... to rank providers" sentence imply 'use this after you have an id and want everything about it.' There is no explicit when-to-use/when-not statement or named alternative for narrower needs like a price-only or provider-only lookup.

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, idempotentHint, and closed-world, so the safety profile is covered. The description adds the useful behavioral fact that the result set is a fixed, small enumeration (20) suitable for scanning, but says nothing about ordering or whether counts are live.

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, front-loaded with the returned artifact and followed by the usage condition. 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?

Output schema exists and annotations are rich, so the description only needs to convey scope and intent, which it does. Minor gap: it doesn't clarify whether categories are stable identifiers worth passing to other tools.

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 `language` parameter already documents the enum, the English-authoritative caveat, and the default. The description adds no parameter-level information, 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 the resource precisely (job categories, count fixed at 20) and the returned payload (use-case counts). It distinguishes implicitly from search_use_cases/get_use_case by framing the tool as a browse-level overview rather than a lookup, though it never names a sibling.

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?

"For browsing when the buyer is vague" gives a concrete triggering condition and implicitly routes away from search/estimate tools when no query term exists. It stops short of naming the alternative to use once the buyer becomes specific.

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, idempotent, non-destructive, and closed-world, so safety needs no restating. The description adds useful output composition (service-area providers, sub-region providers, headquarters providers, worldwide count), but says nothing about ordering, pagination, or how the optional country filter changes scope.

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 sentences with the output breakdown front-loaded and the use case trailing. Dense but every clause carries information; only the semicolon-heavy listing slightly slows parsing.

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, rich annotations, and one optional parameter, the definition is nearly sufficient: the agent knows what the returned coverage categories mean and the safety profile. The remaining gap is scoping behavior when the country parameter is omitted versus supplied.

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 optional parameter is documented there as "just this country." The description only implies the default all-countries behavior via "For each country," adding marginal meaning beyond the schema, 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?

The description states precisely what the tool returns: per-country breakdowns of three provider categories plus a worldwide count. That's a clear resource and output shape, though it never explicitly contrasts with siblings like find_providers or compare_providers, so an agent must infer the difference.

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 tell the buyer honestly how well their country is covered" gives a use case, so usage is implied rather than left blank. But no alternative is named and no when-not-to-use condition is stated, so routing between this and find_providers 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 read-only, idempotent, non-destructive and closed-world, and the description is consistent with that fixed dataset. It adds useful behavioral context beyond the annotations: what each result contains (figure, unit, scope, source chain, Wayback archive, verification dates, permanent URL) and the quoting/confidence preference. No rate limits or pagination behavior is mentioned, keeping it at 4.

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 dataset scope, then result shape, then the get_stat hand-off and examples. It is a bit dense in the middle field list, but each clause carries information an agent needs; 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?

An output schema exists, so the heavy enumeration of result fields is somewhat redundant, but the description still supplies the confidence/source-type semantics and quoting guidance an agent needs to use results correctly. The only gap is that limit and the unfiltered-search behavior aren't clarified.

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 40%; query and topic are documented in-schema, while confidence, source_type and limit lack descriptions. The description partially compensates by explaining confidence semantics ('prefer high-confidence primary sources') and implying topic filtering via the 'topic="labour"' example, but it never clarifies the limit parameter or the confidence/source_type enum meanings beyond what the enum itself 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 (search) and resource (citable robot statistics), enumerates the domains covered and the fields each result carries, and names the sibling get_stat for the deeper-detail path. An agent can distinguish it from get_stat or search_use_cases 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 concrete query examples and explicitly routes to get_stat when the verbatim quote or citation is needed, plus guidance to prefer high-confidence primary sources. It stops short of stating when NOT to use the tool (e.g., vs search_use_cases or the provider tools), so not a full 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 readOnly=true, idempotent=true, destructive=false, so the safety profile is covered. The description adds real value beyond them: multilingual query/text support, that it returns not just use cases but also matching providers and guides, and the id-to-detail chaining pattern. It doesn't discuss ambiguity in matching or empty-result 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?

Front-loaded with the core purpose and next step in the first two clauses; no wasted preamble. The four inline examples plus the two already in the schema's query examples are mildly redundant, but they usefully demonstrate cross-lingual input.

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 available, the description doesn't need to enumerate return fields, yet it summarizes them helpfully and covers the follow-up call. The only gap is any hint about the country filter or result-count limit for a 4-parameter search 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?

At 75% schema coverage the schema already documents query, country, and language, and the description largely restates the natural-language/multilingual angle rather than adding syntax detail. The country filter and limit cap are never mentioned in the description, and "12 languages" conflicts with the 13-value language enum, a small but real inconsistency.

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

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

States a specific verb and resource ("Find the robot job (use case)") plus scope ("in plain words and in any of 12 languages"). It is clearly distinguishable from siblings like find_providers, list_categories, and search_stats, and it explicitly names get_use_case as the follow-up.

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?

"Start here, then call get_use_case with the best id" gives an explicit entry point and next step in a multi-tool workflow. It stops short of saying when to prefer find_providers or compare_providers instead, so the routing is clear but not exhaustive.

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

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

Goes well beyond the annotations: it discloses the full lifecycle (stored, auto-matched by job + country, human-reviewed before forwarding, nothing emailed automatically) and the private status_url/access key the caller must retain. That is exactly the operational context an agent needs and cannot infer from readOnlyHint/destructiveHint/openWorldHint.

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 consent precondition and the matching/review behavior, then the return contract, in a tight two-sentence block. The sentences are long and clause-chained via semicolons, which costs a little readability but wastes no words.

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 20-parameter write tool, the description covers the consent gate, matching logic, human review, test mode, and handoff to get_rfq_status; the output schema already documents the return shape, so no further return-value detail is needed. Nothing critical to calling 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?

The description adds real meaning for two parameters — it explains why 'job' and 'country' matter (they drive matching) and clarifies test-mode behavior — but roughly half the 20 parameters (budgets, dates, contact fields, use_case_id, agent_name) get no treatment in the description or schema. With 50% schema coverage, this is adequate but leaves gaps.

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 (submit a request for quotes) and immediately narrows the scope with the consent=true precondition and 'real buyer' qualifier. It is clearly distinct from siblings like get_rfq_status and get_rfq_template, which are named as the follow-up and the field-source respectively.

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 preconditions (buyer must be real and have consented) and a clear opting signal for non-production use ('Use test=true for testing'), plus routing to get_rfq_status for follow-up. It stops short of stating when NOT to submit, e.g. what to do if consent is absent.

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