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

Annotations include readOnlyHint=false (no read-only), openWorldHint=true, idempotentHint=true, destructiveHint=false, but do not cover the rendering process or cost. The description discloses that it uses headless Chrome, drops navigation/sidebars/cookie banners, and that results are compact. It also notes a surcharge for residential exits. However, it does not detail the exact behavior of async mode or token collection, though that is partially covered by the sync parameter schema. With decent annotation coverage, a 4 is justified.

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 concise and front-loaded with the main purpose and usage. The behavioral context (headless Chrome, content filtering) is early, and the cost/alternative comparison is efficient. It is not overly long, and each sentence adds value. A minor deduction for not mentioning the async token flow in the description, but it is covered by the sync parameter, so overall strong.

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 has 9 parameters, 2 required, and an output schema is absent, the description covers the essential use case and behavior. It explains key parameters like sync and max_age effectively through the schema and description combined. However, it does not explain the return format or token collection process fully, relying on the get_result sibling. Considering the complexity and that annotations carry some info, a 4 is appropriate, not a 5 because the async workflow could be clearer.

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 100%, so the schema already documents all parameters thoroughly, including details like max_age format and idempotency_key behavior. The description does not need to re-explain parameters. It adds a note that 'removed ads and banners are gone from html, markdown and summaries too' for page_options, which is a useful extra beyond the schema. However, this is minor, so a 3 baseline is appropriate given high schema coverage.

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 makes a POST to /markdown, renders the page in headless Chrome, and converts main content to clean Markdown with specific elements kept and others dropped. This is a specific verb+resource with detail that distinguishes it from fetch_html and scrape_url, both siblings with different purposes.

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 explicitly says 'Start here when you want to READ a page' and contrasts with fetch_html, noting that fetch_html returns the whole DOM which is larger and says nothing extra about meaning. It also highlights cost (1 credit) as a differentiator. This provides strong guidance on when to use and when not to use.

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