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

The description discloses key behaviors beyond annotations: no-arg calls return the login link, token calls perform a session-only login, and config-header auth creates a permanent, non-expiring connection. This adds meaningful context about side effects and session duration, with no contradiction to the 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?

Three tightly packed sentences, organized with 'Best:' and 'Or,' and all content earns its place. It is front-loaded with context and immediately gives actionable invocation details without unnecessary prose.

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 simple single-optional-parameter interface and no output schema, the description is complete enough for an agent to correctly invoke the tool: no args returns the link, token arg authenticates, and the config route is explained as an alternative. It covers invocation modes, session semantics, and permanence.

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?

With one optional parameter and 0% schema description coverage, the description fully compensates by explaining that 'token' is a pasted JWT, that it is optional, and that omitting it retrieves the login link. This is exactly the semantic guidance an agent needs beyond the bare string schema.

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 identifies the tool as an authentication flow for MCP.AI/IDE agents, with specific actions: browser login, token copy, and session/permanent token configuration. The verb+resource is clear, but it does not explicitly distinguish itself from sibling tools like 'connect'.

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?

Explicit guidance is provided: use the server config header for a permanent connection, or call with a pasted token for a session-only login, or call with no arguments to receive the login link. It also clearly distinguishes between the two invocation modes and the preferred config approach.

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