browser_discover

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

With no annotations, the description carries the full burden. It does disclose a valuable non-obvious side effect — that kind=tabs writes this connection's latest observation for later claim_tab use — and lists return fields, but it omits whether the listing is scoped per connection, pagination/limits, and failure behavior when no browser is connected.

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?

Two sentences, front-loaded with the core listing behavior, with the claim_tab side effect placed second. Slight compression cost in the 'profiles/capabilities' phrase, but no wasted text.

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 2-parameter discovery tool with no output schema and no annotations, the description covers the essentials (what is listed, what fields come back, the claim_tab linkage) but leaves connection scoping, listing limits, and the mandatory browser_id for kind=tabs unstated — details an agent would need to invoke it correctly.

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 only 50%: browser_id is documented in-schema, but kind's enum has no schema description. The description partially compensates by mapping 'profiles/capabilities' to browsers and 'tabs' to tabs, but it does not state that browser_id becomes mandatory for kind=tabs or what browser_id values look like.

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 clear verb (List) and two distinct resources (connected profiles/capabilities or tabs), plus the key fields returned (URL/title, control status). It also relates itself to browser_claim_tab, giving partial sibling differentiation, though it never contrasts itself with other read siblings like browser_snapshot or browser_logs.

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?

Usage is only implied: the mention that tab discovery records the latest observation 'for claim_tab' hints at a discover-then-claim workflow, but the description never says when to choose this over alternatives or what preconditions apply (e.g. must a browser already be connected).

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