MatterCatalog

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorldHint=false, so the safety profile is fully covered. The description adds genuinely new behavioral context beyond that: the figures are dated sentences that self-carry their date, freshness is tied to 'the latest ledger week and month', and each figure has a MatterCatalog page backing it. It still says nothing about response size, caching, or how stale 'latest' can get.

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

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

It is one enormous run-on sentence that packs every metric into a single clause chain, so an agent scanning for the primary purpose has to parse to the end. There is little filler content, but the structure is poor — a lead sentence stating 'returns dated certification statistics, no arguments' followed by a bulleted metric list would be markedly easier to 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 no output schema, the description must carry the burden of describing the return values, and it does: it enumerates the figure categories and notes that each is a dated sentence plus a source page. For a zero-argument, read-only stats tool this is close to sufficient, missing only shape/ordering details.

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?

There are zero parameters and the description explicitly confirms 'No arguments.', which matches the empty schema with additionalProperties=false. Nothing further is needed on the parameter axis.

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 specific resource — MatterCatalog's certification figures — and enumerates the concrete metrics (certified models/companies on the CSA DCL, distinct certificates, newly certified models by week/month, US product counts by certificate/network/platform). That is far more than a restatement of the name, though the core noun ('statistics') is buried inside a long clause rather than stated up front.

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

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

