PrijsProfeet MCP

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: the need for a Pro API key and the caveat that prices may be promotional or invalid, requiring verification. This goes beyond the annotations and informs the agent about data reliability.

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, front-loaded with the core function, followed by necessary caveats. Every word earns its place; no redundancy.

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 single-parameter tool, the description covers purpose, authentication, and a key usage caution. It implies the return includes pricing, promotion status, and validity. Without an output schema, this is reasonably complete, though it could mention return format or scope of retailers.

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 schema only provides a pattern for the 'ean' parameter without description (0% coverage). The description clarifies that the parameter is an EAN and that the tool compares it across retailers, giving semantic meaning to the parameter. With a single parameter, this is sufficient compensation.

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 the tool's function: 'Compare an EAN across retailers.' It uses a specific verb and resource, and this distinguishes it from sibling tools like get_price_history or match_by_ean, which focus on single-retailer history or matching.

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 explicitly states a prerequisite (Pro API key) and provides a usage directive: 'inspect promotion status and validity before presenting a current cheapest price.' This gives clear context on when and how to use the result, though it does not mention alternatives by name.

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, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds the word 'current' indicating time-sensitivity, but does not disclose other behaviors like pagination, rate limits, or required auth. Given the annotations, this is adequate but minimal.

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 a single sentence of eight words, front-loaded with the action and resource. There is no fluff or redundancy; every word adds meaning. It is appropriately concise for its scope.

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 three parameters (one required), the description is too sparse. It does not explain what 'deal variants' means, how 'limit' affects results, or what values 'promotion_type' accepts. The agent is left with significant ambiguity about the tool's behavior and response 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?

The schema has 0% description coverage, and the description does not compensate. It only hints at the 'brand' parameter via 'for a brand', but 'limit' and 'promotion_type' are completely unexplained. The description adds minimal meaning beyond the schema's bare type names.

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 'Get' and a specific resource 'deal variants for a brand', which clearly distinguishes it from sibling tools like get_top_deals or get_deals_by_type. It clearly states what the tool does.

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 provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions or alternative tools, even though there are many deal-related siblings like get_deals_summary and get_popular_deals. The context for selection is entirely absent.

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 convey readOnly, idempotent, and non-destructive behavior, so the description adds 'unified' which hints at aggregation but without detail. It does not explain what 'unified' means operationally or if there are any edge cases, leaving some ambiguity beyond the annotation coverage.

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 a single, front-loaded sentence: 'Get unified product categories and product counts.' Every word earns its place, and there is no redundant 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 carries the burden of explaining return values. It states 'product categories and product counts' but does not clarify the structure (e.g., list vs. tree, count format), and 'unified' is ambiguous. This leaves some gaps for an agent aiming to invoke the tool 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?

The tool has zero parameters, so the description need not elaborate on parameter meaning. The baseline of 4 is appropriate, and the description adds no extra parameter-related confusion.

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 the tool retrieves unified product categories and product counts, using a specific verb and resource. This distinguishes it from all sibling tools, which focus on products, prices, deals, and other specific 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?

No guidance is provided on when to use this tool versus alternatives. The description does not mention context, prerequisites, or compare against sibling tools like list_products or get_filter_stats, so an agent must infer usage solely from the tool name.

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 comprehensively indicate a read-only, idempotent, non-destructive operation, so the description does not need to repeat that. However, it adds no extra behavioral context such as authentication requirements, rate limits, pagination behavior, or return format, which would be valuable for an agent to invoke the tool 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 a single sentence that front-loads the core action and gives a concrete example. It is concise, informative, and free of unnecessary detail.

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 read-only tool with strong annotations and parameter schema, the description is largely complete. It clarifies the required parameter and the nature of results. However, the lack of an output schema and any mention of the response structure creates a minor gap, though not enough to significantly hamper selection or invocation.

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%, the description partially compensates by explaining 'type' as a promotion keyword with the example '1+1'. It does not address the 'limit' parameter, but that parameter's schema already provides default and bounds, so the meaning is reasonably clear. Overall, it adds value for the key parameter but is not fully comprehensive.

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 the tool retrieves products matching a promotion keyword, with '1+1' as a concrete example. This makes the purpose specific and largely distinguishes it from sibling tools like get_top_deals or get_brand_deals. However, the relationship between 'type' and 'promotion keyword' is slightly ambiguous, and it does not explicitly differentiate from get_promotional_products.

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 this tool is used when you need products matching a promotion keyword like '1+1'. It provides no explicit guidance on when not to use it or which alternative tools to prefer, so it stops at implied usage rather than clear directives.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-destructive read. The description adds no additional behavioral context beyond the word 'aggregate,' which is more about purpose than behavior. No contradictions.

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 concise sentence, front-loaded with 'Get aggregate deal and retailer statistics.' No unnecessary words.

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?

