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

Beyond the annotations (destructiveHint=false, idempotentHint=true), the description adds useful behavioral facts: the stored corpus and crawl history are left untouched, and terminal-state jobs are unaffected. This reassures the agent about side effects, though it doesn't cover the return value or confirming state after cancellation.

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?

Three short sentences, front-loaded with the core action, each contributing a distinct fact (action, preserved data, terminal-state no-op). No waste.

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 simple one-parameter cancel operation with annotations covering the safety profile and no output schema to explain, the description is nearly complete. Missing only post-cancellation state/return detail, which is minor.

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 the single job_id is fully documented there (including its origin from crawl_site). The description's 'by job ID' adds nothing beyond the schema, 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?

States a specific verb ('Cancel') and resource ('crawl job') plus the qualifying scope ('running or pending'). An agent can immediately distinguish it from siblings like get_job_status or crawl_site.

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?

Clearly states the applicable states (running or pending) and explicitly rules out terminal-state jobs, which is real when-to-use guidance. It does not name an alternative tool, so it falls short of a 5.

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

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

Goes well beyond the annotations: it discloses that execution is asynchronous (returns a job ID immediately), that writes go to a staging area and replace the corpus atomically, and that cancelled/failed crawls leave the prior corpus intact. That last point meaningfully explains why destructiveHint=false despite this being a mutating crawl.

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?

Three tight sentences, zero filler. The core action is front-loaded, and the async return and atomicity guarantee follow in logical order.

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?

With no output schema, the description compensates by stating the return value (job ID) and explains the lifecycle/failure semantics. An agent has everything needed to invoke this correctly and understand the consequences.

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%, so site_key and incremental are already documented in the schema. The description adds no extra semantics about these parameters, which is the expected baseline when the schema carries the full burden.

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?

States a specific verb and resource ('Start a background crawl for a configured site') and adds the async contract ('Returns immediately with a job ID'). This cleanly separates it from siblings like get_job_status and cancel_crawl without needing to name them.

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 'background crawl' framing implies this is the kicking-off action, but there is no explicit when-to-use guidance or mention of alternatives such as diff_crawl or list_sites. Usage is inferable from the verb rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context by noting 'hash-based verdicts from the SQLite history index' and precisely defining the baseline selection rule, which goes beyond the structured 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?

Three sentences, with the core behavior first and the workflow example last. Each sentence carries distinct information (what, how, when) with no filler or repetition.

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?

Given there is no output schema, the description gives a sufficient high-level contract: added/removed/changed pages with hash-based verdicts. It also reduces ambiguity by naming the exact sequence with crawl_site and get_freshness, so an agent can correctly select and chain the tool; minor gaps like response entry shape remain but are not essential for 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 covers 100% of parameters, so the baseline is 3. The description adds cross-tool value by explaining where `since` comes from ('pass the last_crawl_ended_at value as since'), which is not present in the input schema; the other parameters are already well documented in the schema.

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?

States a clear action and resource: 'Return added/removed/changed pages between the latest crawl and the most recent crawl whose crawl_ended_at <= since.' This is specific enough to distinguish it from sibling tools like get_freshness, and the title 'Diff crawls over time' reinforces the same function.

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?

Provides a concrete workflow: 'Pair with get_freshness: pass the last_crawl_ended_at value as since after running crawl_site with incremental set to true.' This tells an agent when to call it and how to chain it with siblings, though it does not explicitly state exclusions or when-not-to-use alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description goes further by disclosing what the tool returns (crawl summary fields, output/state dir presence, running job), which is useful behavioral detail beyond the structured annotations. It accurately describes a read-only inspection operation without contradicting any 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?

Two dense sentences: the first lists the return content, the second gives the decision context. No filler and the key return information is front-loaded. The description achieves high information density in a compact format.

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 single-parameter read-only tool with no output schema, this description is complete. It states what is returned, how to decide to use the tool, and the annotations cover idempotence and safety. The provided information fully supports correct 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?

The input schema documents site_key at 100% coverage, including the hint to use list_sites to discover available keys. The description adds no parameter-level details, but with full schema coverage the baseline score of 3 is appropriate. No extra semantics are needed beyond what the schema already provides.

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 opens with a specific verb and resource ('Return the most recent crawl summary for a site') and enumerates the returned fields, making the operation unmistakable. It also injects a decision cue ('Use this to decide whether to query the existing crawl or run crawl_site first') that distinguishes it from the crawl_site sibling. This is a clear, specific purpose statement that differentiates it from other tools.

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?

It explicitly states when to use the tool: before deciding between querying an existing crawl and running crawl_site. This names the alternative and the condition, satisfying the usage guidance dimension. The tool's role as a freshness check is directly tied to a decision, giving clear context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds no behavioral context beyond the word 'Get', such as what status values may appear or whether the call reflects updated progress. No contradiction exists.

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, focused sentence with no filler. The verb and object are front-loaded, making it immediately scannable for an agent.

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 one-parameter, read-only status lookup with strong annotations, the definition is mostly sufficient. However, with no output schema, it does not indicate what statuses or fields the response contains, and the absence of usage guidance leaves minor but real ambiguity.

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 the single job_id parameter is adequately documented as the ID returned by crawl_site. The description itself adds no parameter-level meaning beyond what the schema already provides.

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 uses a specific verb ('Get') and resource ('status of a crawl job'), making the tool's purpose clear. It is naturally distinct from siblings like crawl_site or cancel_crawl, though it does not explicitly name or contrast 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?

