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

Beyond the annotations, the description explains that a no-arg call returns a login link, that pasting a token gives a session-only login, and that config-header tokens provide a permanent non-expiring connection. This is useful behavioral context beyond the schema and annotations, though it does not describe the exact response payload or error cases.

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 information-dense and every sentence contributes to understanding how to use the tool. It is slightly unstructured, opening with 'MCP.AI for IDE agents (Cursor, etc.)' rather than a clean purpose statement, but it remains reasonably concise for the range of behaviors it describes.

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 low complexity, one optional parameter, and no output schema, the description is largely sufficient. It covers the main flows: getting a link, passing a token for session login, and the recommended permanent header configuration. It could be more explicit about what happens after a successful token call, but overall it provides enough context for an agent to invoke 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 only defines an optional 'token' string with 0% description coverage, so the description carries the full burden. It clarifies that the token is a JWT, how it should be passed, and that omitting it triggers the login-link flow. This adds meaningful semantics to the single parameter.

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 conveys that this tool handles authentication for the MCP server: the agent should direct the user to log in via browser and copy an access token, then call this tool with that token. It distinguishes from siblings by focusing specifically on the auth flow, though it never explicitly says 'authenticate this server'.

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 gives concrete usage modes: no args to obtain a login link, or pass { token: '<jwt>' } after the user pastes the token. It also recommends the preferred permanent setup via config header versus the session-only paste route. It does not explicitly discuss when not to use this tool, but it provides clear actionable guidance.

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