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

Annotations declare it is a non-readOnly, non-destructive, non-idempotent mutation. The description adds valuable context beyond that: it re-connects the integration, captures httpOnly cookies page JS cannot read, and that the secret never leaves the server (returns counts only). It omits required permissions, which keeps it from 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?

Purpose is front-loaded in the first clause, then setup steps and session-type detail follow. It is a dense wall of text rather than bulleted, but nearly every sentence carries actionable content with little filler.

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 multi-step capture tool with no output schema, the description covers the prerequisite sequence, both session types, the returned value (counts only), and the secrecy guarantee. Nothing an agent needs in order to invoke it correctly appears missing.

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 100%, so the baseline is 3, but the description adds meaning: page_id must come from a prior logged-in browser_open, integration_id and base_url are alternatives that select the target, tying parameters to the workflow. This goes beyond raw schema text.

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+resource — restore an expired integration session by capturing LIVE auth from an open browser page — and distinguishes the two auth schemes (cookie storage_state vs token/header). This clearly separates it from siblings like integrations_set_auth or browser_attach_identity.

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 an explicit precondition flow: call browser_open(url, identity_name) first with a logged-in page that has called its API, then pass page_id with integration_id or base_url. It doesn't explicitly name a sibling as the alternative for the non-capture case, but the ordering and conditions are clear.

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