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

Annotations already cover safety (readOnly, openWorld, non-idempotent, non-destructive), and the description adds real behavioral context beyond them: crawl caps at 10 pages by default and 100 maximum, and each successfully extracted uncached page consumes one credit — a cost disclosure an agent needs before choosing crawl. It also explains how compact mode filters output and when that filtering is skipped, though it never states response size or latency characteristics.

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?

Front-loaded with purpose, then options, then response shaping, then four runnable examples — good ordering for a tool with this many hidden switches. The compact-filtering paragraph is dense and requires re-reading, but nearly every sentence conveys a distinct behavior rather than restating the schema.

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 tool whose real parameters are hidden inside an open object, the description supplies the semantics the schema cannot express, and the examples resolve the otherwise confusing split between top-level mode and params.mode. Since an output schema exists, the return-value detail is partly duplicative, but it remains useful given the two-tier filtering model.

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 0% and the params object is an untyped open bag, so the description carries the entire burden — and it does: url required, params.mode enum values with default, params.output values, max_pages default and ceiling, and the interaction where output overrides the response-mode default. It falls short by naming include_markdown and json_restrictor without explaining their accepted values or effects.

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?

Opens with a specific verb and three named operations — extract content from a URL, discover site URLs, crawl pages — which maps directly to the scrape/map/crawl modes. This is unmistakably distinct from the search-family siblings, so an agent can route without opening a schema.

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?

Gives explicit selection logic for the two axes that matter: which mode (scrape default / map / crawl) and which response mode (complete default / compact), plus a decisive rule — 'Use complete with output="json" for full JSON.' It also states url is required. What's missing is any when-not guidance or an explicit contrast with the search siblings.

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