'No arguments' tells the agent how to call it but nothing about when to call it. None of the siblings (check_matter_certification, compare, find_matter_devices, where_to_buy) are mentioned, and there is no stated condition such as 'use this for aggregate totals, use check_matter_certification for a single product'.

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. The description adds real value beyond that: it discloses the data source (MatterCatalog's published ledger read), that a ledger-read date is returned (freshness/staleness signal), and that non-ledger products are included with a caveat about bridged or claim-only listings. It omits any rate-limit or coverage-lag details, keeping it short of a 5.

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

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

The purpose is front-loaded in a clean first sentence, but the second sentence repeats input forms already listed in the schema, and the third is a long run-on cataloguing every returned field. It is informative but dense and over-stuffed rather than tightly structured.

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

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

With no output schema, the description carries the full burden of describing return values, and it does so thoroughly: certificate IDs, dates, software/Matter versions, device type, network transport, ledger-read date, and MatterCatalog page links plus the page's own certification answer. An agent can decide whether the response meets its needs without calling the tool first.

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

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

Schema description coverage is 100%, with both `query` (with example values) and `limit` (1-10 range) fully documented in the schema. The description restates the accepted query forms (name, brand, model, part number, CSA certificate ID) but adds no syntax or matching-behavior detail beyond that. Baseline 3 is appropriate when the schema carries the semantics.

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

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

States a specific verb and resource ('checks whether a product holds a Matter certificate') plus the authoritative source (CSA Distributed Compliance Ledger via MatterCatalog's read). This is clearly distinguishable from sibling lookup tools like where_to_buy or compare, which the description implicitly excludes with 'No prices.'

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

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

Gives a clear context of use: look up certification status by product name, brand, model, part number, or CSA certificate ID, and notes it also surfaces non-ledger (bridged/claim-only) products. It does not explicitly name an alternative tool or state when-not to use it, so the agent must infer the boundary against find_matter_devices.

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

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

Annotations already declare readOnly=true, idempotent=true, closed-world, non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral detail: prices are excluded ('names only, no prices'), links back to both pages and to the compare page are returned, and Thread border router needs are surfaced. It does not say what happens when a product lookup fails or one input is ambiguous.

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

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

It is a single sentence, which is efficient, but it is heavy with a long comma-separated field list that reads as an enumeration rather than front-loaded guidance. Understandable but dense; a short lead clause on when to use it would improve structure.

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

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

For a two-input read-only comparison with no output schema, the description is nearly complete: it enumerates the returned fields, notes the exclusion of prices, and mentions the link outputs. Missing only failure/edge-case behavior, which is minor for this tool.

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

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

Schema coverage is 100% and both parameters are documented as accepting brand+model, product ID, or page URL. The description adds no format or disambiguation guidance beyond the schema, so the baseline 3 applies.

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

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

Description uses a specific verb ('compares') and resource ('two products from MatterCatalog's catalog') and enumerates exactly which fields are compared (brand, category, certification answer, CSA device type, Matter version, network/Thread border router, platforms, where sold). This clearly distinguishes it from siblings like check_matter_certification or where_to_buy, which cover subsets of this 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?

Usage is implied by the side-by-side framing and the field list, but the description never states when to choose this over calling check_matter_certification or where_to_buy individually, nor does it state prerequisites (e.g., both products must exist in the catalog). Implied usage only.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral detail beyond that: the exact shape of each result line (certificate + date, network and Thread-border-router need, platforms, store names without prices), the inclusion of buying-guide picks, and the default filtering predicate. It is silent on result ordering and on what happens when filters match nothing.

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

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

The purpose is front-loaded in the first clause, and every following sentence carries filter or output information rather than filler. It is a dense single paragraph, and the closing line ("Each product links to its MatterCatalog page") plus the repeated store/guide mentions are close to redundant.

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

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

With seven optional parameters, no output schema, and no annotations about return volume, the description does the necessary work of describing what one result entry contains and what the default query restricts to. Gaps relative to complexity are minor: no mention of ordering, pagination beyond limit, or empty-result behavior.

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

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

Schema description coverage is 100%, including enum meanings and the note that Thread devices need a border router, so the schema already carries the parameter semantics and the baseline of 3 applies. The description restates the two boolean defaults and adds that works_with Home Assistant is not recorded per product, but most parameter meaning lives in the schema.

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

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

The description opens with a specific verb and resource ("Lists Matter smart home products in MatterCatalog's catalog") and enumerates the filter dimensions, which lets an agent separate it from catalog_stats or check_matter_certification. It never names a sibling tool directly, so sibling differentiation is implied through the described output 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?

Usage context is conveyed through the default-filter sentence ("By default only products sold in the US with a verified store link and a CSA certificate"), which tells an agent what a default call returns and that booleans relax it. There is no explicit when-to-use-this-instead-of guidance naming compare, where_to_buy, or check_matter_certification, so the agent must infer routing from those siblings' own definitions.

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, closed-world, non-destructive), yet the description adds real behavioral detail: results are store names only, with no store URLs and no prices, and it points to the page that carries prices, check times and the affiliate disclosure. It also discloses that matching is constrained by exact model, pack and region. It adds no note on how region is determined from a product string, which is the one behavioral ambiguity left.

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 content is information-dense with little filler, but the sentence structure is convoluted, especially the clause 'and links that page, where the store buttons, prices with their check times and the affiliate disclosure are.' That clause is hard to parse on first read and buries the useful 'store names only, no URLs or prices' constraint in the middle. Front-loading the return shape would help.

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 one parameter, no output schema and no nested objects, the description carries the burden of explaining the return, and it does: store names, the certification answer and network, plus a link to the page holding prices and disclosures. The only gap is not clarifying how region/pack matching is resolved when the input is a bare model name.

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% for the single product parameter, so the baseline is 3. The description repeats the accepted forms already documented in the schema and adds only the matching strictness (exact model, pack, region) as marginal extra meaning. Nothing about input formatting or fallback behavior goes 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 names a specific verb and resource: it returns the store names that MatterCatalog's product page links for one product, matched to exact model, pack and region. It is clearly distinguishable from find_matter_devices or compare because it is a per-product store-link lookup. It does not explicitly name a sibling or state what it is not, which keeps it below a 5.

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

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

Usage is only implied: the accepted input forms (brand+model, product ID, or product URL) suggest you call it once you have identified a product. There is no explicit 'use this when' versus check_matter_certification, which also returns a certification answer, and no statement of when not to use it. Adequate but leaves the routing decision to inference.

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