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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false; the description goes well beyond that by disclosing the OAuth prompt behavior, the client-compatibility caveat, the global change in what every other tool returns, the fact that the call itself is free, and what comes back (plan and usage). No behavior contradicts the read-only, non-destructive annotations.

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?

Front-loads the action and its payoff, then the fallbacks, so an agent gets the decision-relevant facts first. It is a long single paragraph with nested parentheticals (the x402 URLs and USDC detail) that could be trimmed or split, but every clause carries information an agent needs to route correctly.

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 still covers what the tool returns (plan and usage), what it changes downstream (full pages, credits), and what to do instead when it is not usable. Nothing an agent needs in order to call it or route away from 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, so there is no parameter meaning to add; the baseline for an empty schema applies. The description's mention of the OAuth prompt correctly signals that input is collected interactively rather than through arguments.

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 action (connect the user's gankdat account) plus the exact mechanism (OAuth sign-in prompt in clients that support it, such as Claude) and the concrete effect on all other tools (full pages and account credits instead of the preview). That effect clause is what separates it from siblings like request_api_key and buy_credits, which offer other routes to the same data.

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 when-to-use (sign in to get full pages and use plan credits), explicit when-not ('No person to sign in?'), and names the alternatives with their conditions: request_api_key with the user's email for a free key, or accountless per-call payment via the x402 endpoints. Nothing is left to inference.

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