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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this writes data without being destructive. The description confirms the activation action but adds no context on idempotency, reversibility, authentication needs, or what happens to already-activated offers.

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

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

A single, front-loaded sentence with no filler. Every word contributes to stating the action and its target.

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 (2 required params, no output schema) and the description covers the core action, but for a mutation tool it omits any usage context or caveats. It is adequate but with clear gaps given the annotations leave room for richer behavioral detail.

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%, so both parameters are already fully documented. The description references 'Bonus card number' and the selected promotions but adds no format, constraint, or usage detail beyond what the schema provides.

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

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

The description states a specific verb ('Activate') and resource ('selected weekly Bonus Box promotions') and ties it to a required input ('given Bonus card number'). It is clearly distinct from the read-only sibling ah_get_personal_bonus, though it does not name that sibling explicitly.

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

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

The description gives no when-to-use guidance, no prerequisites, and no mention of the obvious alternative ah_get_personal_bonus. An agent must infer that this is the mutating counterpart to the read-only bonus tools.

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=false and destructiveHint=false, but the description adds the meaningful context that this mutates the user's real Albert Heijn account. It does not explain idempotency, duplicate handling, or what happens on unknown free text, but the side-effect warning is genuinely additive.

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

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

Two short sentences, zero filler, with the operation stated first and the write warning second. Nothing redundant or 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?

For a single-parameter mutation tool with no output schema and annotations already covering the safety profile, the description is nearly adequate. It omits return behavior, auth/prerequisite requirements, and duplicate/error handling, which would matter for a real-account write.

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

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

Schema description coverage is 100%, so the schema already documents the items array and the text/product_id fields with examples. The description only restates the same union ('free-text items or products') without adding format, length, or batch-limit guidance, 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 (add) plus resource (shopping list), and clarifies the accepted input forms ('free-text items or products'), which cleanly separates it from ah_get_shopping_list and ah_remove_from_shopping_list. An agent can identify the operation without opening the schema.

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

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

There is a clear implied context (adding groceries), and the 'WRITES to the real AH account' note signals this should be used deliberately rather than speculatively. However, no explicit when-to-use guidance or alternatives are given, e.g. whether a product_id from ah_search_products is preferred over free text.

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?

readOnlyHint=true already declares the safety profile, and the description adds real value by disclosing the report contents (hits, misses, hit rate, stored entries, evictions), which substitutes for the missing output schema. Minor gap: it does not say the cache is in-process per session or that stats cannot be reset.

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 waste: the first front-loads the reported metrics, the second supplies the purpose. Nothing is redundant or buried.

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, listing the reported fields is the right compensation and covers most of what an agent needs. It could be slightly more complete by noting the stats are session-scoped and read-only with no reset.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies a no-argument call and adds no misleading parameter language.

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 ("Report the in-process response cache") and enumerates the exact metrics returned: enabled state, hits, misses, hit rate, entries, evictions. This is clearly distinguishable from every sibling, which are all Albert Heijn data-retrieval 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?

Gives an explicit use case: verify that cached AH responses are reused instead of re-fetched, i.e. a diagnostic/verification tool. It does not name alternatives or state when not to call it (e.g. it is not a cache-clearing tool), so it stops short of full routing 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=false and destructiveHint=false, so the agent knows this mutates state without destroying it. The description adds the toggle semantics ('as collected', checked=true/false), but says nothing about idempotency, auth requirements, or side effects on the surrounding list.

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 well-formed sentence with no filler, and the core verb/action is front-loaded. Slightly loose phrasing ('tick off as collected') is the only minor cost.

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 3 fully-documented params there is little risk of mis-invocation, but there is no output schema, so the description could reasonably say what the toggle returns or whether the change is reflected immediately. Auth/session expectations from ah_login are also unstated.

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% and each parameter is documented, so the schema does the heavy lifting. The description's checked=true/false phrasing duplicates the schema's own 'true to check, false to uncheck' wording and adds no new meaning; baseline 3 is appropriate.

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

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

The description names a specific verb pair (tick off / un-tick) and the resource (an item in a favorite list), so the operation is unambiguous. It does not, however, distinguish itself from siblings like ah_get_favorite_lists or ah_add_to_shopping_list, leaving the agent to infer the boundary.

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 description conveys that this tool toggles an item's collected state, which implies when it applies, but it never says when to choose it over ah_get_favorite_lists or how it relates to list-mutating siblings. No prerequisites or exclusions are given.

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?

