get_semantic_surface

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

With no annotations provided, the description fully discloses behavioral traits: it queries the AX tree, resolves shadow roots, computes accessible names, pierces iframes, and runs serialization on a worker thread to avoid blocking. The options, like semanticOnly, are explained in terms of their pruning effect, ensuring the agent understands the tool's behavior and performance implications.

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?

The description is well-structured with clear sections (capitalized headings) and front-loaded with the key purpose. However, it is somewhat verbose, containing multiple paragraphs. While every sentence adds value, a more concise version could remove some redundancy (e.g., the workflow repeats the tool names). Still, it earns a 4 for clarity and logical organization.

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?

Given the tool's complexity (perception via accessibility tree) and the absence of an output schema, the description adequately covers the input parameters, output format (Markdown with stable IDs, JSON structure), and workflow integration. It could be improved by explicitly listing the Markdown format details, but overall it provides sufficient context for an agent to use the tool 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?

Both parameters have 100% schema description coverage. The description adds significant value beyond the schema: for `semanticOnly`, it explains its purpose ('aggressively prunes non-interactive structural nodes') and use case ('large pages where you only need interactive elements'). For `format`, it details the JSON output structure (stableId, backendNodeId, role, name, value, childIds) and clarifies that it is the source of truth for the Markdown view.

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?

The description clearly states the tool's purpose: it queries the browser's Accessibility Object Model via CDP and returns a hierarchical Markdown document (USAG). It emphasizes that it is 'THE PRIMARY PERCEPTION TOOL' and distinguishes itself from sibling tools by outlining a workflow where this tool is used first, followed by atomic_interact and get_state_delta.

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?

The description includes a 'WHY THIS EXISTS' section explaining the rationale and a 'WORKFLOW' section that tells the agent when to use this tool (first step in perceiving a page) and how to use its output (backendNodeIds with atomic_interact). It implicitly warns against using raw HTML by stating it has 90% semantic noise, but does not explicitly exclude other tools or mention specific when-not scenarios.

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