The tool has no output schema, and the description doesn't specify what 'deal and retailer statistics' includes (e.g., counts, averages, time periods). For an agent to know what response to expect, this is a gap. However, many sibling tools are similarly terse, and the annotations cover safety. It's minimally viable but not 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?

There are zero parameters, so the input schema fully documents the tool's inputs. The description doesn't need to explain parameters. Per the rubric, 0 params = baseline 4.

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 the specific verb 'Get' with a clear resource: 'aggregate deal and retailer statistics.' It distinguishes from sibling tools like get_top_deals by emphasizing aggregate statistics rather than individual deals. However, it doesn't specify what the statistics include, which slightly limits clarity.

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 tool versus the many sibling tools such as get_filter_stats or get_ean_stats. The description simply states what it does, leaving the agent to infer use cases. No explicit exclusions or alternatives are mentioned.

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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds the auth requirement ('Pro API key required') and the cross-retailer scope. It doesn't describe response format or rate limits, but the auth note is a valuable behavioral disclosure.

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 extremely concise, with two short sentences that convey the core purpose and a key prerequisite. No filler or redundancy.

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 empty schema and lack of output schema, the description provides the essential purpose and auth requirement, but it leaves ambiguity about what 'coverage statistics' specifically includes or the return structure. For a simple stats tool, it's marginally adequate but could be clearer.

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 input schema is empty (zero parameters), and schema coverage is 100%. With no parameters to describe, the description isn't required to add parameter details. The description does not reference any parameters, but the baseline for zero parameters is 4.

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 the specific verb 'Get' with the resource 'EAN coverage statistics' and scope 'across retailers,' clearly distinguishing it from sibling tools like get_price_history or get_forecast. It conveys precisely what the tool returns.

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 does not explicitly state when to use this tool versus alternatives, but the purpose statement implies usage for EAN coverage statistics. The 'Pro API key required' note is a prerequisite, not a usage guideline. No exclusions or alternative tools are mentioned.

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. The description adds that it returns faceted counts, which gives a bit of context about the output. However, it doesn't address behavior like pagination, filtering semantics, or what 'matching' refers to. Given annotations, this is adequate but not outstanding.

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?

Single sentence, no redundancy, direct. It is appropriately front-loaded with the core purpose.

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 5 parameters, the description is too terse. It omits return value structure, query parameter semantics, and any caveats. It covers only the surface purpose.

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 provides no descriptions for 5 parameters, and the tool description only mentions the dimensions (retailer, status, category, dietary) without explaining parameter semantics, value formats, or how q relates. With 0% schema coverage, the description fails to compensate.

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 the tool returns faceted counts for four dimensions (retailers, statuses, categories, dietary tags), using the specific verb 'get' and a resource. It distinguishes from sibling search tools by focusing on counts rather than product lists, though it doesn't explicitly name alternative 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?