readOnlyHint already covers the safety profile, so the description's added value is staleness and volume: it discloses a 30-minute cache and warns that the folder spans far more than one page. That is real behavioral context beyond annotations. It stops short of describing the response shape or whether pages are stable/ordered while cached.

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 with zero filler, front-loading what the tool returns (discounts, promotion types, validity) before pagination mechanics and caching. Each sentence contributes a distinct fact.

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

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

For a simple two-param read tool with no output schema, the description covers scope, promotion examples, pagination strategy and cache freshness. The only remaining gap is what an offer record actually contains, which an agent must discover by calling.

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%, with defaults, min/max and descriptions already supplied for both page and limit. The description only adds the iteration hint to 'walk page with limit to see more of it', which is useful but does not add depth on limit bounds or page indexing. 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: browsing 'active national Bonus folder discounts, promotions ... and validity windows'. The word 'national' implicitly separates it from the personal-bonus siblings, but the description never names those siblings explicitly, so differentiation is inferential 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 is implied by 'Browse active ... discounts', and the pagination advice gives a practical cue for larger result sets. However, it gives no explicit when-to-use-this-vs-alternative guidance, e.g. versus ah_get_personal_bonus or ah_get_promo_digest, and no exclusions.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful behavioral context beyond the annotation by stating that the cart is always fetched live and never cached, which tells the agent the data freshness profile.

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 with zero waste. The read-only nature and resource are front-loaded, and the freshness detail follows immediately.

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 zero-parameter read tool with readOnlyHint and no output schema, the description covers the resource, the read-only nature, and freshness behavior. It is nearly complete, though it could mention authentication requirements if the cart requires a logged-in user.

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 baseline score is 4. There are no parameter semantics to explain, and the empty schema is straightforward.

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

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

The description states a specific read-only action on a specific resource: the user's active Albert Heijn online shopping cart and order summary. It is clear enough for an agent to know what the tool does, but it does not explicitly distinguish this cart view from sibling tools like ah_get_shopping_list.

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 name and description — read the active cart — but there is no explicit guidance on when to use this instead of a sibling such as ah_get_shopping_list or ah_get_receipt_details. No exclusions or alternative routing are given.

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, and the description adds a genuine behavioral trait beyond them: results are cached for up to 24 hours, which matters for freshness expectations. It doesn't cover auth requirements or return shape, but for a read-only lookup the caching note is meaningful added context.

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

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

Two tight sentences: purpose and examples first, caching caveat second. No filler, nothing buried.

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 zero-parameter, read-only lookup with no output schema, the description covers purpose, sample values, and caching behavior – enough to call it correctly. Explicit routing relative to ah_get_sub_categories would complete it.

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 takes zero parameters, so the baseline is 4. The description correctly implies a no-argument listing call and introduces no parameter 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?

States a specific verb and resource ('Get top-level supermarket product shelves and categories') and gives concrete examples (Aardappel/groente/fruit, Bakkerij, Zuivel). The word 'top-level' distinguishes it from the sibling ah_get_sub_categories without ambiguity.

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 'top-level' framing implies this tool is the entry point before drilling into ah_get_sub_categories, but the description never explicitly names that sibling or states when to prefer it over ah_search_products. 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 readOnlyHint=true, so safety is covered. The description adds genuine context beyond that: results are cached for up to 30 minutes, meaning data can be stale, and the markdowns are 'today-only' and dynamic. It stops short of describing the return payload or how discounts are represented.

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

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

Two tight sentences, zero padding. The scope-defining qualifier and the caching caveat each appear once and are front-loaded where an agent will read them.

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 single-parameter read tool with annotations and no output schema, the description covers scope, dependency (store ID from store search), and freshness. The only gap is that it never characterizes the response shape — presumably a product list with markdown prices — which would help the agent know what to do with results.

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?

Only one parameter, and schema description coverage is 100% — the schema already tells the agent it is a store ID number from ah_search_stores. The description adds nothing about the parameter beyond restating 'for a given store ID', 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?

States a specific verb ('Fetch') and a precisely scoped resource ('today-only dynamic clearance markdowns (*vandaag-af* / 35% discount items) for a given store ID'). This clearly distinguishes it from broader siblings like ah_get_bonus_offers or ah_search_products, 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?

