Brickfact LEGO Shopping

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

The annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description still adds substantive behavioral context beyond them: the comparison is against the recorded retail low only, not an all-time low, predictions are deliberately out of scope, and the Amazon asymmetry between history and current offers is disclosed. It does not describe how 'coverage' is expressed in the response, but the output schema presumably carries that.

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 with no filler: purpose first, disclaimer second, data-source caveat third. Each sentence carries distinct information and the most important framing is front-loaded. The telegraphic phrasing ('show coverage') is slightly compressed at the cost of a little readability, which keeps it off 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 annotations covering the safety profile and an output schema present, the description need not explain return values; what remains is to define the comparison semantics and caveats, which it does. The gaps are minor: no statement of whether an assessment requires existing recorded data for the set, and no explicit routing versus sibling history 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 description coverage is 75%, with days and market well documented and set_id and language mostly self-explanatory from their types and enums. The description contributes little parameter-level meaning; 'show coverage' loosely relates to the days look-back and 'freshest known delivered offer' implies the market scope, but neither is spelled out. With the schema doing the heavy lifting, the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource pair: compare the freshest delivered offer against the recorded retail low and report coverage. That tells an agent exactly what the tool computes rather than merely restating the title. It stops short of naming a sibling such as get_retail_price_history or get_set_offers, so the boundary between this assessment tool and the raw history tools is only inferable.

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?

Scope rules are given ('No all-time-low claims or predictions') and the data source boundary is stated ('History excludes Amazon; current offers can include Amazon'), which implicitly frames when this tool is appropriate. However, there is no explicit instruction about when to prefer it over get_retail_price_history or get_set_offers, and no stated prerequisites beyond what the schema's 'ask when unknown' note for market provides.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context about what is compared and that all sets must belong to one market, but says nothing about how results are presented or any limitations when data is missing for one of the sets.

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 with the core action and facets stated first and the constraints after; there is no redundant or filler wording.

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 and annotations covering safety, the description needn't explain return values. However, for a four-parameter comparison tool it leaves the price_basis parameter entirely opaque and gives no hint about behavior when one set lacks offers in the chosen market, so it falls short of fully complete.

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

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

Schema coverage is 50%: market and language carry their own descriptions, while set_ids and price_basis do not. The description compensates for set_ids by stating the 'two to four distinct set numbers' range and the same-market requirement, but price_basis (item vs. delivered) is left unexplained in both schema and description, which matters for interpreting compared prices.

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') and resource ('set numbers') and enumerates the compared facets: specifications, retirement status, and monitored offers. The 'two to four distinct set numbers in the same retailer market' scope implicitly separates it from single-set siblings like get_set_details and get_set_offers, 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 2-4 set and single-market constraints imply when this tool fits, but there is no explicit when-to-use/when-not guidance and no pointer to alternatives such as get_set_offers for a single set. An agent must infer the routing decision from the name and scope wording.

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

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

The annotations already declare the operation read-only, open-world, and non-destructive. The description adds useful behavioral context beyond that: candidate coverage is bounded, and fewer pieces does not establish physical dimensions, which warns the agent against a likely 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 description is two concise sentences, front-loading the core purpose before adding two relevant constraints. There is no filler or redundant wording.

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 covering return values and annotations covering safety, the description provides the essential purpose and key caveats. It still omits sibling routing and full parameter details, but it is largely complete for a read-only discovery 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 only 33%, so the description must compensate. It adds meaning for preference and max_price by explaining cheaper delivered-price and budget semantics, but it does not clarify set_id, limit, or the default 'similar' preference, leaving several parameters under-explained.

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

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

The description states a specific verb and resource: 'Find curated related sets,' with optional scoping by delivered-price preference, piece count, or budget. It is clear what the tool does, but it does not distinguish itself from sibling tools such as compare_sets or search_sets.

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 mention of finding related sets with cheaper, fewer-piece, or budget constraints. However, there is no explicit guidance on when to choose this tool over compare_sets or search_sets, 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 establish readOnly, non-destructive, and open-world behavior, so the bar is lower. The description still adds real value: it clarifies that nothing is created server-side, that the user completes the action in the app, and that target_price is only a draft in the market currency. It omits auth or rate-limit context, but openWorldHint covers the external nature.

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

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

Three sentences, front-loaded with the purpose before the behavioral caveat. The second sentence partly restates the read-only annotation, but it earns its place by explicitly ruling out creation. No filler or unnecessary repetition.

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

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

With an output schema present, the description need not explain return values, and annotations cover the safety profile. For a five-parameter tool, the description covers the core behavior and the one non-obvious parameter. Minor gaps remain around action-specific parameter applicability and error handling.

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%, but the description compensates for the most ambiguous field by defining target_price as an optional draft in the market currency. The action values are restated in prose, while set_id is left to the schema as self-evident. It does not clarify whether target_price is meaningful for the wishlist action or what happens if supplied with action=wishlist.

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

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

