crawl

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

With no annotations, the description must shoulder the burden of behavioral disclosure. It discloses that the operation is asynchronous, uses BFS, converts to Markdown, and returns a job id, which signals non-blocking behavior and a side effect (creating a job). However, it does not mention resource consumption, rate limits, whether it respects robots.txt, or if any setup (e.g., proxies) is required. This is adequate but not rich; a 3 is appropriate.

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 compact, two sentences, and every clause contributes. It front-loads the core action ('Start an asynchronous BFS crawl'), specifies output format (Markdown), and immediately guides the agent to the next step (poll with crawl_status). There is no fluff, repetition, or unnecessary detail—exemplary conciseness.

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 with 7 parameters and no output schema, the description provides the essential guidance: what it does, how it returns results (job id), and how to follow up (crawl_status). It does not explain preconditions like proxy configuration (though the 'country' parameter implies proxy usage) or clarify how parameters affect the crawl, but these are mostly derivable from the schema. The missing nuance about setup and parameter interactions keeps it from a 5, but it is sufficiently complete for safe invocation.

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% and every parameter already has a description (e.g., 'Max link depth (default 3)', 'Max pages (default 50)'). The tool description adds no additional meaning about any parameter; it only references the 'BFS' mechanism, which is not tied to a specific parameter. Per the baseline rule for high coverage, a 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 states a specific action ('Start'), a resource ('a site'), and a method ('BFS crawl'), plus the output ('converting each page to Markdown') and the return value ('Returns a job id'). It clearly distinguishes itself from sibling tools like 'scrape' or 'search' by emphasizing the asynchronous multi-page traversal and the need to poll with 'crawl_status'.

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 context: this is asynchronous, you get a job id, and you must poll with crawl_status. It implies the use case of crawling an entire site, but does not explicitly name alternatives or state when NOT to use this tool (e.g., for single-page scraping, use 'scrape'). The flow is clear, but exclusions are absent; a 4 reflects the lack of explicit alternative differentiation while providing solid usage direction.

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