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

The description explains the behavior of returning a login link when called with no args and accepting a token for authentication. It doesn't detail side effects, but since there are annotations (idempotentHint=true, readOnlyHint=false), it adds useful context on persistence options that the annotations don't cover.

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 well-structured: it starts with the tool's purpose, then provides clear instructions for setup and usage. Every sentence adds value, and it's compact despite covering a complex authentication flow.

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 optional token and config setup), the description covers the key aspects: how to log in, what the token is, and how to use it for both permanent and session-only connections. The absence of an output schema is compensated by the description's thoroughness.

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 'token' as a string with no description. The description adds significant meaning: token is a JWT that the user pastes, and calling without args gives the link. It doesn't list all parameter purposes, but for a single optional parameter it provides enough guidance.

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 this is an authentication tool for IDE agents, explaining how to log in and use tokens. It distinguishes itself from siblings like 'connect' by focusing on browser-based login and token exchange.

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 explicitly explains when to use it: first-time setup vs. session-only login, and how to use the optional token parameter. It also provides clear alternatives like adding the token to the server config, making it a strong guideline example.

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