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

Annotations only indicate non-read-only and non-destructive, so the description adds useful behavioral context: browser-grant handling, optional retry with sessionId, testMode messaging, and a 'do not spend until granted' guard. It does not sharply state what persistent state verify_connection changes, but it is not contradictory and adds meaningful constraints.

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 most important trigger is front-loaded, but the rest is a dense run-on list of directives with mixed-language scraps like 'Разрешить', 'ap_', and 'recovery.openUrl', plus several prohibitions in one paragraph. It is information-rich but not well structured or concise.

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

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

Given the lack of an output schema, the description covers the main branches: when to call, what to do without credentials, browser-grant handling, retry with sessionId, and testMode follow-up. It is slightly incomplete because NEED_BROWSER_GRANT and recovery.openUrl are not defined, but an agent with context from sibling tools can act.

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 already explains code and sessionId, so the baseline is 3. The description earns an extra point by adding operational parameter conditions: pairing code is optional, and sessionId should be passed when AGENTPAY_API_KEY is required and a sessionId already exists in the chat.

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 opens with a specific action ('Finish AgentPay connect') and names precise triggers: after poll_agent_link returned apiKey, or when the user says «проверь MCP». It also distinguishes the tool from siblings by explicitly directing the agent to call begin_agent_link first when no ap_ exists and never to call begin_agent_link again.

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 gives explicit when-to-use conditions, names the alternative tool for the no-credentials case, and lists clear never-actions such as do not invent a code, do not ask the owner to edit connector settings, and do not reconnect. This removes ambiguity about routing among the agent-link tools.

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