compatsy home espresso

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context by explaining the return: a verdict with the rule id and version that decided it, or the missing fields. This goes beyond the annotations and gives the agent useful output semantics.

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 question, then immediately states the return format and gives a compact example. Every sentence earns its place with no wasted text.

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 simple two-parameter, read-only compatibility check with no output schema, the description is complete enough: it states the purpose, the return value (verdict, rule id/version, or missing fields), and provides an example call. Annotations handle safety, and the schema handles parameter typing, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters as part id/slug and printer/hotend id/slug. The description's example showing concrete IDs adds a small amount of format guidance, but it does not provide deeper semantics beyond what the schema already states.

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+resource: checking whether a part fits a machine. It is distinct from siblings like check_stock or get_product, but it does not explicitly name an alternative such as compare, leaving some ambiguity about when to choose this over a general comparison.

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 question format and the example, but there is no explicit guidance on when to use this tool versus alternatives like compare or check_stock. The example helps illustrate a typical call but does not state exclusions or alternatives.

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, idempotent, closed-world semantics, so the bar is lower. The description adds a genuinely non-obvious trait beyond them: results are re-verified live when cached data is over an hour old, which tells the agent to expect a slower call and trustworthy freshness. It stops short of covering error/not-found 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?

Two compact sentences with the freshness rule front-loaded and an inline example that earns its place given the undocumented schema. Only the sentence-fragment style slightly weakens 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?

For a two-parameter lookup with no output schema, the description should state the return shape and the behavior when merchant_id is omitted. It conveys the concepts of availability and price but not their structure or the single-merchant vs multi-merchant branching.

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, and it does partially via a concrete example showing slug-style IDs ('prusa-mk4s', 'prusa3d'). It never explains that merchant_id is optional or what omitting it returns, so the required/optional asymmetry is left implicit.

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 two returned values (availability and price) and the per-merchant scope, which is specific enough to distinguish it from get_product and compare. It does lean on the title for the verb ('check'), but the resource and scope are 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 statement of when to use this versus siblings like compare or get_product, nor any prerequisite or exclusion. Usage is only inferable from the name and the phrase 'per merchant'.

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 fully covered. The description adds useful behavior — the response is a spec comparison table including offers and only the fields that differ — but says nothing about cost, size limits on the returned table, or error handling beyond what the schema notes.

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 what the tool returns, followed by the two input modes and a compact example. No filler, and the example earns its place by disambiguating the array form.

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 characterizes the return value as a spec table with offers and differing fields. The remaining gap is the limit parameter and what happens when fewer than two valid products match; otherwise an agent has enough to call it correctly.

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

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

Schema description coverage is only 25%, so the description must carry weight: it does explain the product_ids (2-10) path, the category+filters path, and provides a sample payload, and the filters error behavior is documented in the schema. The limit parameter (1-10) is never mentioned in either place, leaving one of four parameters semantically thin.

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 operation and result: a side-by-side spec table with offers and differing fields, taking either product_ids or a category plus filters. That distinguishes it from get_product (single item) and search_products (discovery), though it never names those siblings 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?

It clearly states the two invocation modes ('Pass 2-10 product_ids, or a category with filters') and gives a concrete example payload, which is enough for an agent to pick the right form. It stops short of saying when to prefer this over search_products or get_product, so no exclusions or alternatives are 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?

Because annotations already cover the safe, idempotent, read-only character of this tool, the description adds meaningful context by disclosing the shape of the results: confidence and source for each spec field, verified offer timestamps, and multi-window price ranges. It does not cover not-found or error behavior, but for a read tool this disclosure is valuable.

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

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

The definition is a single dense sentence followed by a compact invocation example; it is front-loaded with the return payload and contains 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?

There is no output schema, so the description properly carries the burden of describing return values by summarizing the specs, offers, and price ranges. It falls just short on not-found or error behavior and on the tool's relationship to the search-to-detail workflow.

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

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

Schema coverage is 100%, and the schema already documents product_id as 'Product id or slug', so the baseline is 3. The example value 'prusa-mk4s' reinforces the slug format in practice, but no further meaning is added.

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 specific content returned by the tool: full specs with per-field confidence and source, every offer with a verified timestamp, and a 30/90-day price range. It makes clear that this is a single-product detail lookup, but it never explicitly distinguishes the tool from siblings search_products or compare.

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 example id 'prusa-mk4s' shows that a single product record is fetched by id or slug, which implies this tool follows a search. There is no explicit statement of when to use this tool instead of search_products, check_stock, check_fit, or compare, and no 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 only say it is non-read-only, non-destructive and non-idempotent. The description adds real value beyond them: reports do not edit facts, and two independent reports are what mark a fact disputed — behavior an agent cannot infer from structured fields. It leaves unclear what a single report does on its own (stored? queued? acknowledged?).

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 and an example, with the core action front-loaded and the dispute-threshold rule second. Every clause adds information; nothing is padding.

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 never says what calling it returns or what happens to a single report before a second one arrives. Combined with 0% schema coverage on four parameters, meaningful gaps remain for an agent deciding whether the call succeeded and how to phrase 'field'.

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 carry parameter meaning, and the embedded JSON example at least maps values for entity_type, entity_id, field and claim. But it never explains what 'field' means (which field names are valid, why it is optional), nor the allowed entity_type values or the 500-character claim limit.

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: 'Flag a wrong spec, price or fit verdict', which immediately sets it apart from the read-only siblings (check_fit, check_stock, get_product, search_products, compare). The 'Reports never edit facts' clause further pins down that it files a report rather than mutating 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?

The description makes clear when to call it (you found a wrong spec, price or fit verdict) and supplies a worked example, which is strong selection guidance. It stops short of naming an alternative path or stating any exclusion (e.g., when to use compare or check_fit instead of reporting).

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's main added value is the return shape — key specs plus a best in-stock offer — which matters because there is no output schema. However, 'best' is undefined (price? availability?) and there is no note on ranking, defaults, or truncation 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?

Two short segments, with the capability statement front-loaded before the example. The example earns its place by demonstrating how query/category/limit combine, though it is somewhat longer than needed for a four-parameter 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?

Reasonable for a search tool with no output schema: the return contents are summarised and filter error behavior lives in the schema. Still missing what an agent needs for edge cases — empty-parameter behavior, default result count, and how query interacts with filters.

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 25% — query, category, and limit are undocumented in the schema — and the description only partially compensates by mapping query to name search and category/filters to facet matching. The worked example shows the three parameters combined, but there is no guidance on precedence between query and filters, default limit, or when category 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?

Names a specific verb and resource ('Find products') and states both retrieval modes (by name, or by category/spec filters), plus what comes back ('key specs and the best in-stock offer'). This implicitly separates it from get_product (single item) and check_stock, 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 phrase 'by name or by category and spec filters' implies when to reach for this tool, but there is no explicit when-to-use / when-not-to-use guidance and no mention of alternatives such as get_product for a known item or compare for side-by-side evaluation.

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