Usage is implied rather than stated: the schema's parameter description points to ah_search_stores as the source of store_id, establishing a workflow prerequisite. There is no explicit when-not guidance or comparison to alternative offer/markdown tools (e.g. ah_get_bonus_offers).

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 readOnlyHint annotation already covers safety. The description adds that the result includes item counts, which is a small behavioral detail. It omits auth requirements, ordering, empty-list behavior, and whether list IDs are returned.

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 front-loaded sentence with no wasted words; the key resource and the returned detail come first.

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 zero-parameter read-only tool with no output schema, the description conveys the essential return content (favorite lists with item counts). It stops short of describing the return shape, such as whether list IDs are included, which downstream tools might need.

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 baseline is 4. There is nothing further for the description to document beyond the empty 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 specifies a verb ('Get'), a resource ('saved custom favorite lists'), and adds concrete examples ('Weekly Staples', 'Party') plus the returned datum ('item counts'). This distinguishes it from the sibling ah_get_shopping_list by referring to saved custom lists, though it does not explicitly name that sibling or state the difference.

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

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

No when-to-use guidance, no alternatives, and no prerequisites are given. The description only states what it returns; it does not say when an agent should call this instead of ah_get_shopping_list or ah_check_favorite_list_item.

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?

Adds two genuinely useful traits beyond the readOnlyHint annotation: the fixed result cardinality (5 promotions) and a 30-minute cache window, which tells the agent not to poll for freshness. It stops short of stating that results depend on an active login session or what happens if the member has no offers.

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

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

Two short sentences, zero filler, with the resource and scope front-loaded and the caching caveat appended. Every clause carries information an agent would otherwise have to guess.

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 return-value burden but only supplies the count and the domain concept 'Bonus Box promotions'. That is enough to select and call the tool, though slightly thin on what a promotion entry contains compared with the sibling bonus-offer tooling.

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 takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The implicit assumption that identity comes from the session rather than an argument is consistent with the empty 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?

Specific verb and resource with concrete scope: exactly 5 personalized weekly Bonus Box promotions for the logged-in member. However, it never distinguishes itself from siblings like ah_get_bonus_offers, ah_get_promo_digest, or ah_activate_personal_bonus, so an agent must infer the boundary from the name alone.

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 'logged-in Albert Heijn member' framing hints that authentication is a prerequisite, and 'weekly Bonus Box' implies a once-a-week promotional check. No when-not conditions, no naming of ah_get_bonus_offers or ah_get_promo_digest as alternatives, and no hint that ah_activate_personal_bonus is the follow-up action for these offers.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful behavioral context by disclosing that results are cached for up to 30 minutes, though it does not describe return format or any authentication requirements.

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 compact sentences with the core purpose front-loaded and the cache detail following. Every sentence adds useful information without waste.

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 zero-parameter read tool with no output schema, the description gives enough context to know what it returns at a high level and that caching affects freshness. It could be slightly more complete with a note on return shape or auth, but it is adequate.

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 there is no parameter semantics to explain. The schema is empty and no compensation is needed, matching the baseline for a no-parameter tool.

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

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

The description states a specific verb and resource: fetch predictive favorite recommendations and frequently reordered products. The word 'predictive' implicitly distinguishes it from actual favorite-list tools like ah_get_favorite_lists, but no sibling is named explicitly.

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

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

Usage is implied by 'predictive favorite recommendations' and 'frequently reordered products,' suggesting this is for recommendation retrieval. However, it does not explicitly say when to choose it over related tools such as ah_get_favorite_lists or ah_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?

readOnlyHint=true already tells the agent this is a safe read. The description adds genuinely useful non-annotation context — results are cached up to 24 hours, so pricing/staleness may lag. It stays silent on auth requirements and on what happens for an unknown or delisted product ID.

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 returned-field list, and the caching caveat is a distinct, non-redundant fact. No filler, though the field enumeration could have been compressed into a single clause.

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 read-only single-parameter lookup with no output schema, the description covers the returned data and freshness, which is most of what an agent needs. Missing only error/not-found behavior for an invalid product ID.

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?

Only one parameter and schema coverage is 100%, with example formats ('wi196825' or '196825') already in the schema. The description adds nothing about the ID beyond what the schema states, 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?

