AIBuilder Marketplace: software pricing dossiers

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

Annotations already declare a safe, idempotent, read-only operation, so the burden is light; the description nonetheless adds rich behavior beyond them — affiliate disclosure on the vendor handoff, a fixed order that never uses commission, a share_url, summary_markdown, and depends_on facts for later re-checking. It also discloses a methodology rule ('documented only from vendor's own pages, never as tested by us'). Gaps remain around rate limits or pagination, but coverage is well above the annotation baseline.

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

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

The purpose is front-loaded in the first clause, which is good, but the remainder is a dense, semicolon-chained run-on that mixes return-shape, methodology, and setup-rule detail into one paragraph. It earns most of its length yet is hard to scan.

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 3 low-coverage parameters, the description carries the load and does so substantially: it enumerates the return payload (per-candidate check with evidence, cheapest fitting cost, test results, unknowns, vendor handoff), the summary/share artifacts, and the setup_check interplay. Missing only clarification of 'question' and product_ids format.

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%, so the description must compensate. It does explain requirements.modules in detail ([{id, role}], setup semantics including per-currency costs and budget), but leaves 'question' entirely undefined and only bounds product_ids by cardinality (1-6) without format guidance. Partial compensation only.

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 clear verb ('build') and resource ('purchase file/dossier') for 1 to 6 candidate products against shared requirements, and anchors it via 'same fields as check_choice'. It references siblings (check_choice, setup_check) by name, giving partial differentiation, though it never states outright why to pick this over compare_products or check_choice.

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 through the '1 to 6 candidates' scope and the conditional rule about requirements.modules naming a setup (read setup_check for the verdict). There is no explicit when-to-use vs. when-not or a direct comparison to the sibling tools that also produce comparisons, so the agent must infer 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 establish that this is a read-only, idempotent, non-destructive operation, but the description adds substantial behavioral detail beyond them. It specifies the possible per-requirement statuses, the overall outcomes, and the rule that 'unknown never counts as a fit', which is critical for interpreting results correctly.

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

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

The description is front-loaded with the core purpose and packs a large amount of necessary detail into compact form. It is dense but largely earns its length, though the long inline enumeration of requirements could be structured more readably.

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

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

Given the absence of an output schema and the generic input schema, the description does a strong job covering input requirement fields, result statuses, and outcome categories. It does not describe the exact return shape or how evidence is structured, but it provides enough semantic context for an agent to invoke and interpret the 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?

With schema description coverage at 0% and a generic nested requirements object, the description carries the full burden of parameter documentation. It enumerates the optional requirement keys, gives allowed values for billing and avoid_cost_traps, provides examples for service, and clarifies that each requirement is optional.

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

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

The description clearly states a specific verb and resource: checking a software choice against requirements before buying. It is distinguishable from cost-comparison siblings by its requirements-evaluation scope, but it does not explicitly name or contrast itself with alternatives such as check_offer_eligibility or compare_offer_costs.

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

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

The phrase 'before buying' gives clear context for when to use the tool, implying a pre-purchase validation step. However, it provides no explicit exclusions or guidance about when to use sibling tools instead.

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 the safe-read profile (readOnly, idempotent, non-destructive, closed-world). The description adds real value beyond that: it enumerates the outcome states (matches, does_not_match with reasons, needs_confirmation for missing info/unconfirmed offers/case-by-case pilots) and discloses what the vendor did not state, plus the 'not a checkout guarantee' limitation.

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 dense but front-loaded paragraph: purpose first, then output shape, then the caveat. Every clause carries information, though the nested parenthetical for needs_confirmation is slightly heavy.

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 correctly carries the burden of explaining the three return states and their reasons, plus the vendor-omission caveat. It never addresses error behavior or what happens when offer_id is unknown, which is the remaining 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% and the situation object is a wide-open anyOf(object/null) with additionalProperties true, so the schema gives the agent almost nothing. The description compensates by spelling out the situation shape (customer: new|existing, plan, billing: monthly|annual|biennial), but offer_id is left unexplained and no field is marked required or optional.

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

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

Specific verb ('Check whether an offer fits') plus resource (offer) and the buyer-situation inputs it evaluates. An agent can tell this apart from cost-oriented siblings like compare_offer_costs or estimate_cost, though 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?

Usage is implied by the framing ('whether an offer fits a buyer's situation') and the caveat that a match is not a checkout guarantee, which hints this is an evaluation, not a purchase step. However, no when-to-use versus when-not conditions or named alternatives 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that by disclosing the result shape and the conditions under which no result is produced (credits, a longer trial, unknown duration).

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

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

Three sentences, scope stated first, no filler. The middle sentence is dense but earns its place by defining the key nested prices map.

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

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

There is no output schema, and the description partly compensates by outlining the return fields and non-computable cases. However, with 0% schema coverage and a nested situation object, several parameters remain unexplained, leaving gaps for a moderately complex 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 0% across 5 params, so the description must compensate. It explains the semantics of prices (offer_id -> monthly buyer price ex-offer, same currency as vendor) and ties billing/terms to the comparison, but leaves months, billing defaults, and the situation object entirely undocumented.

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 (compare) and resource (offer costs) with an explicit scope: '1 to 3 offers on the same billing term and period.' This distinguishes it from generic siblings like compare_products or estimate_cost, though it never names a sibling directly.

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

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

The description implies the usage context (comparing a small set of offers on identical terms), but offers no explicit when-to-use vs. when-not guidance and never points to alternatives such as estimate_cost or cost_at_growth.

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, so the safety profile is covered. The description adds genuinely useful behavior the annotations don't: every requested id is returned found or not (no error on misses), and 'units' triggers a cheapest-fitting-plan cost computation gated on price rules.

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, zero filler, and the core purpose plus cardinality is front-loaded. Each sentence carries distinct information.

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 conveys return semantics (missing ids still returned, conditional cost output). The one notable gap is the defaulted 'billing' parameter, which is never addressed.

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 0% schema description coverage, the description must carry the burden. It explains product_ids (2-6, always echoed) and units (adds cheapest fitting plan cost), but billing is left completely unexplained in both schema and description.

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 ('Compare'), resource ('products'), and an explicit cardinality bound ('2 to 6'). It is clearly distinguishable from compare_offer_costs by the 'products' resource, though it never names a sibling to sharpen the boundary.

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

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

It states behavior when optional 'units' is supplied but gives no when-to-use guidance or explicit alternatives. An agent must infer on its own whether to reach for this versus get_product or compare_offer_costs.

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 needs no restatement. The description adds the shape of the result (cheapest fitting plan per size, plus plan-change breakpoints), which is useful since no output schema exists, but it says nothing about assumptions, defaults, or how the computation is bounded.

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 tight sentence with zero filler, front-loaded on the core behavior and then the secondary output (breakpoints). Nothing repeats the tool name or annotations.

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 three-parameter analytical tool with no output schema and zero parameter documentation, the description covers the conceptual output but leaves the inputs and usage context for the agent to guess. Adequate as a one-line summary, insufficient to invoke confidently.

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% across three parameters, so the description carries the full burden. 'At each size' loosely hints that points are team sizes, but billing (annual vs monthly) and product_id are left completely undefined, and the default annual billing is unmentioned.

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

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

States a concrete computation: cost across team sizes plus the crossover points where the best plan changes. The 'as a team grows' framing distinguishes it from siblings like estimate_cost or compare_offer_costs, which are single-point comparisons. It stops short of naming an alternative explicitly, so it is clear but not sibling-differentiating by name.

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 for growth-curve questions rather than a one-off cost estimate. There is no when-to-use statement, no stated prerequisites, and no pointer to estimate_cost or compare_offer_costs for simpler cases.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior. Beyond that, the description adds genuinely useful behavior: it will not interpolate between published price steps and returns a range instead, and it explicitly reports when price rules are absent. Those are non-obvious response behaviors that the annotations do not cover.

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 tight sentences, front-loaded with the core purpose, then return contents, then scope and the range caveat. Dense but no filler; every clause carries information.

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 7-parameter, 0%-coverage schema with no output schema, the description usefully explains the return shape and price-rule caveat. It still leaves two parameters (plan_id, include_personal) and the exact units semantics undocumented, which is a real gap given that no structured field compensates.

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%, so the description carries the burden. It meaningfully maps units ('team size, or companies/orders per the product's axis') and billing ('monthly or annual'), and mentions usage and add-ons implicitly. But plan_id and include_personal are never explained, and the meaning of the axis-switching for 'units' is left vague.

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

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

States a concrete verb+resource ('Cost of each plan at a team size') and enumerates the return contents (monthly equivalent, amount billed per period, commitment, minimums, add-ons, usage). It also scopes itself ('Only for products with price rules'). However, it never names or contrasts with siblings like compare_offer_costs or cost_at_growth, so an agent must infer the boundary itself.

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 scoping clause 'Only for products with price rules; says so otherwise' gives one real usage condition, which is better than nothing. But there is no explicit when-to-use guidance or routing to alternatives such as compare_offer_costs or cost_at_growth, leaving the agent to guess when estimation vs comparison is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety bar is lower; the description adds real value by disclosing the shape of the payload — verbatim pricing-note sentences, read dates, source, and separate measured claims with true/false/not_tested states and review evidence. It also clarifies that vendor claims and measured claims are kept distinct, which prevents misinterpretation.

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

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

The core content is front-loaded, but it is delivered as one sprawling sentence with heavy internal jargon ('our own hands-on claims, exit test and facts') that slows parsing. It is not padded with filler, but structure could be tightened.

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

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

With no output schema, the description does useful work describing return contents, so that burden is partly met. However, a two-parameter tool with zero documented parameters leaves an agent unable to construct arguments confidently, which is a material 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%, and the description never mentions product_id or the optional cost_trap parameter. 'A product's cost traps' hints at filtering, but there is no explanation of what cost_trap accepts (a name? an id?) or what happens when omitted — the description should compensate for the fully undocumented schema and does not.

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?

It names a specific verb+resource (retrieve the evidence behind a product's cost traps and free-plan flag) and enumerates the evidence types returned, so the purpose is inferable. But it's dense domain jargon ('measured', 'exit test', 'not_tested') and never distinguishes itself from nearby siblings like get_task_evidence or build_purchase_dossier.

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?

There is no guidance on when to call this instead of get_task_evidence, build_purchase_dossier, or compare_offer_costs. The description only says what will be returned, not the situation that selects this tool, so the agent must guess among siblings.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, so the description earns credit for adding data-quality context instead: 'eligibility as recorded (null = the vendor did not say)' clarifies null semantics, and 'No offer has been tested at a checkout' warns that values are unverified. These are genuine behavioral caveats beyond the 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?

A single front-loaded sentence inventories the returned fields, followed by one short caveat sentence. It is dense but every listed field helps an agent judge whether this tool answers its question; only the enumeration is heavy, with no filler.

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

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

With no output schema, the description properly carries the return-value burden by naming the record's fields, and it flags the untested/affiliate disclosure caveats. The remaining gap is the undocumented offer_id and no pointer to how it is sourced, which is minor for a single-parameter 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% and the description never mentions offer_id, its format, or how to obtain one (e.g., from search_offers). With one required parameter fully undocumented in both schema and prose, the description does not compensate for the coverage gap.

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 it returns 'the full record of one offer,' a specific resource with singular scope that implicitly contrasts with the sibling search_offers (list) and get_evidence (sub-resource). The verb 'get' is only implied by the name, and no sibling is named explicitly, so differentiation is inferable rather than stated.

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?

There is no when-to-use or when-not guidance, and no alternative tool is named despite close siblings like check_offer_eligibility, compare_offer_costs, and search_offers. The 'one offer' phrasing faintly implies a single-record lookup, but the agent must infer the routing condition entirely.

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 bar is met. The description adds genuinely useful context beyond that: results carry full evidence sentences, explicit 'unknowns', and an affiliate disclosure on the vendor handoff — the last being a material trust signal an agent would not otherwise know to watch for. It stops short of noting payload size or behavior for an unknown product_id.

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 front-loaded sentence that leads with the core purpose before listing contents, so an agent can stop reading early. The content list is dense and slightly run-on ('in measured (claims, exit-test scope and three-valued facts...'), costing some readability without wasting whole sentences.

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 appropriately carries the burden of describing return contents in detail, including evidence, unknowns, observations and handoff data. Remaining gaps — where product_id comes from, and what happens on an unknown id — are minor for a single-key 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 0% and the single parameter product_id has no title detail, yet the description says nothing about the identifier's format or provenance (e.g., an id returned by search_products). With one parameter the gap is small, but the description does no compensating work here.

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 concrete verb+resource framing ('The full record for one product') and then enumerates the record's contents, which lets an agent separate it from siblings like get_evidence (evidence only) and compare_products (multi-product). It never states the retrieval key explicitly, but 'for one product' combined with the required product_id is unambiguous.

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

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

There is no guidance on when to call this versus alternatives: nothing says to fetch a product_id from search_products first, nor when to prefer get_evidence for a single trap or build_purchase_dossier for a decision. The agent must infer routing from the content list alone.

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 bar is lower. The description adds real behavioral context the annotations cannot: each result is scoped to the product version on run_date and the stated plan, and later versions inherit nothing — a critical caveat for interpreting results correctly. It omits pagination behavior despite limit/cursor params.

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 in the first clause, followed by query guidance and then the important scoping caveat. Two sentences with little waste, though the inline enum list is dense enough to slightly strain 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?

With no output schema, the description should characterize return values more than 'what we observed.' It conveys the semantic scoping well but never sketches the shape of a returned observation (fields like run_date, plan, task) nor pagination behavior for a 5-param list tool.

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

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

Schema coverage is 0%, so the description must carry the load. It does document the result parameter's six allowed values (an enum the schema lacks) and clarifies that query means task words and product_id is a product identifier. But limit and cursor are entirely unexplained, leaving conventional-but-unstated pagination 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?

The description states a concrete purpose: returning first-hand observations from running products, searchable by task words, product id, or result. It is more than a tautology and tells the agent what data it holds. However, it never differentiates itself from the sibling tool get_evidence, leaving the agent to guess which evidence tool to call.

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?

'Search by task words, product id or result' describes how to query, which implies usage, but there is no explicit statement of when this tool is preferable to get_evidence or the other evidence-adjacent siblings. No exclusions or prerequisites 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds one genuinely useful behavioral fact beyond that: results are aggregated with product counts, implying a computed summary rather than raw rows. It says nothing about ordering, caching, or size of the returned set.

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 nine-word sentence that front-loads the resource and then the payload. Nothing is redundant and nothing is padded.

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

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

With no parameters and no output schema, the description is the only place the return shape can be conveyed, and it does so concisely (categories plus counts). It is sufficient for a trivial enumeration tool, though it could note whether counts are global or filtered by the caller's context.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. Schema coverage is 100% but empty, so no compensating text is required.

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

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

The description names the resource (categories) and the exact shape of the result (each category with its product count), so an agent knows precisely what comes back. It lacks an explicit verb, though the name 'list_categories' supplies it, and no sibling tool covers categories, so differentiation is not needed.

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?

There is no statement of when to reach for this tool versus alternatives, nor any prerequisites. Because it is a zero-argument enumeration with no competing sibling, the omission is less costly, but the description still gives no routing guidance at all.

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 readOnly, idempotent and non-destructive, so the safety profile is established. The description adds useful context beyond that: it enumerates what is compared (entry price, plans, cost traps, price rules, research status, pricing date) and notes that no purchase/cancel/switch action occurs, reinforcing the read-only contract.

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 tightly packed sentences: what it does, what to pass, what it reports, and the side-effect disclaimer. Front-loaded with the action and the input convention, with zero 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, so the description must sketch the return value, and it does by naming the fact categories and the affected conclusions. This is sufficient for an agent to invoke and interpret the tool, though a note on whether the entire dossier must be byte-identical (for idempotency reasoning) would close the last 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?

With 0% schema coverage on a nested, open-ended object parameter, the description carries the burden and does so with 'pass the whole dossier back' — clarifying this is a full round-trip of the previously returned object rather than an ID or partial patch. The internal structure of the dossier remains undocumented, but it is implicitly the output of the build step.

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 ('Re-check a purchase file') and ties itself to the sibling workflow by referencing a dossier 'built earlier'. An agent can immediately distinguish this from build_purchase_dossier or the generic check_* tools.

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

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

Implies the precondition clearly: use this when you already hold a dossier from a prior build and want to know what changed. It does not explicitly name build_purchase_dossier as the counterpart or state when not to use it, but the 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 declare this a safe, idempotent read, so the bar is lower. The description still adds real behavior: default exclusion of expired offers, the row contents (evidence, evidence date, verification status, UTC deadline), and the non-obvious alphabetical ranking that is explicitly not by discount or commission.

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 tight sentences, each carrying distinct information: what is searched, what a result row contains, and the two surprising behaviors (expired filtering, alphabetical ranking). 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 returned fields and default filtering/ranking, which is what an agent needs to interpret results. The main gap is the undocumented filter parameters (confirmed_only, product_id, query, limit), which leaves the tool's full capability 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 0% and there are six parameters, so the description must carry the load. It explains include_expired ('Expired offers are left out unless include_expired') and hints at offer_type values, but says nothing about limit, query, product_id, or confirmed_only, leaving half the parameters undocumented.

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 ('Find') and a well-scoped resource ('reader offers and vendor offers on our deal pages'), with concrete examples (discounts, extra credits, longer trials, conditional pilots). It is clearly a search over offers, distinguishable from siblings like get_offer and compare_offer_costs, though it never names an alternative 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?

Usage context is implied by the domain (searching deal pages) and by the include_expired switch, but there is no explicit statement of when to use this versus get_offer, check_offer_eligibility, or compare_offer_costs. An agent must infer the routing from the sibling names.

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/openWorld=false, so safety is covered. The description adds genuinely new behavioral context: the compact return shape (id, entry price, cost-trap ids, pricing date) and the ranking rule (text relevance only, never commission). It omits pagination semantics for cursor/limit.

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 dense sentences, zero filler, with the core capability front-loaded and the return/ranking facts appended. Every clause adds information an agent could act on.

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 an 8-parameter, zero-coverage schema with no output schema, the description leaves most filter parameters undefined even though it partially compensates on return values. An agent cannot reliably construct filters like avoid_cost_traps or max_price_usd_month without guessing.

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

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

Schema description coverage is 0% across 8 parameters, so the description carries the full burden, yet it only maps the query to 'by task or name' and lumps the rest under 'optional filters'. Parameters like avoid_cost_traps, has_cost_rules, free_plan, max_price_usd_month, limit and cursor are left entirely unexplained.

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?

Clear verb+resource: search products by task or name with optional filters. It is distinguishable from get_product and compare_products by being a search, but it never names its closest sibling (search_offers) to disambiguate product vs offer search.

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

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

The description says it accepts filters but gives no when-to-use guidance, no exclusions, and no pointer to alternatives such as compare_products or search_offers. The agent must infer the boundary between product search and offer search on its own.

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