scrape_markdown

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

With no annotations provided, the description carries the behavioral disclosure burden. It explains the default rendering path, the fast/cheap tradeoff, when browser rendering is needed, and the cleanup behavior of the output. It could add more about proxy/impersonation behavior or output truncation, but the core behavioral traits are disclosed.

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 two sentences with no wasted words. The output contract is front-loaded, followed by relevant mode-selection guidance. Every sentence contributes actionable information.

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 covers the primary behavior and the key use_browser decision, but missing details about the remaining parameters, return format boundaries, and explicit alternatives leave some gaps. For a 5-parameter tool with no output schema and no annotations, the description is adequate but not complete.

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 only 20%, so the description must compensate for undocumented parameters. It adds meaning for use_browser, but does not explain proxy, max_chars, or impersonate semantics beyond what the schema already provides. This leaves the agent with minimal understanding of most parameters.

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 fetches a URL and returns clean, LLM-ready markdown with specific transformations (preserving headings, links, lists; stripping nav/footer/scripts). This distinguishes it from generic fetching tools, though it does not explicitly name or differentiate from siblings like scrape_page or smart_fetch.

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 clear guidance on when to use the default browserless path versus setting use_browser=true for JS-rendered pages, and notes the browser_launch prerequisite. It does not explicitly state when to choose this tool over sibling alternatives such as scrape_page or http_request.

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