Best way to pay at a store

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

With no annotations, the description carries the full burden and does well: it discloses that it makes a single live request to connected benefit sources, that results are ranked with the user's own providers first, and that it is read-only in effect ('Never buys anything'). It omits auth/permission requirements and any freshness or rate-limit caveats, keeping it out of 5 territory.

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 sentences, each earning its place: trigger first, then behavior/return shape, then the agent-facing obligations (show links, attribute sources, tell the user to confirm at checkout). Front-loaded and free of 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?

There is no output schema, so the description must describe returns — and it does: ranked options, how to use each, and a link, plus attribution expectations. Missing only edge-case handling (unknown store, no matching offers) and the effect of the optional amount/channel/country parameters.

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 baseline is 3. The description adds only one genuine semantic beyond the schema — that the store name may be supplied in Hebrew or English — which is helpful but marginal against four well-documented parameters.

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 precise verb+resource: it returns ranked payment options (card, club, cashback portal, discounted gift card) for a given store. The subject matter is clearly distinct from the wallet and source-listing siblings, and an agent can tell what a call produces before 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?

Gives an explicit trigger condition — the user is in or heading to a store and asks which payment method to use. It also implies a boundary with 'Never buys anything'. However, it never names an alternative (e.g. wallet_get) or states when NOT to call it, so the routing guidance 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.