The description offers no guidance on when to use this tool versus alternatives like search_products or get_categories. There is no mention of prerequisites or incompatible use 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 indicate read-only, idempotent, and non-destructive behavior. The description adds that the forecast is 'backtested' and conditional on history availability, which is useful context. However, it does not disclose what happens when insufficient history exists (e.g., empty result vs. error).

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 that is concise and includes only necessary information. No fluff or redundant phrases.

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 one-parameter tool with rich annotations, the description covers the purpose and a key condition. However, it lacks explicit details about the return value or behavior when enough history is absent, which would round out the 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 schema has full coverage for product_id with a descriptive label ('PrijsProfeet product ID'). The description does not add additional parameter-level detail beyond the schema, so the baseline of 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 clearly identifies the action ('get') and resource ('backtested price forecast for a product'), with a clear qualifier ('if enough history exists'). It is distinguishable from sibling tools like get_price_history, which likely provides historical data rather than a forecast.

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 tool is used when a forecast is needed and when sufficient history exists, but it does not explicitly compare to alternatives or state when not to use it. The condition 'if enough history exists' is a prerequisite but not a full usage guideline.

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds the time window (this week) and ordering (newest first), providing useful context beyond annotations, but it does not disclose additional behavioral traits such as pagination or result size limits beyond the schema's limit parameter.

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 a single sentence that is front-loaded with the core verb and resource, then specifies the time filter and sort order. Every word earns its place with no redundancy or 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?

For a simple read-only list tool with one optional parameter and no output schema, the description covers the essential purpose and distinguishing behavior. It could slightly improve by noting the limit parameter or what happens when no products are found, but overall it is reasonably complete given the tool's simplicity and the strong annotations.

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 schema has one parameter, 'limit', with default, min, and max constraints but no description. Schema description coverage is 0%, so the description must compensate, but it does not mention the limit parameter at all. The description adds no meaning beyond the schema's structural constraints, leaving the parameter's purpose entirely to inference from its name.

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 the tool retrieves products scraped this week, ordered newest first. It uses a specific verb and resource, and it distinguishes from sibling tools like get_top_deals or get_deals_summary by specifying the time window and sort order.

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 usage when the user wants recently scraped products, but it does not explicitly mention alternatives or when not to use it. It provides clear context but lacks exclusions or direct references to sibling tools, so it stops short of a 5.

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 read-only, non-destructive, and idempotent behavior. The description adds a useful behavioral detail: the requirement of an API key for authentication. It does not describe potential errors or what 'usage' encompasses, but given the strong annotation coverage, the added auth context is sufficient for a moderate score.

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 short sentences, immediately stating the primary function and the key prerequisite. Every word earns its place, with no redundant phrases or unnecessary details.

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 tool with zero parameters, no output schema, and a straightforward action, the description is largely complete: it explains what is retrieved and the required auth. Minor gaps exist around the exact response format or definitions of 'account' and 'rate-limit usage,' but these are not critical given the tool's simplicity.

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 has no schema parameters, so the baseline is 4. The description mentions the required API key, which is not a schema parameter but an external credential, adding context beyond the empty schema. There is no parameter ambiguity to resolve.

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 the tool's function: retrieving API-key account and rate-limit usage. The verb 'Get' and specific resource (usage) make the purpose precise, and it is distinct from sibling tools which focus on products, deals, or health checks.

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 usage context by stating it 'Requires PRIJSPROFEET_API_KEY,' which suggests it is for authenticated partners checking their usage. However, it does not explicitly mention when to use this over other tools or provide exclusions/alternatives, so the guidance remains implicit.

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 as read-only, idempotent, and non-destructive, covering the safety profile. The description adds the behavioral context of the seven-day time window and the 'most-clicked' ranking, but does not disclose pagination behavior, response format, or any other operational details. For a simple read-only tool with strong annotation coverage, this is acceptable but not rich.

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 a single, concise sentence that fully explains the tool's function. Every word contributes meaning, with no filler or redundancy. It is front-loaded with the action verb and immediately specifies the resource and criteria.

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 tool's simplicity (one optional parameter, no nested objects, no output schema) and strong annotations, the description is sufficiently complete for an agent to understand and invoke the tool. It could be improved by explicitly stating that the return value is a list of products, but the name and description sufficiently imply this. There is no ambiguity about the purpose or input.

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 schema defines 'limit' with type, min, max, and default, but the description provides zero context for the parameter. Since schema description coverage is 0%, the description was expected to compensate, but it never mentions how 'limit' affects results. The parameter name and schema constraints offer some semantics, but the description adds no value 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 clearly states the action ('Get'), the resource ('products'), and the specific criteria ('most-clicked', 'last seven days'). This distinguishes it from sibling tools like 'get_top_deals' or 'get_deals_summary' by specifying a unique metric and time window.

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 tool is for retrieving popular deals based on clicks in the last week, but it provides no explicit guidance on when to use this tool versus alternatives like 'get_top_deals' or 'get_deals_by_type'. No exclusions or alternative recommendations are given, so the usage context is only implied.

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 tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond annotations by specifying the authentication requirement (PRIJSPROFEET_API_KEY with Pro access). This is exactly the kind of context (auth needs) the rubric credits. No contradiction with annotations.

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 short sentences, front-loaded with the action and immediate requirement. Every word earns its place with no filler or redundant content. This is a model of conciseness.

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 tool with one parameter and no output schema, the description provides the essential context: what it does and the access requirement. It does not describe the return format or data granularity, which could be helpful in the absence of an output schema, but this is a minor gap given the tool's simplicity and strong annotation coverage.

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 input schema fully describes the only parameter, product_id, with a description. Since schema_description_coverage is 100%, the baseline is 3. The description does not add any additional parameter-level semantics beyond what the schema already provides, so it earns the baseline exactly.

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 the tool's action: 'Get Pro price history for a product.' This specifies the verb (get), resource (price history), and scope (Pro), distinguishing it from siblings like get_forecast (future predictions) and get_product (product details). The purpose is unambiguous and specific.

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 usage context by stating the requirement 'Requires PRIJSPROFEET_API_KEY with Pro access,' which indicates when the tool can be used. However, it does not explicitly compare to alternatives or state when not to use it. The guidance is implied rather than explicit, so it does not fully meet the 'clear context with exclusions' bar.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the behavioral detail that it retrieves exactly one product (not a list) by unique ID, which is a modest addition beyond annotations.

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 a single sentence, front-loaded with the verb and resource, and contains zero wasted words. It is appropriately concise for a simple 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?