The description opens with a precise verb and resource: get the existing app link and steps for setting a price alert or saving to a watchlist. That is specific enough to separate it from every sibling, which are all data-retrieval or comparison tools rather than app handoffs.

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 naming the two supported actions (price alert, watchlist), and the 'handoff' framing tells the agent this is not a data query. However, there is no explicit when-not-to-use guidance, no named alternatives, and no statement about prerequisites such as requiring a known set_id or market.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context: the values are EUR collector valuations rather than retailer prices or predictions, which prevents misreading output. It does not describe freshness, coverage or how valuations are computed, so beyond the currency/nature caveat it is moderate.

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

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

Three short sentences, front-loaded with the gating condition and the routing instruction, with zero filler. The one inefficiency is that the opening is a usage restriction rather than a statement of what the tool returns, so the reader learns what it is for before learning what it does.

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 need not be described, and the sibling routing is fully handled. What is missing is only the semantic gap around range/price_basis and a direct statement of what 'collector valuation' output represents over the selected range; for a read-only open-world lookup this is close to complete.

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

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

Schema coverage is 40%, so the description must compensate. It partially does: stating all values are EUR clarifies that the market enum (DE/AT/CH/GB/US/...) does not change currency, which is a real ambiguity the schema leaves open. However, range, price_basis and the relationship between market and collector valuation are not explained anywhere, leaving half the parameters underspecified.

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 frames the tool around 'explicit collector, resale or sealed-set market-valuation requests' and later clarifies 'Values are EUR collector valuations, not retailer prices or predictions,' which pins down the resource. But it never states the verb/return shape directly (a history series? a single valuation?) and its reference to 'price history' as belonging to another tool actively works against the name get_price_history, leaving the actual output somewhat vague.

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

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

Explicit routing: use only for explicit collector/resale/sealed-set valuation requests; for price history, price development, Preisentwicklung or past shop prices call get_retail_price_history first; and 'Never use this tool as a fallback for partial or unavailable retailer history.' Both the when and the when-not are stated with the named alternative.

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, non-destructive, openWorld), so the lower bar applies. The description adds real operational context beyond them: results are recorded/delivered retail prices, Amazon and unknown-shipping data are absent, and partial coverage is legitimate rather than empty. It does not discuss rate limits or result volume, but the output schema covers return 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?

Dense but front-loaded: selection guidance first, then coverage caveats. The multilingual keyword list ("Preisentwicklung") is mildly redundant for an agent but short. No sentence is wasted, though the piece reads as a run of fragments rather than a structured statement.

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

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

Output schema exists, so return values need not be explained; the description instead addresses the pitfalls that matter (partial data, excluded sources, wrong-valuation substitute). Minor gap: set_id semantics and the language parameter get no mention, and currency is described but derived implicitly from market.

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 75% and already documents days, market, and language well, including the 365-for-12-months guidance the description repeats. The description adds only the market/currency linkage (a concept with no corresponding parameter) and says nothing about set_id or language. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb and resource ("Read recorded delivered retailer prices") plus the scoping dimensions (selected market and currency), and explicitly contrasts with the sibling concern by saying collector market valuations must not be substituted. An agent can distinguish this from get_price_history without opening either schema.

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

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

Declares itself first choice, gives a concrete parameter recipe ("Use days 365 for the last 12 months"), tells the agent how to handle partial coverage, and states exclusions (Amazon, unknown shipping) and the anti-pattern (collector valuations). When-to-use and when-not-to-use are both present.

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 a safe read (readOnlyHint true, destructiveHint false, openWorldHint true), so the bar is lower, and the description still adds real value: it warns that future retirement dates are estimates and that shipping totals and unverified stock are labelled. Those are data-quality caveats an agent could not get from the annotations or schema.

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

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

Two tight sentences with zero filler, front-loaded with what the tool returns and followed by the caveats that qualify that data. 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?

An output schema exists, so return structure need not be explained, and the description covers the content scope plus the two data-quality traps (estimated retirements, unverified stock). The only real gap is the unexplained price_basis option, which matters because it changes which price is reported.

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 exactly 50%: market and language carry descriptions, while set_id and price_basis do not. The description adds no parameter meaning at all — notably it never explains what price_basis "item" versus "delivered" changes, which is the one genuinely ambiguous input.

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

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

The description uses a specific verb ("look up") with a specific resource (a set) and enumerates the returned content: specifications, retirement information, and monitored offers. It is clearly distinct from list/search siblings like search_sets or list_themes, though the mention of "monitored offers" overlaps with get_set_offers without explaining 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?

Usage is only implied: an agent can infer this is the detail-lookup tool for a single set, but the description never states when to prefer it over get_set_offers or compare_sets, nor any prerequisites such as needing a known set_id. No when-not guidance is offered.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, and the description adds real value beyond them: 'Unknown shipping is not free shipping' warns against a specific misinterpretation of the returned totals, and 'Results do not guarantee stock or checkout prices' discloses data staleness. It does not cover freshness windows or rate limits, but the caveats given are exactly the kind of behavioral context annotations cannot convey.

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

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

Four short sentences, front-loaded with the action and scope, then the comparison semantics, then the two caveats. No sentence restates the name or title, and nothing could be removed without losing a distinct point.

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

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

