open_url

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

With no annotations, the description carries the full burden and does well: it discloses the screen-takeover side effect, states that nothing is sent or called by opening a link, gives the return value ('Opened'), and tells the agent to call read_screen to observe the result. It doesn't cover failure modes (no handler installed, bad URL), which is the only meaningful gap.

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?

Front-loaded with the action and its core semantics, then alternatives, then the side-effect caveat, then the follow-up. It's a single dense paragraph with heavy parentheticals (the consumer-app examples), which costs a little readability but every sentence carries distinct information.

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?

A one-parameter, no-output-schema tool whose description still covers the action semantics, the scheme routing matrix, the side-effect profile, the return value, and the follow-up call. Nothing an agent needs in order to invoke it correctly is 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 real meaning beyond the schema's single 'tel:' example by enumerating handler families — https, mailto, tel, geo/maps, market:// — so the agent knows which schemes are legitimately routable rather than only the accepted type.

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 and resource ('Open a link on the phone') and immediately defines the exact semantics — behaving as a tap would, with https links routed to the browser/handler app and deep-link schemes routed to their apps. It explicitly contrasts itself with the browser_* family, so an agent can distinguish it from browser_open without opening either 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 an explicit when-not rule: 'For public web pages you only need to read, the browser_* tools work without taking over the screen.' That names the alternative and the condition that selects it, which is exactly the routing decision an agent needs.

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