Grant or deny a site permission

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds valuable implementation context by revealing the required BiDi request shape, including the nested descriptor object and the fact that a top-level name is rejected. It does not explain persistence or whether changes are reversible, but it goes beyond the annotations.

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?

Three compact sentences, front-loaded with the purpose and the most important wire-format warning. The callout to the underlying BiDi command and the practical use case follow efficiently with no wasted wording.

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 simple three-parameter mutation tool with no output schema, the description covers what it does, exactly how to format the request, and why an automation agent would use it. A brief note on persistence or how to restore a permission would make it fully complete.

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 schema already defines all three parameters. The description adds critical payload semantics that the schema does not convey: the permission name must be wrapped in a descriptor object, while state and origin sit at the top level. It also clarifies that state controls granted, denied, or prompt behavior.

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 action and resource: 'Set one permission for an origin', and names the underlying BiDi command. It is cleanly distinguishable from the read-only sibling browser_list_permissions.

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?

Explains the practical automation context: stopping a page from blocking on location or notification requests. It does not explicitly name alternatives or say when not to use this tool, but the intended use case is clear.

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