Pagemd

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

Annotations are absent, so the description carries the full burden. It discloses key behaviors: JavaScript is never run, pages without server HTML are refused, and Markdown is truncated at 60,000 characters with a 'truncated flag'. It also states that certain page elements are removed and metadata is extracted. These are significant operational behaviors beyond the schema. The only minor gap is not specifying error handling for non-HTML content (e.g., PDFs) or rate limits, but the description is notably transparent for a tool with no annotations.

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 a single, well-structured paragraph that front-loads the core action ('Read a public web page as clean Markdown for an LLM') and then lists the specific behaviors and returned data. Every sentence adds valuable information: content extraction rules, URL handling, metadata list, truncation limit, and JavaScript policy. There is no fluff, and the structure is logical (purpose → output specifics → constraints). This is a model of conciseness with high information density.

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?

The description is remarkably complete for a tool with a single parameter and no output schema. It covers input requirements (public URL, HTML), processing behavior (no JS, content cleaning), output format (Markdown with specific elements), additional metadata fields, size limit, and refusal condition. An agent would know exactly what to expect and how to handle the result. There's no ambiguity about what the tool does or its constraints. The only minor omission is explicit error codes, but the refusal behavior is described, and the description fully satisfies the context needed to call 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?

Schema description coverage is 100% for the single parameter 'url', which is described as 'any public http or https address serving HTML'. The description adds a bit of context: it specifies that the page must be 'public' and 'serving HTML', and that JavaScript is not executed (so the URL must lead to server-rendered HTML). However, the schema already conveys the format and constraints. The description doesn't add significant new meaning beyond what the schema provides, so baseline 3 is appropriate.

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 reads a public web page and converts it to clean Markdown for an LLM, specifying what is removed (navigation, footers, sidebars, cookie banners, forms, comments) and what is preserved (headings, lists, tables, code blocks, links/images as absolute URLs). It also lists additional returned metadata (title, canonical URL, language, byline, date, description, JSON-LD, word count) and constraints (60,000 character cap, no JavaScript). This is highly specific and distinguishes it from any possible sibling (none listed, but the description is self-contained).

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 implies usage: it's for reading public HTML pages, and it explicitly notes that client-rendered pages with no server HTML content are refused and not charged, which serves as a usage caveat. However, it doesn't explicitly state when to prefer this tool over alternatives, but with no sibling tools listed, there's no direct alternative to differentiate. The clear scope (public pages, HTML only, no JS) provides good guidance, but a mention of when not to use it (e.g., for private pages or PDFs) is implicit rather than explicit.

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