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

Annotations indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it explains that calling with no args returns a login link, and calling with a token performs a session-only login. It also discloses that the token is a JWT and that the config-based method is permanent and non-expiring. This goes beyond annotations by explaining the side effects (session vs. permanent) and the authentication flow. No contradiction with 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?

The description is a single paragraph but is well-structured and front-loaded with the purpose. It contains necessary details about two usage modes and the config recommendation. It's slightly verbose but every sentence adds value. No fluff, but could be slightly more concise by separating the config advice from the tool invocation instructions.

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 tool's complexity (authentication flow with two modes), the description covers the essential aspects: how to get the token, how to use it, and the difference between permanent and session-only. There is no output schema, but the description implies the tool returns a link or confirmation. It doesn't mention error cases or what happens if the token is invalid, but for an authentication tool, this is adequate. The description is complete enough for an agent to use it 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?

The schema has one optional parameter 'token' with no description (0% coverage). The description compensates by explaining that the token is a JWT and that it can be passed as { token: "<jwt>" } for session-only login. It also clarifies that calling with no args returns the login link. This adds meaning beyond the schema, though it doesn't specify the token format beyond JWT or any constraints.

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 clearly states the tool's purpose: to authenticate the MCP server for IDE agents by logging in via browser and obtaining an access token. It distinguishes itself from siblings by focusing on authentication, while siblings like 'connect' and 'marketplace' serve different functions. The verb 'authenticate' plus the resource (access token) is specific and unambiguous.

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 provides explicit usage guidance: it explains two methods (permanent config-based token vs. session-only token), when to use each (permanent vs. session-only), and how to invoke the tool (with token argument or no args to get link). It also mentions the best practice of adding the token to the server's config. This clearly instructs the agent on when and how to use the tool, though it doesn't explicitly mention alternatives among siblings, but the context is sufficient.

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