Bestshopping Cashback — IT, DE, FR

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new behavioral context by stating the data is public-only (no account access) and that rates are not a personalized quote. It does not describe pagination or rate limits, but for a read-only lookup that is a minor omission.

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 redundancy: the scope of returned data leads, and the caveats about rates and account access follow. Every clause carries information the agent would not otherwise have.

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

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

With an output schema present, return-value details need no explanation, and the annotations cover the safety profile; the description fills the remaining gaps (public-only data, no personalized quote). Only the explicit search_merchants → get_merchant sequencing is missing, a small residual 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 schema itself carries strong warnings ('never guess or reuse IDs from another market', market default 'it'), so the description need not repeat them. The description adds no parameter-level meaning beyond the schema, which is the baseline 3 case.

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 ('Read') and resource ('merchant information'), and enumerates the payload (cashback conditions, browser tracking rules), which lets an agent distinguish it from search_merchants and prepare_cashback_link. It stops short of explicitly labeling it as the detail-lookup step after a search, so sibling differentiation is implied 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?

It sets clear boundaries: exact rates must be read off the returned page, and the tool gives neither a personalized quote nor account access — useful when-not signals against expect-a-quote or account-scoped siblings. However it never explicitly says 'call this after search_merchants to expand a merchant_id', leaving the workflow linkage to the schema description.

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?

Consistent with readOnlyHint/idempotentHint, it reinforces that nothing is activated and no purchase click or cookie is set, then adds behavior the annotations cannot express: never open or prefetch the link server-side. It also prescribes the agent's follow-up messaging (show the link, tell the user to click, allow cookies, disable AdBlock, never claim cashback is already active).

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?

Purpose is front-loaded in the first sentence, followed by a negative-scope sentence and two imperative usage sentences. Every sentence carries distinct operational content, though the compliance list is dense enough that a slightly tighter grouping would read better.

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

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

An output schema exists so return-value documentation is not required, yet the description still explains what the returned link is for. Combined with full parameter coverage and redundant safety framing, an agent has everything needed to call it and handle the result correctly.

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

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

Schema description coverage is 100%, so market, nickname, and merchant_id are already fully documented with constraints and provenance. The description only restates that the nickname must pre-exist and the merchant be verified, adding marginal meaning beyond the schema baseline of 3.

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 first sentence names a specific verb ("Prepare") and resource ("personal Bestshopping go.html link") and scopes the inputs (existing recipient nickname, verified cashback merchant). It is clearly distinct from the read-only lookup siblings get_merchant and search_merchants, though it never names them directly.

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 preconditions (nickname must already exist, merchant must be verified) and heavily delimits what the tool does not do, which implicitly routes agents that want to browse merchants to search_merchants. It stops short of an explicit "use this instead of X when Y" 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 readOnly, idempotent, closed-world and non-destructive, so safety is covered. The description adds genuine behavioral context beyond them: no tracking activation and no merchant visits are side-effect disclosures an agent would otherwise have to guess.

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, no filler, with the core action and scope front-loaded and the negative side-effect constraint placed last as a clarifier.

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

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

An output schema exists, so return-value explanation is unnecessary, and the market parameter carries rich in-schema guidance. The only real omission is pagination behavior for limit/offset, which leaves a small gap for a search tool.

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

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

Schema coverage is 50%: query and market are well documented in the schema, and the description reinforces them ('by name, domain or ID', 'selected account market'). The limit and offset pagination parameters are documented nowhere, and the description does not compensate for that 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 gives a precise verb+resource ('Search the current Bestshopping merchant catalog') plus the searchable keys (name, domain, ID) and entity subtypes (online cashback, gift cards, top-ups). The closing clause functionally separates it from prepare_cashback_link, though it does not name siblings explicitly.

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

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

It establishes the operating context ('selected account market') and a clear negative condition ('does not activate tracking or visit merchants'), which steers agents away from the link-preparation flow. It stops short of naming the alternative tool or stating prerequisites explicitly.

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