Extract structured data from a URL

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

The description provides rich behavioral context beyond the annotations: it details the exact return shape (`json` and `markdown` views), notes that Twitter cards are surfaced inside the `opengraph` list, and warns that pages without schema.org metadata will yield empty lists. This is far more than the read-only/idempotent hints already convey.

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 section headers, bullet lists, and a compact Args section. Every sentence earns its place — the length is justified by the need to convey use cases, return formats, and common pitfalls without redundancy.

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?

Despite the moderate complexity, the description covers purpose, usage guidelines, return formats, behavior on empty results, and parameter semantics. It also cross-references sibling tools appropriately. With an output schema present, the description doesn't need to repeat return type details, but it still explains the two output formats clearly.

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 0%, but the description fully compensates: it specifies that `url` must be an absolute http(s) URL, and explains `format` options (markdown default vs json) with context from the Returns section. This adds meaning that the raw schema (type + enum) does not provide.

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 starts with 'Pull JSON-LD, OpenGraph, Twitter cards, and microdata from a web page' — a specific verb and resource that clearly states what the tool does. It also explicitly contrasts with sibling tools, noting when to use `fetch` or `read_doc` instead, which fully distinguishes it from alternatives.

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 'Best for' and 'Not recommended for' sections give explicit use cases with concrete page types and explicit fallback alternatives. The 'Common mistakes' section further clarifies when not to use the tool, providing strong usage guidance beyond mere capability.

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