Given the simplicity of the tool (one required parameter, rich annotations, and no output schema), the description is nearly complete. It clearly states what the tool does, and the schema covers the parameter. A minor gap is the lack of mention of error behavior (e.g., not found), but this is not critical for a basic getter.

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 input schema has 100% coverage for product_id, including a description 'PrijsProfeet product ID'. The tool description's phrase 'unique ID' is consistent but does not add meaningful format or syntax details beyond the schema, so it meets the baseline.

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 'Get' with a clear resource 'one product' and identifies the key by 'unique ID'. It clearly distinguishes from sibling tools like list_products and search_products by indicating a single product lookup by ID.

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 usage: use this tool when you have a unique product ID and need that one product. However, it provides no explicit guidance on when not to use it or mentions alternatives such as search_products_by_name or list_products.

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 and destructiveHint=false, so the safety profile is clear. The description adds pagination behavior, but does not disclose return format, error conditions, or interaction with openWorldHint. It doesn't contradict annotations.

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 short sentence, front-loaded with the verb and resource, no filler. It is appropriately concise.

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?

The description is extremely minimal. While the annotations cover safety and idempotency, the lack of output schema and low parameter documentation means the description does not fully orient the agent on pagination defaults, folder_id meaning, or what the response contains. However, the tool is simple and the annotations add 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 input schema describes only 1 of 3 parameters (33% coverage). The description mentions pagination, which loosely relates to page and page_size, but does not explain folder_id or the semantics of pagination parameters, nor does it compensate for the missing schema descriptions.

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 the specific verb 'Get' with resource 'products from a folder' and notes pagination, which clearly distinguishes it from sibling tools that operate on other scopes (e.g., retailers, promotions).

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 guidance is provided on when to use this tool versus alternatives like list_products or search_products. The description simply states what it does without contextual usage instructions.

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 tool read-only, idempotent, and non-destructive. The description adds the behavior of pagination, which is useful context beyond the annotations, though it doesn't detail response format or rate limits.

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?

