Get the interactive structure of a page

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

With no annotations provided, the description carries the full burden, and it delivers: it discloses the cost ('Costs 2 credits'), the access requirement ('Requires Pro or above'), and the nature of the response (semantic snapshot with selectors). These are non-obvious operational traits an agent needs before invoking. It does not describe failure modes or async behavior for the default path, but the most decision-relevant behaviors are surfaced.

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?

Four short sentences, each earning its place: cost, output contents, usage positioning, and access tier. There is zero filler and the most operationally important facts (cost and output) are front-loaded before the usage guidance. This is a model of concise, information-dense tool documentation.

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 5-parameter tool with no output schema and no annotations, the description covers the essentials: pricing, authorization tier, output shape, and when to use it in the workflow. The main gaps are the undocumented maxNodes parameter and the absence of a precise output contract (no output schema means 'accessibility tree, interactive elements, selectors' is all an agent gets). These are minor against the solid core, so 4 is appropriate.

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 80% (url, delay, detail, and waitForSelector are documented), so the schema carries most of the parameter load and the baseline of 3 applies. The description adds nothing about parameters, and maxNodes remains undocumented in both the schema and description – a real gap. The description's output details hint at what selectors are returned, but that does not compensate for the missing parameter semantics.

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 states a specific action and resource: 'Returns a semantic snapshot: the accessibility tree, the interactive elements, and a selector for each.' This concretely distinguishes it from siblings like domscout_extract_markdown (content) and domscout_capture_screenshot (visual), while the reference to domscout_automate_page clarifies its role in the workflow. The title and description together give an agent an exact picture of what the tool produces.

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 gives explicit usage context: 'Use this before domscout_automate_page to find out what is on the page and what to target.' This names the companion tool and the timing precisely. It stops short of a 5 because it does not state when NOT to use it or mention alternatives like domscout_extract_data, but the primary orchestration flow is clear.

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