get_pairing_credentials

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

No annotations are provided, so the description carries full burden. It discloses the tool's side effect of auto-opening the browser, the exact return fields (deep_link, ws_url, token, userMessage), the fact that it returns paired:true if already paired, and the behavioral guarantee of a timeout if the flow is not followed. This is comprehensive transparency beyond what any annotation would typically provide.

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 about 150 words, longer than average, but every sentence earns its place given the criticality of the pairing flow. It is front-loaded with purpose, then the required sequence, then behavioral detail. Some redundancy exists (e.g., repeating the timeout guarantee) but it does not detract significantly.

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?

For a 1-param tool with no output schema, the description fully enumerates all return values (deep_link, ws_url, token, userMessage, paired:true if already paired) and positions the tool within the larger pairing workflow (as the step before wait_for_pairing). It covers the parameter, the flow, the side effects, and the fallback behavior, leaving no important gaps.

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 already documents auto_open_browser with 100% coverage, making baseline 3. The description adds practical semantics: 'By default this also auto-opens the deep link in the user's default browser; pass auto_open_browser:false to suppress that', plus concrete use cases (headless/CI/background, avoiding focus stealing). This elevates the parameter understanding beyond the schema alone.

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 explicitly states it 'Get the credentials the user needs to pair their browser with this MCP bridge' and clarifies 'calling this tool does NOT itself pair anything', clearly distinguishing it from the sibling wait_for_pairing. The verb+resource combination 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?

Provides a REQUIRED FLOW with numbered steps, explicitly says 'DO NOT skip step (2)', and explains the consequence of skipping: 'calling wait_for_pairing without first showing the credentials guarantees a timeout'. It also gives guidance for when to suppress auto-open (headless/CI/background contexts) versus when to leave it enabled.

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