Single sentence, 'Get products for one retailer with pagination.' Six words, front-loaded, 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?

For a simple read tool with annotations and a clear schema, the description is mostly adequate. It covers the core action, scope, and pagination, though it omits ordering/response details and explicit alternative selection.

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 covers page and page_size with descriptions, and retailer has an enum. The tool description adds no parameter-specific meaning beyond the schema, so with 67% schema coverage it does not compensate for the missing retailer description but the enum covers itself.

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 specifies 'Get products for one retailer with pagination' – a clear verb-resource-scope combination. The phrase 'one retailer' distinguishes it from the broad list_products or get_product 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?

The description implies usage when retrieving products for a specific retailer, but it does not mention alternatives or exclusions. Sibling tools like search_products_by_name or list_products exist, yet no guidance is given on when to choose this one.

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, and destructiveHint=false, covering the safety profile. The description adds that the tool returns only promotional products and can be filtered by retailer, which is a modest behavioral clarification, but it does not explain pagination behavior or the returned data structure beyond the implied list of products.

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 a single, front-loaded sentence with no redundant words. It conveys the essential purpose and the main optional parameter without unnecessary elaboration.

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?

The tool is relatively simple, and the annotations cover safety and idempotency. However, with no output schema and a minimal description, the agent is not informed about pagination, return format, or how results are ordered. The schema provides defaults and limits for page/page_size, but the description does not tie these together into a complete operational picture.

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% (only 'page' has a schema description). The tool description clarifies the 'retailer' parameter by stating it is an optional filter, but it does not explain 'page' or 'page_size' semantics beyond what the schema provides, leaving the agent without additional guidance for pagination.

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 the verb 'Get' with the resource 'promotional products' and adds an optional retailer filter, clearly indicating what the tool does. The qualifier 'promotional' distinguishes it from general product listing tools like list_products, though it does not explicitly reference sibling 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?

The description gives no guidance on when to use this tool versus alternatives such as list_products or get_products_by_retailer. It mentions an optional retailer filter, but does not state any exclusions, prerequisites, or scenarios where this tool is preferred.

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 provide readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds behavioral context about ranking by savings percentage/amount and optional retailer filtering. However, it does not mention output format, ordering direction, or other runtime behavior, so it adds modest value beyond annotations.

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 a single sentence of 15 words, directly starting with the verb and resource. It contains no redundant information and is easy to parse.

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 read-only list tool with three optional parameters and no output schema, the description covers purpose and key parameters. The annotations cover safety. However, the ambiguous phrase 'repeatable retailer slugs' and absence of any indication about the output format or default sorting direction leave minor gaps in completeness, especially given the crowded sibling tool set.

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 partially does by mapping 'retailer slugs' to the `retailer` parameter and 'savings percentage and amount' to `min_savings`. However, it does not explain the `limit` parameter, and 'repeatable' is unclear. This is insufficient to fully compensate for the lack of schema descriptions.

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 'Get top deals by savings percentage and amount' – a specific verb, resource, and ranking criterion. It distinguishes from sibling deal tools like get_popular_deals by focusing on savings. However, 'repeatable retailer slugs' is somewhat ambiguous and does not fully differentiate among the many deal-related siblings.

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 use when the agent needs top deals ranked by savings, optionally filtered by retailer. It does not explicitly mention alternatives or when not to use it, especially given numerous sibling tools like get_popular_deals and get_deals_by_type. The lack of explicit exclusions makes the guidance only implied.

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, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds the domain (PriceProfeet) but doesn't disclose what the response looks like or what happens if services are not operational. It provides minimal behavioral context beyond the annotations.

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 a single front-loaded sentence with no wasted words. It fully conveys the tool's purpose efficiently.

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 tool's simplicity (no params, no output schema), the description adequately covers the use case. It could mention the return format, but for a health check with strong annotations, the description is nearly 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?