An output schema exists, so return values need not be explained, and the annotations cover safety and openness. Combined with the caveats about shipping and stock, the definition is sufficient to invoke the tool correctly; only the absence of any routing to sibling tools for related pricing questions keeps it from a 5.

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 50%, so the description must do some work, and it does: 'item prices and reported shipping totals' clarifies the item vs. delivered distinction behind price_basis, and 'Unknown shipping is not free shipping' tells the agent that a missing shipping figure is not zero when choosing or interpreting that basis. It says nothing about the language parameter's effect on results or about set_id beyond context, leaving part of the gap unfilled.

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

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

The description opens with a specific verb and resource: 'Find monitored retailer offers for one set in a supported market,' and follows with what is compared (item prices and reported shipping totals). The single-set scope distinguishes it implicitly from compare_sets and get_price_history, 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?

Usage is implied by the single-set, single-market framing ('for one set in a supported market'), and the schema tells the agent to ask when the market is unknown. There is no explicit when-to-use/when-not guidance and no pointer to assess_deal, compare_sets, or find_alternatives for related questions such as 'is this a good price?' or 'what else fits?'.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile and the fact that data comes from an external catalogue are covered. The description confirms that this is a read-only reference lookup, but adds nothing about result volume, caching, or fallback behavior when no theme matches.

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 short sentences, zero filler, with the output shape stated first and the downstream use second. Nothing can be removed without losing meaning.

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

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

An output schema exists, so return values need no explanation, and the tool is a simple reference lookup with only three parameters. The only real gap is the lack of guidance on match behavior for `query` and on whether an empty result is possible.

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 67%; market and language are documented in the schema, including the 'ask when unknown' note for market. The description only clarifies that `query` is an optional free-text filter, and does not explain matching semantics (prefix vs substring) or how language affects theme names, 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?

The description states a specific verb and resource ('Find catalogue theme IDs and names') and names the payload (IDs and names), so the agent knows what comes back. It does not explicitly name a sibling like search_sets, but the phrase 'narrow a set search' still signals the relationship to it.

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

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

'optionally by text' and 'can be used to narrow a set search' imply when this tool is useful: resolving a theme before filtering returns from search_sets. However, it never states when not to use it, or whether a bare list is returned with no query, so the routing guidance is implied rather than explicit.

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

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

Annotations already declare readOnly and non-destructive, so the description isn't burdened with safety disclosure. It still adds real behavioral context: the cardinality limits per view mode, the fact that output includes images, reported delivered prices, card shortlists and app handoffs, and that data remains available without UI — an important trait for an agent that may consume results headlessly.

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, with the mode/cardinality rule front-loaded. The second sentence packs several content features into one list, which is dense but still readable and 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?

An output schema exists, so return values needn't be enumerated in prose, and annotations cover the safety profile. Combined with the cardinality rules and the headless-data note, the description is complete enough to call correctly; only explicit sibling disambiguation is missing.

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

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

Schema coverage is 50%: market and language are documented in the schema, while view and set_ids are not. The description partially compensates by tieing set_ids cardinality to the view mode (1-6 for cards, 2-4 for comparison), which is a constraint the schema's minItems/maxItems do not express. It says nothing about the view enum values themselves or the default, so it only partially fills the 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 names a concrete action and resource: render 1-6 set IDs as shopping cards or 2-4 as a side-by-side comparison. That is specific enough to distinguish it from data-returning siblings like get_set_details or get_set_offers, though it never explicitly contrasts itself with the similarly-named compare_sets 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?

'After searching or choosing sets, show the final...' gives a sequencing cue that this is a terminal presentation step, which is useful context. However, it offers no exclusions or named alternatives (e.g., when to use compare_sets instead of the comparison view), so the agent must infer the boundary 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 establish read-only, non-destructive, open-world behavior, so the description is free to add operational detail — and it does: delivered search excludes unknown shipping before pagination, market/language interaction is explained, and output is described as Brickfact comparison links. It stops short of describing pagination limits or result ordering 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?

Three dense sentences with no filler; the capability statement leads and the trickier price_basis and shipping caveats follow. Every clause conveys distinct 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?

With 16 parameters, one required field and an output schema (so return shape needn't be explained), the description covers the filter families but not the operational controls. An agent still lacks guidance on pagination, sort semantics and price currency, which matters for a price-comparison search.

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

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

Schema description coverage is only 13% across 16 parameters, so the description must carry more weight than it does. It adds real meaning for price_basis, query, theme_ids, pieces, age and retirement filters, but leaves sort, page, limit, language, current_offers_only, retirement_year and the currency/units of min_price/max_price entirely unaddressed.

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 ('Find sets') and enumerates the searchable facets (name/number, theme IDs, budget, pieces, age, retirement status), so an agent knows exactly what this tool retrieves. It does not, however, distinguish itself from siblings like render_sets or compare_sets, which also surface set data.

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

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

Provides real conditional guidance for the price_basis switch ('use delivered for budgets including shipping; item preserves the original item-only search'), which is genuinely actionable. But there is no guidance on when to choose this tool over render_sets or get_set_details, and no mention of prerequisites beyond the market requirement carried in the schema.

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