Usage is only implied: checking the status of a crawl job makes sense after calling crawl_site, and the schema's job_id description references crawl_site as the source of the ID. However, the description itself gives no explicit when-to-use or when-not-to-use guidance.

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

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

The annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral detail beyond these: live network access, markdown output, independence from crawl output, and intentional disregard for site-configured content_selector/scope. There is no contradiction with 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?

Two sentences, front-loaded with action and output, then a compact contrast that disambiguates from crawl-based tools. Every sentence earns its place with no filler.

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 two-parameter read-only tool with rich annotations, 100% schema coverage, and no output schema, the description is sufficient. It explains what, when, and one key quirk, leaving no ambiguity about 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?

The input schema covers 100% of the parameters, including the content_selector default of 'body'. The description adds no meaningful parameter-level detail; its mention of content_selector refers to site configuration rather than the argument itself. Baseline 3 is appropriate because the schema carries the parameter documentation.

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 verb and resource: 'Fetch a URL live over the network and return its content as markdown.' It also distinguishes itself from siblings by explicitly noting it does not read stored crawl output, which clearly separates it from read_page and other crawl-related tools.

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?

It provides a clear context: use this for an on-demand, live fetch independent of any crawl, as opposed to reading stored crawl output. It doesn't name an explicit alternative such as read_page, but the contrast with crawl-based reads gives an agent enough guidance to choose correctly.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context: it returns metadata only (URL, title, depth, crawled_at, content_length), is paginated and sorted by URL, and reflects stored crawled pages rather than live fetches. It doesn't discuss errors or partial failures, so it is strong but not exhaustive.

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?

Three focused sentences front-load the core action, state output scope and shape, and route to sibling tools. Every sentence earns its place with no wasted words.

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 read-only listing tool with fully documented parameters and safety annotations, the description covers action, scope, output fields, pagination ordering, and downstream tool usage. The schema supplies the remaining parameter details, so nothing essential is missing.

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%, so the baseline applies. The description's mention of pagination and 'for a site' mildly reinforces site_key, offset, and max_results, but it does not add parameter meaning beyond what the schema already documents.

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?

Description uses a specific verb 'List' with a clear resource 'crawled pages for a site' and adds pagination and sort order. It also distinguishes itself from read_page and get_page by explicitly stating that it returns metadata only and that the pages are crawled, not live.

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 explicitly routes downstream usage: URLs returned here should be passed to read_page for stored markdown, while get_page is for live re-fetching rather than crawled copies. This gives an agent clear when-to-use and when-not-to-use guidance for the relevant siblings.

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

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

Beyond the readOnly/idempotent annotations, the description reveals important behavior: no network access, content_selector already applied, truncation at max_bytes, and a next_offset mechanism for reading the rest. These are not derivable from the annotations or schema alone.

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?

Four sentences, each earning its place: core function, sibling distinction, discovery workflow, and pagination behavior. The most important information is front-loaded, and there is no filler or repetition.

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 without an output schema, the description adequately covers return format, truncation, and continuation via next_offset. It also provides the surrounding workflow with list_pages and clarifies the live-crawl tradeoff, leaving no critical gap for an agent to call it 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%, and the schema already explains each parameter's meaning. The description's mention of max_bytes truncation and next_offset adds behavioral context, but it does not add new semantic detail about the parameters themselves.

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 opens with a specific verb and resource: 'Return a page's markdown from the stored crawl output, without any network access.' It explicitly contrasts itself with get_page, making the tool's role unambiguous and differentiating it from the most similar sibling.

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?

It gives clear workflow guidance: 'Use list_pages to discover URLs, then read_page to read them.' It also explains the exact tradeoff versus get_page (crawled copy vs live re-fetch), so an agent knows when to select this tool over the alternative.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description reveals important behavioral traits: zero network access, BM25 ranking with stemming, result format including URL and section path, FTS5 syntax support, and the stored-index-only scope. This adds substantial context about what happens when calling the tool and what the output contains, with no contradiction to 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?

Four dense sentences, each earning its place: purpose and ranking, result format and follow-up, query syntax, and index caveat. The most important scoping constraints are front-loaded, and there is no fluff or repetition of schema content.

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?

Given there is no output schema, the description properly explains what results contain (URL, heading path, snippet with highlighted matches) and how to get the full content. It also covers prerequisites (crawl_site), querying syntax, and scope limitations. The agent has enough context to invoke the tool correctly without missing behavioral details.

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?

The schema already describes all three parameters at 100% coverage, including the query syntax, limit bounds, and site_key usage. The description reiterates the FTS5 syntax but does not meaningfully extend parameter-level understanding beyond the schema. Baseline 3 is appropriate because the schema carries the parameter-heavy lifting.

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 opens with a specific verb and resource: 'Full-text search across all crawled documentation'. It further distinguishes the tool from siblings by stating it is ranked by relevance, works offline, and searches only the stored index, which clearly differentiates it from list_pages, get_page, and read_page.

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 for when to use the tool: when you need to search crawled documentation. It also provides practical guidance by telling the agent to run crawl_site first for uncrawled sites and to follow up with read_page for the full page. However, it does not explicitly mention when not to use this tool in favor of a sibling like list_pages or get_page, so it falls just short of a 5.

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