The tool has zero parameters, and schema coverage is 100% vacuously. The description doesn't need to explain parameters. Baseline for zero params is 4, which 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 uses a specific verb ('Verify') and resource ('PriceProfeet services') with a clear outcome ('operational'). It distinctly separates this tool from all sibling data-access tools, making its purpose unmistakable.

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 clearly implies the tool is for checking service operational status. While it doesn't explicitly mention alternatives or exclusions, the sibling tools are all data-focused, so context makes the appropriate use obvious.

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, and destructiveHint=false, so the safety profile is known. The description adds little beyond what the schema shows; it mentions filters, sorting, and pagination, but no additional behavioral details like result limits or potential empty results. No contradiction with annotations.

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 a single, front-loaded sentence that immediately identifies the tool's purpose. It avoids verbosity, though the phrase 'with filters, sorting, and pagination' is somewhat redundant given the schema. Overall, it is appropriately concise and 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?

Despite having 9 parameters and no output schema, the description provides almost no contextual guidance. It does not explain default behavior, response format, or how filters interact. With many sibling tools, it also lacks guidance on when this general list is appropriate. The description is too thin for the tool's complexity.

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 22%, with most parameters having no description. The description's generic mention of 'filters, sorting, and pagination' does not explain individual parameters like min_price, retailer, or is_promotional. It fails to compensate for the sparse schema, leaving the agent without meaningful parameter 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 clearly states the tool lists products, with the verb 'List' and resource 'products'. It mentions filters, sorting, and pagination, which distinguishes it as a general-purpose listing tool compared to siblings like get_products_by_retailer or get_promotional_products. However, it does not explicitly name sibling alternatives or contrast them.

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 guidance is provided on when to use this tool versus the many sibling tools. There is no mention of intended use cases, exclusions, or alternatives. The description simply states capabilities without advising when to choose this over get_products_by_folder or search_products.

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, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond these: the authentication requirement ('Pro API key required') and the semantics of non-current matches ('may be upcoming or historical unless current_only is true'). This clarifies default behavior without contradicting annotations.

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 three short, front-loaded sentences with no redundant wording. Each sentence adds distinct information: purpose, requirement, and behavioral nuance.

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 read-only lookup tool, the description covers purpose, a prerequisite, and a key behavioral aspect. It does not explain the 'exclude_retailer' parameter or return format, but the absence of an output schema and the presence of strong annotations reduce the need for extra detail. Overall, the essential context is provided.

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 only indirectly references 'current_only' through the clause 'unless current_only is true', but does not explain 'exclude_retailer' or its behavior. The 'ean' parameter is obvious from the name, but the lack of explicit parameter semantics for most fields leaves a notable 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 uses a specific verb ('Find') and a specific resource ('products with the same EAN across retailers'), making the tool's core purpose immediately clear. It also implicitly distinguishes itself from sibling tools like 'match_product' or 'search_products_by_name' by focusing on EAN-based cross-retailer matching.

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 states a usage prerequisite ('Pro API key required') but does not explicitly compare with alternatives or state when to use this tool over siblings. The phrase 'across retailers' hints at its unique role, but there is no direct 'use this instead of X' guidance.

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, open-world, idempotent, and non-destructive. The description adds meaningful context beyond annotations: Pro API key requirement and the fact that non-current matches may be upcoming or historical unless current_only is true. This gives the agent important behavioral nuance about returned data scope.

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, front-loaded with the core action, no filler. Every clause adds value: purpose, access requirement, and a clarifying flag behavior.

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?

Covers the main purpose and one key flag, but omits explanation of include_same_retailer and does not describe the output shape. With no output schema, the description could be more complete, though the tool appears simple and the open-world annotation mitigates some ambiguity.

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 low (only product_id documented). The description adds meaning for current_only by explaining that false/non-current results may include upcoming or historical matches, but it says nothing about include_same_retailer. Partial compensation; clear gap remains for one parameter.

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: 'Find a product at other retailers.' It does not explicitly distinguish from match_by_ean, but the name and required product_id imply matching by product ID rather than EAN, which nearby sibling names make discernible. Slightly differentiated but not 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?

