browser_set_policy

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

With no annotations, the description carries the full behavioral burden. It does disclose what read-only mode blocks ('click/type/navigate/cookies set/etc.') while allowing reads, which is valuable. It omits policy lifetime/persistence, whether a call replaces or merges existing policy, and whether deny overrides allow — meaningful gaps for a state-changing tool.

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 short sentences, front-loaded with the primary purpose and followed by the most important behavioral detail. No filler; every clause carries 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?

For a state-changing tool with no annotations, no output schema and three optional params, the description covers the essentials (what the params mean, what readonly does) but leaves notable gaps: list precedence, policy persistence, and whether setting a policy replaces prior state. Adequate but incomplete.

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 description coverage is 0%, so the description must compensate. It clarifies that 'allow'/'deny' are URL regex lists and that 'readonly' is a boolean mode, mapping the three bare params to meaning. It does not explain precedence between allow and deny, or the effect of leaving both null.

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: 'Set URL allow/deny regex lists and/or read-only mode.' The scope of 'policy' is spelled out (two list params plus a mode flag), so an agent can see exactly what this tool mutates. It does not explicitly name its counterpart browser_get_policy, but the 'set' verb naturally contrasts with 'get'.

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?

It gives one concrete use case for readonly mode ('let the agent observe only'), which is genuinely helpful implied guidance. However, there is no guidance on when to use allow vs deny, how the two lists interact, or when to prefer this tool over browser_get_policy. Usage is implied rather than stated.

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