Specific verb ('Get detailed information') plus resource ('a specific Albert Heijn product'), and it enumerates the returned fields (description, nutrition, allergens, sizes, pricing). It only implicitly differentiates from ah_get_products_bulk / ah_search_products via the word 'specific', never naming an alternative.

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: 'a specific product' suggests single-item lookup rather than the bulk/search siblings, but there is no explicit when-to-use statement, no exclusion, and no pointer to ah_get_products_bulk for multi-item needs.

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, so the safety profile is covered. The description adds one genuine behavioral fact — results are cached up to 24 hours — which tells the agent data may be stale. It says nothing about how many alternatives come back, whether they are ranked, or what happens when no substitute exists.

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, purpose first and the caching caveat second. No wasted words and nothing buried.

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 required parameter and no output schema, the description is nearly sufficient, but it never indicates what an alternative looks like (product IDs, names, prices) or what an empty result means. For a lookup tool with no return-value documentation anywhere, that is a real gap.

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 parameter even carries a format example ('wi196825' or '196825'), so the description adds nothing on parameters. Baseline 3 applies since the schema does the work.

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?

Specific verb ('Find') plus resource ('alternatives, store-brand swaps, dietary substitutes for a product') gives an unambiguous purpose that is naturally distinct from ah_get_product. It stops short of naming the sibling it displaces, so an agent must infer that this is the 'what else could I buy' tool rather than the 'details for this item' tool.

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 enumerated substitute types imply when the tool is useful, but there is no explicit routing guidance such as 'use ah_get_product for full details on a single item' or any stated precondition. Usage is inferable but not 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=true, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond the annotations: results are cached for up to 24 hours, which tells the agent data may be stale and that repeat calls are cheap. It stops short of describing error behavior for invalid IDs.

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 waste: the core action plus its scope comes first, followed by the caching caveat. Nothing is repeated or 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?

For a single-parameter, read-only lookup with full schema coverage and no output schema, this covers what an agent needs to select and call it. The only gap is the absence of any batch-size or failure-mode guidance for the bulk aspect.

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 there is only one required parameter, so the schema already carries nearly all semantics (array of strings, minItems 1). The description's example ID list duplicates the schema example rather than adding format rules such as batch limits or ID validation.

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 ('fetch product details') and explicitly scopes it to bulk retrieval across multiple Albert Heijn product IDs, with a concrete ID example. The 'bulk' framing implicitly separates it from the singular ah_get_product sibling, though it never names that alternative.

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 bulk-for-multiple framing implies when this tool is preferred over the single-product sibling, but no explicit 'use ah_get_product when you only need one' guidance or size/rate caveats are given. Usage is inferable from the description 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds value by disclosing the returned data shape (name, email, Bonus card number) in the absence of an output schema, but says nothing about authentication requirements or error behavior for a tool sitting next to ah_login.

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

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

A single front-loaded sentence with no filler; every clause (profile, name, email, Bonus card number) conveys concrete information.

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 parameterless read tool with annotations covering the safety profile, the description supplies the return fields that an output schema would otherwise provide. The only gap is the unstated login prerequisite, which matters given ah_login is a sibling.

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 takes zero parameters, so the baseline of 4 applies. Nothing in the description is needed to clarify inputs, and it correctly does not invent any.

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 (Get) and resource (customer loyalty profile) and enumerates the returned fields, including the distinctive '13-digit Bonus card number'. No sibling tool retrieves a profile, so the purpose is unambiguous, though it doesn't explicitly contrast with any sibling.

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

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

There is no when-to-use guidance, no mention that ah_login is a prerequisite, and no indication of what happens if the user is not authenticated. Usage is only implied by 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 only cover readOnlyHint, so the description carries the rest and does so well: it discloses that receipts are paged back to the oldest receipt in the window, capped at 150, meaning results can be incomplete for long histories. It does not mention expected latency for a scan of that size or what the digest's result shape looks like.

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, and the user-facing question is front-loaded before the implementation detail. Every clause earns its place by either scoping intent or disclosing the scan strategy.

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 filtered analysis tool with a fully documented schema and a readOnly annotation, this covers the essentials: what it answers, how it scans, and the 150-receipt ceiling. With no output schema present, a brief note on what the digest returns (offer plus purchase frequency, presumably) would have closed the remaining gap.

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 all three parameters are already documented with defaults and bounds. The description adds only loose conceptual mapping ('requested window' for days, 'frequently buy' for min_times) and never mentions the limit parameter or how the 150-receipt cap interacts with days.

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 chain (mines receipts, cross-references against active offers) and the exact user question it answers, which pins the resource to 'frequently bought items currently on Bonus discount'. It is distinguishable from ah_get_bonus_offers and ah_list_receipts by implication, but never names either sibling.

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

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

