toolgrep

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

Annotations already declare readOnly, idempotent and non-open-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond them: the arity constraint (2–6) and the shape of the result (full records plus a field-by-field table keyed by slug), which tells an agent how output is organized for downstream use.

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, zero filler, with the core action and comparison scope front-loaded before the return-format note. Nothing is padded or repeated unnecessarily.

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

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

With an output schema present, return values need no explanation, and the annotations cover safety; the description adds the comparison axes and arity, which is sufficient for a one-parameter tool. The only gap is not pointing to search_products as the source of valid slugs.

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

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

Schema coverage is 100% and the single slug array parameter is already bounded by minItems 2 / maxItems 6 in the schema. The description merely restates that bound and adds nothing about slug format, case sensitivity, or where valid slugs are obtained, 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?

The description uses a specific verb phrase ('put 2 to 6 products side by side') and enumerates the exact dimensions compared (pricing, free tier, API, MCP, SDK, open source), which clearly distinguishes this multi-entity comparison from the singular get_product. It never names a sibling explicitly, so it stops short of a full 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?

The 2-to-6 product bound implies when the tool is applicable, but there is no explicit statement of when to choose this over get_product or search_products, nor any prerequisite such as where slugs should come from. Usage is inferable rather than stated.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, so the safety profile is covered. The description adds genuinely new operational context: the ranking is nearest-neighbour on the product's embedding, and when the vector index is unavailable it degrades to same-category results. It does not mention ranking order guarantees or default limit, but the fallback disclosure is the important one.

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, front-loaded with the core behavior and followed by the fallback caveat. No filler.

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

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

An output schema exists and annotations cover the safety profile, so the description only needs to explain the retrieval logic and its degradation path, which it does. The one remaining gap is routing guidance against search_products, which would make agent selection unambiguous.

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 86%, so the schema already documents nearly every parameter including the category enum pointer. The description's 'with optional filters' adds no syntax or semantics beyond that, 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?

States a specific resource (products similar to a given one) and the mechanism (vector similarity), which clearly separates it from 'search_products' semantically. It lacks an explicit naming of the sibling it complements, so it falls just short of 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?

'Products similar to a given one' implies the use case (seeded similarity lookup rather than keyword search), but there is no explicit statement of when to prefer this over search_products or compare_products. The guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and closed-world access, so the safety profile is covered. 'Every field' adds a small amount of value by signaling a complete, non-paginated object rather than a summary, but nothing is said about missing-slug behavior or errors; an output schema exists, so return shape need not be described.

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 terse sentence with zero filler, and the key detail (full field set) is front-loaded. It is a fragment rather than a complete statement, but nothing is 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?

For a one-parameter read tool with full schema coverage, annotations, and an output schema, the description covers what an agent needs to call it correctly. Only the sibling-selection guidance 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 100% and the single slug parameter is fully documented there, including the source_url format. The description's 'by slug' only restates 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?

The fragment 'Every field of one product by slug' identifies the resource (a single product) and the scope (all fields, keyed by slug), which is clearer than a bare restatement of the name. It does not distinguish itself from siblings like search_products or compare_products, but the single-record full-fetch intent 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 use this over search_products (list/query) or compare_products. The agent must infer that this is the exact-lookup path from the word 'slug' alone, with no explicit when/when-not statement.

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

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

Goes well beyond the annotations by disclosing the downstream side effect (a re-crawl), its rate limit (at most once per hour per product), and the guarantee that the report is always recorded even when the crawl is throttled. That is exactly the operational context an agent needs before firing a write-like call, and it is consistent with idempotentHint=true and destructiveHint=false.

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 with zero filler; the action comes first and the throttling caveat follows. Every clause carries information the agent cannot get from the schema 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?

An output schema exists, so return values need no explanation, and the description covers the side effect, throttling and record guarantee. The remaining gap is parameter guidance — particularly what `slug` should contain and whether `reason` is optional.

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 50%: `reason` is documented with maxLength and examples, but the required `slug` has no description anywhere. The description never mentions either parameter — 'per product' only weakly hints that slug identifies the product — so it fails to 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?

States a specific verb and resource ('Flag a listing as outdated or wrong') plus the main side effect ('triggers a re-crawl'). The action is clearly distinct from the sibling read/search tools and submit_product, 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?

'Flag a listing as outdated or wrong' gives a clear trigger condition, and the rate-limit note implies this is a last-resort correction path rather than a routine call. No explicit when-not guidance or named alternative is provided.

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/closed-world, so the safety profile is covered; the description adds the genuinely useful behavioral detail that matching is hybrid full-text plus semantic similarity and that result counts are capped. It stops short of describing relevance ordering or pagination.

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: capability, then the matching advice, then the result bound. Front-loaded and free of padding, though the parenthetical filter list slightly duplicates the schema's enum and property names.

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

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

With an output schema present, return-value structure needn't be described, and the description covers the remaining essentials for a 7-param, all-optional search tool: how the query is interpreted, how to phrase it, and how many results come back. Missing only relevance/ordering behavior and any guidance on combining 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 86%, so the baseline is 3; the description earns above that by explaining the query's matching semantics and the need-style phrasing that works best, plus the limit default of 10 (the schema states the max but not the default). Filter parameters are only enumerated, not otherwise illuminated.

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: 'Search the directory' with a natural-language query plus structured filters. It distinguishes itself implicitly from get_product (single lookup) via the query/filter framing, but never names a sibling to make the boundary explicit.

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

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

Usage is implied rather than stated: the example need-style query ('send transactional email with a free tier') shows how to call it, and 'omit to browse by filters only' hints at filter-only mode (documented in the schema, not the description). No statement of when to prefer find_alternatives or compare_products over this search.

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 the write/idempotent/open-world profile, and the description adds genuine context on top: no authentication required, crawl latency of roughly a minute, and a status_url to poll. It does not say what happens on a duplicate submission despite idempotentHint=true, which keeps it from 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?

Three short sentences, each carrying distinct information (action, auth exemption, latency plus polling), with the core action front-loaded. 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 an output schema present, return values need no explanation, and the description covers auth, latency, and follow-up polling. The only gap is duplicate-submission behavior, which matters given idempotentHint=true.

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 both url and email are already documented in the schema. The description mentions submitting a URL but adds nothing about the optional email or the 'homepage' constraint, so baseline 3 applies.

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

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

States a specific verb and resource ('Submit a product URL') plus the effect ('to be crawled and listed'), which clearly separates it from the read-oriented siblings (search_products, get_product, compare_products). It never names an alternative explicitly, so it stops short of a 5.

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

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

'No account needed' gives a precondition and 'poll status_url' implies a follow-up workflow, but the description never states when to prefer this over report_outdated or how to handle a product already listed. Usage is implied rather than spelled out.

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