States a prerequisite (Pro API key required) and explains the current_only flag's effect. However, it does not explicitly state when to prefer this tool over alternatives like match_by_ean or compare_prices, nor does it offer exclusions. Usage context is implied rather than fully specified.

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 assert non-read-only, non-idempotent behavior with openWorldHint. The description adds concrete context: it emails a free API-key link and is rate limited to five requests per hour per IP. This rate-limit disclosure and delivery mechanism go beyond the structured annotations, enhancing transparency.

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 extremely concise: two sentences that front-load the primary action and then add the rate-limit constraint. Every word earns its place; there is no redundant or vague 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?

The tool is simple and the description covers the action, delivery mechanism, and a key constraint (rate limit), which is adequate for a request tool with no output schema. However, it omits any mention of project_name/site_url semantics or what the user should expect after requesting, leaving minor gaps.

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 input schema has 0% description coverage, so the description is the only source of parameter meaning. It clarifies email's role via 'email a free API-key link,' but project_name and site_url are completely unexplained. Two of three parameters therefore remain semantically ambiguous.

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 ('Ask') and resource ('PriceProfeet to email a free API-key link'), making it clear this is a request action. It distinguishes itself from all sibling tools, which are read-oriented (get, list, search, compare), so there is no ambiguity about its unique purpose.

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 clearly implies when to use the tool: when you need a free API key. Since the sibling tools are all read operations, there is no alternative that performs a similar action, so context is sufficient. However, it does not explicitly state exclusions or contrast with alternatives, so it falls just short of full guidance.

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 behavior, covering the safety profile. The description adds the 'fuzzy search' behavioral trait, which is useful. However, it does not disclose what happens when no query is provided, whether results are limited to promotions or include all products, or the response format/pagination behavior beyond the schema. No contradiction with annotations.

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 a single, information-dense sentence that front-loads the core action ('Fuzzy search and browse promotions') and lists the filter dimensions without unnecessary words or repetition. Every phrase contributes value, making it highly efficient for an agent to parse.

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 tool with 12 parameters and no output schema, the description provides a sufficient overview for selecting the tool, but lacks commentary on the return shape, default behavior when no parameters are supplied, and the specifics of fuzzy matching. Annotations cover safety, but the description does not fully compensate for the absent output schema and low parameter description coverage.

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 helps by enumerating filter categories (status, type, price, savings, sorting) that map to specific parameters. Yet it does not explain the search term q, acceptable values for sort_by or promotion_type, or the meaning of 'type' beyond the parameter name. It partially compensates for the schema's lack of descriptions but leaves several parameters semantically 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?

The description clearly states the tool's function: 'Fuzzy search and browse promotions' with a specific list of filters. It distinguishes itself from siblings like list_products or search_products_by_name by emphasizing fuzzy matching and a wide range of filter dimensions (retailer, category, status, type, dietary, price, savings, sorting, pagination). The title 'Advanced product search' reinforces this differentiation.

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 a use case—searching products/promotions with complex filters—but does not explicitly state when to use this tool versus alternatives such as search_products_by_name or get_promotional_products. There are no exclusions, prerequisites, or direct references to alternative tools, so the agent must infer applicability from the filter list.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the tool's safety profile is well covered. The description adds the retailer filter behavior but does not disclose additional behavioral details like matching semantics or sorting. With annotations providing the baseline safety info, this is acceptable.

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 a single, front-loaded sentence that directly states the tool's purpose and the key optional parameter. No redundant or extraneous information is present.

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 filtered-list tool with comprehensive annotations and pagination parameters in the schema, the description covers the core behavior and key filter. It does not explicitly state the return format, but this is inferable for a search tool and not a severe gap given the tool's simplicity.

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 description clarifies the role of the two undocumented parameters: 'query' is the product name and 'retailer' is the filter. This meaningfully compensates for the 50% schema description coverage, while page and page_size are already described 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 states the specific verb 'search' plus the resource 'product collection' and the scope 'by name', which clearly distinguishes it from sibling tools like search_products or get_products_by_retailer. The optional retailer filter adds a distinguishing capability.

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 clearly communicates the intended use case: searching products by name with an optional retailer filter. However, it does not explicitly name alternatives or state when not to use this tool, so it lacks explicit exclusion guidance.

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