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

Annotations already set readOnlyHint=true, and the description adds substantial non-obvious behavior: enforced shopping boundaries, conditional return of preferredStores + preferredStoreRoutingRu, testMode-dependent store visibility, and retry logic for AGENTPAY_API_KEY with sessionId. There is no contradiction with the readOnly annotation.

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 purpose is front-loaded and every sentence carries a real constraint or trigger, so there is no filler. However, it is dense and mixes policy rules, invocation triggers, and auth retry guidance into one block, making it more of a rulebook than a tightly scoped tool description.

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 no output schema, the description covers the return shape conditionally, the exact user phrases that trigger it, demo/test-mode handling, and session auth nuances. Nothing critical appears missing for an agent to invoke it correctly in 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?

Schema coverage is 100%, so the baseline is 3. The description adds operational meaning beyond the schema: demoOnly is tied to discussing only returned demo stores and avoiding Dixy/Ozerki, and sessionId is tied to retrying without re-running begin_agent_link. This is useful but not a full redefinition of the 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?

Opens with a specific verb-resource pairing ('List stores on this agent's allowlist') and immediately distinguishes itself from peek_stores and search_products. The allowlist concept plus the explicit 'agent MUST shop only here' makes the tool's role 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?

Gives explicit call triggers («магазин», «где можно потратить», «спецмагазин», «тестовый магазин»), conditional demoOnly behavior, and a hard routing rule: for «найди» / «сравни» / «подбери» call peek_stores first, not this tool. It also clarifies testMode interactions and when to pass sessionId.

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