The quoted question 'of the things I frequently buy, what is on Bonus discount right now?' gives clear context for when to reach for this tool. There is no explicit exclusion or named alternative for the plain bonus-offer or receipt-listing cases, so the agent must infer the boundary itself.

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, so safety is covered and the description earns credit for adding real context beyond them: closed receipts are immutable and cached for 30 days, telling the agent results may be stale and cannot change. It stops short of covering failure behavior — what happens for an unknown or still-open transaction ID — which is the one gap 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?

Two sentences, zero padding. The payload contents come first and the caching caveat second, matching the order in which an agent needs that information.

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 required parameter, no output schema and only a read-only annotation, the description carries the right load: it enumerates the returned fields and explains caching. It could go one step further by noting error behavior for invalid or non-closed receipt IDs, which is the only meaningful omission for a single-ID lookup.

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?

Only one parameter, with 100% schema description coverage that already says it is the receipt transaction ID sourced from ah_list_receipts. The description adds no format, validation or edge-case detail beyond the schema, 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 (get), a specific resource (a single store receipt) and enumerates exactly what comes back: line items, unit prices, discounts and total. That enumeration plus the singular 'specific store receipt' separates it cleanly from the sibling ah_list_receipts without requiring the agent to open either schema.

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

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

Usage is only implied: the singular receipt plus the transaction_id requirement signals 'call this after ah_list_receipts, with an ID from that list', but the description never names the sibling or states the when-to-use condition. The routing hint lives in the schema's parameter text rather than in the description, so the guidance is present but indirect.

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, so the safety profile is covered. The description adds valuable behavioral context: caching for up to 24 hours and that the ingredient list includes product mappings, which goes beyond the annotation and helps set expectations about data freshness and return content.

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, both front-loaded and information-dense: the first states what is returned, the second adds caching behavior. No wasted 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?

There is no output schema, so the description must convey return values. It does so reasonably well by naming 'full cooking steps' and 'structured ingredient list (with product mappings)'. Minor gaps remain about what 'full cooking steps' entails, but overall it is complete enough for a simple read-only tool.

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

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

Schema description coverage is 100% and the single parameter (recipe_id) is fully documented in the schema with an example. The description adds no additional parameter-level detail, which is appropriate given the schema completeness.

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

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

The description states a specific verb ('Get') and resource ('full cooking steps and structured ingredient list') for an Allerhande recipe. It distinguishes itself from the search sibling implicitly by focusing on detailed recipe content, but does not explicitly name or contrast with ah_search_recipes.

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 purpose: use when you need full details for a known recipe ID. However, there is no explicit guidance on when to use this versus ah_search_recipes, nor any prerequisites or exclusions 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=true, so safety is covered; the description adds a non-obvious behavioral trait — results are cached for up to 30 minutes, so suggestions may be stale. That is genuine value beyond structured data, though nothing is said about result shape or ranking.

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 the core purpose front-loaded and the caching caveat as a secondary clause. Nothing is redundant or 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?

For a two-parameter read tool with full schema coverage and annotations, this is nearly complete, but there is no output schema and the description never indicates what a suggestion looks like (plain strings vs. objects with labels/hrefs). That leaves a small but real gap for an agent consuming the result.

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' and 'limit' documented in the schema, so the description needs no parameter detail. It adds nothing beyond the schema but does not need to; 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 ('get search autocompletion suggestions and related grocery query keywords') plus the provider, which is enough to separate it from ah_search_products or ah_search_recipes. It does not explicitly name the sibling it contrasts with, so it stops 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?

The word 'autocompletion' implies the intended use (typeahead / prefix completion rather than full product search), but there is no explicit when-to-use, when-not-to-use, or pointer to ah_search_products for full searches. Usage is inferable but not 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=true, so safety is covered; the description adds genuinely new behavior – that results are always fetched live and never cached, which matters for freshness expectations. It does not cover auth prerequisites or behavior when the list is empty, keeping it below 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?

