auth_begin

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

Annotations declare openWorldHint=true and non-readonly, and the description adds real context beyond them: the flow opens a browser as a side effect, the URL and code must be surfaced to the user, and polling must wait an interval. It stops short of covering code expiry/re-invocation or what state is established on success, keeping it below a 5.

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 short sentences, each doing distinct work: identity, parameter guidance, and the required next action. Nothing is repeated from the schema or annotations.

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 output schema, the description correctly states what the caller receives (a URL and code) and what to do with it. Minor gap: it does not say whether credentials persist after a successful poll, which matters for an auth entry point.

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?

Schema coverage is 0% for the single parameter, but the description compensates fully: it states the default (browser opens) and the exact condition to flip it (headless host). Only the parameter name itself is left implicit, which is inferable from context.

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 verb (Start) and resource (browser device-code sign-in), and anchors it to a known reference point ('same ... as the VS Code extension'). It also names the required follow-up sibling auth_poll, so an agent can place the tool in the auth flow without opening the schema.

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 concrete when-to guidance for the parameter ('Opens a browser by default; disable on a headless host') and prescribes the next step ('call auth_poll after the indicated interval'). It does not explicitly contrast with auth_status or auth_logout, but the sequence for this tool is unambiguous.

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