Two short sentences, front-loaded with the resource identity, then the freshness caveat. Every clause carries information; nothing is padding.

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

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

With no parameters and no output schema, the description usefully sketches the return contents and the no-cache behavior. Minor gaps remain around authentication requirement and empty-list handling, but nothing essential to invoking it 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?

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 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+resource ('Get the user's primary in-app shopping list'), names the native term 'Boodschappenlijst', and enumerates the returned content (items, notes, checked states). The qualifier 'primary' separates it from the sibling ah_get_favorite_lists.

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 read-oriented framing implies when this is used, but nothing states when to prefer it over ah_get_favorite_lists or when not to call it (e.g. no list yet). Usage must be inferred from the purpose 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered, and the description adds a genuinely non-obvious trait: results are cached for up to 24 hours, warning about staleness. It does not cover failure behavior for invalid IDs or result ordering, 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?

Two sentences, zero waste, with the core action front-loaded and the caching caveat as a compact second sentence.

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 single-parameter read with annotations covering safety and no output schema, this is nearly complete. The one residual gap is that nothing tells the agent where a valid category_id comes from.

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 parameter is fully documented, so baseline 3 applies. The description reinforces that the ID refers to a supermarket category but adds no format, type, or sourcing details 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?

States a specific verb ("Fetch") and resource ("child subcategories") scoped to a supermarket category ID, which clearly separates it from ah_get_categories' implied top-level listing. It stops short of naming the parent-category sibling explicitly, so differentiation is inferable 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 is only implied: an agent can infer this is the drill-down step after obtaining a category ID, but the description never says when to use it versus ah_get_categories, nor that a category_id from that tool is a prerequisite. No exclusions or alternatives are given.

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?

With readOnlyHint already indicating a safe read operation, the description adds useful traits beyond annotations: receipts are always fetched live, never cached, and large sizes are fetched in 100-row windows. It stops short of explaining authentication or full return shape, but the added behavioral context is substantive.

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

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

Three short sentences, front-loaded with the core listing purpose, followed by pagination and caching behavior. There is no filler and every sentence provides useful information.

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 two fully documented parameters and no output schema, the description covers return fields, pagination, and cache behavior well. Minor gaps remain around authentication requirements and explicit sibling routing, but the core calling context is complete.

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

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

Schema description coverage is 100%, so page and size are already documented in the schema. The description adds that pagination walks the whole history and repeats the 100-row window behavior, but this is largely confirmatory rather than adding new parameter semantics 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 uses a specific verb and resource: 'List in-store cash register receipts (kassabonnen)' and names the summary fields returned. It clearly implies a listing/summary operation, but it does not explicitly differentiate itself from the sibling tool ah_get_receipt_details.

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 does not state when to use this tool versus alternatives, nor does it mention ah_get_receipt_details for full receipt details. The pagination and caching notes are behavioral details rather than usage 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?

The readOnlyHint annotation already establishes this is a safe read operation. The description adds useful context by listing what is returned (member identity, Bonus card details, connection status), which matters because there is no output schema, but it says nothing about behavior when unauthenticated, latency, or how a failing session is reported.

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 efficient sentences with the core purpose front-loaded and the return contents following. Minor redundancy in pairing 'Check authentication status' with 'verify session', but nothing wasteful.

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 zero-parameter, read-only tool, the description is largely sufficient: it explains the purpose and the return contents in lieu of an output schema. It omits the unauthenticated/failure path, which would be the main remaining thing an agent needs.

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 takes zero parameters, so per the baseline for 0-param tools this scores 4. The description cannot add parameter meaning, and none is needed.

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

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

The description states a clear verb and resource ('Check authentication status or verify session with Albert Heijn'), so an agent knows this is an auth/session check rather than a data fetch. However, it does not explicitly differentiate itself from the similarly named sibling ah_get_profile, which also surfaces member identity.

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: 'check authentication status' suggests calling it before other authenticated operations, but the description never states when to use it versus alternatives like ah_get_profile, nor any prerequisites. No explicit when/when-not guidance 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 readOnlyHint=false and destructiveHint=true, and the description's 'remove' is consistent with that. It adds the useful scoping detail that this targets the primary list rather than a favorite list, but says nothing about reversibility, error behavior for unknown IDs, or auth requirements. With annotations covering the safety profile, this is an acceptable but thin addition.

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 short sentence with the action and the identifier front-loaded and no filler. Nothing could be trimmed without losing meaning.

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

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

For a one-parameter destructive removal with annotations covering the safety profile and no output schema, the description is nearly complete. The only real gap is not indicating where item_id is obtained or what happens on failure.

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% for the single item_id parameter, so the schema already documents it. The description's 'by its item ID' merely restates the schema rather than adding format or source details, which is the expected baseline when the schema does the work.

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 (remove) and resource (item on the primary shopping list) plus the identifying key (item ID), so an agent can distinguish it from ah_add_to_shopping_list. It does not explicitly name siblings, but the 'primary shopping list' scoping is clear.

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 when-to-use guidance, no prerequisites, and no pointer to where item_id comes from (e.g., ah_get_shopping_list) or how it differs from favorite-list tools. The scope phrase 'primary shopping list' implies but does not state the boundary against favorite lists.

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

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

Annotations only supply readOnlyHint=true; the description adds real behavioral context beyond that: what the result set contains and that results are cached for up to 30 minutes (staleness expectations). It stops short of describing result-count/pagination behavior or failure modes, so not a full 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: purpose first, return payload second, caching caveat last. Every sentence carries information an agent would otherwise lack; nothing is redundant with the name or title.

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 read-only, fully schema-documented search tool with no output schema, the description covers intent, return contents and cache TTL, which is essentially everything needed to call it correctly. Minor gap: nothing about paginating through results or how many matches are typically returned.

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 all five parameters (query, page, limit, sort, bonus_only) are already documented in the schema with defaults and enum meanings. The description adds nothing parameter-specific, 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?

Names a specific verb and resource (search the Albert Heijn grocery catalog by keyword) and enumerates what comes back (prices, bonus discounts, unit prices, links). It is implicitly separable from siblings like ah_search_recipes, ah_search_stores and ah_get_product, though it never names an alternative explicitly.

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

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

The wording implies keyword search as the entry point, but there is no explicit when-to-use, no exclusions, and no routing to ah_get_products_bulk or ah_get_bonus_offers (which would be the natural alternative when bonus_only=true is desired). Usage is only inferable.

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, so safety is covered. The description adds a useful behavioral detail (results cached up to 24 hours), but it does not describe result format, pagination, or whether empty results are possible, leaving clear gaps.

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

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

Two tight sentences, front-loaded with the core search purpose, followed by a relevant caching note. Nothing is redundant or wasted.

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

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

For a simple two-parameter read-only search tool with full schema coverage and a readOnly annotation, the description is mostly sufficient. It could optionally mention that results are a list of recipes that can then be passed to ah_get_recipe_details, but nothing essential for invocation is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description reinforces the query parameter meaning by listing dish name, ingredient, or keyword, but adds no details about the limit parameter or query syntax 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 uses a specific verb (Search) and resource (official Albert Heijn Allerhande recipe collection), and names the searchable fields (dish name, ingredient, keyword). It is clearly distinguishable from ah_get_recipe_details, which retrieves a specific recipe rather than searching.

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 search context is implied clearly by the description, but there is no explicit guidance on when to use this versus ah_get_recipe_details or how to proceed after finding a recipe. It is adequate but leaves the agent to infer the workflow.

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, so the safety profile is covered; the description adds a genuinely non-obvious trait — results are cached for up to 24 hours, which tells the agent data may be stale. It does not say anything about result volume or failure modes for unresolvable queries.

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

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

Two short sentences, zero filler, with the core capability front-loaded and the caching caveat as a trailing qualifier. Nothing to cut.

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 single-parameter read-only lookup with no output schema, this covers purpose, inputs, expected result content, and the cache staleness caveat. Only the shape of the returned store list is unstated, which is minor given there is no output schema to defer to.

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?

Only one parameter with 100% schema description coverage, including its own examples ('Amsterdam', '1011NG'), so the schema already carries the semantics. The description's mention of postal code or city name duplicates that rather than extending it.

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?

Specific verb+resource: 'Search nearby Albert Heijn stores by postal code or city name', plus the three things the result answers (opening hours, distance, facilities). The word 'stores' cleanly separates it from siblings like ah_search_products and ah_search_recipes.

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 query form (postal code or city name) implies when to reach for it, but there is no explicit guidance on when not to use it and no named alternative — the store-vs-product-vs-recipe distinction is left to inference 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.