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

Annotations already declare non-read-only, non-destructive, idempotent behavior. The description adds valuable specifics: stored corpus and crawl history are untouched, and terminal-state jobs are unaffected. It does not cover auth or rate limits, but those are not critical here.

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 and immediately followed by the key side-effect and state constraints. 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?

With a complete input schema, rich annotations, and an output schema, the description covers purpose, side effects, and state limitations. It could add a note about checking job status before cancelling, but otherwise is sufficient for a simple cancel operation.

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 single job_id parameter has 100% schema coverage and the schema already documents it as the ID returned by crawl_site. The description adds no semantic detail beyond 'by job ID', so the baseline 3 applies.

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 (running or pending crawl job) with scope. Though it doesn't name a sibling, its purpose is unmistakable against crawl_site and get_job_status in the sibling list.

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 indicates the applicable job states (running or pending) and an exclusion (terminal state jobs have no effect). It does not name an alternative tool or say when to prefer checking status first.

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?

Discloses behaviour well beyond the annotations: builds in a staging area, atomic replacement of the corpus on success, previous corpus preserved on cancel/failure, and a kept-back crawl that fails with 'refused' when pages are lost. This is consistent with destructiveHint=false and non-idempotent semantics and clarifies the failure mode precisely.

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 tight sentences, front-loaded with purpose and return behaviour, then failure semantics. No filler; each sentence carries distinct 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?

An output schema exists, so return structure need not be spelled out, and the description still notes the job ID. For a 3-parameter mutation with annotations, the failure and atomicity story is fully covered.

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 coverage is 100% so the baseline is 3, but the description adds real meaning to allow_shrink by explaining the shrink guardrail and the 'refused' failure that it overrides. Incremental mode itself is left to the schema text.

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') plus the immediate return ('job ID'), which distinguishes it from siblings like get_job_status and cancel_crawl that operate on the resulting job.

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?

Clear operating context: asynchronous start, staging-then-publish semantics, and the shrink guardrail with the workaround implied by the allow_shrink schema text. It does not explicitly name alternatives (e.g. why to prefer this over re-drafting a site), so it stops 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?

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful context that the call returns consolidated identity, sites, and recent job data in one call, though it does not discuss pagination, caching, or response limits.

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 front-loaded with what the tool returns, followed by when to call it and why. All three sentences contribute directly to selecting and understanding the tool, with no wasted wording.

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 the rich annotations, no parameters, and an output schema, the description is sufficiently complete. It explains the tool's purpose, usage, consolidation value, and even clarifies why the MCP tool list is not included.

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?

There are zero parameters, so parameter semantics are inherently simple. The description does not need to explain parameters, and the baseline for a no-parameter tool applies.

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 resources: returns server identity, configured sites, and recent crawl jobs. It clearly distinguishes itself from siblings by explaining that it consolidates what would otherwise require list_sites plus several get_job_status calls.

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 explicit usage guidance: 'Call this first to orient yourself.' It also names the alternatives it replaces (list_sites and several get_job_status calls), leaving little ambiguity about when to use this tool versus its 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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: verdicts are hash-based from a SQLite history index (no content re-fetch), and the baseline is data-dependent, requiring a prior crawl. It does not state what happens with zero or one prior crawl (empty result vs. error), which is the remaining gap.

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?

Front-loaded with the core verb+resource, then baseline semantics, then a short workflow recipe; every sentence contributes. There is mild duplication between "the crawl before it by default" and the schema's "Omit to compare with the previous crawl."

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?

An output schema exists, so return shape needn't be described; the description covers baseline resolution and the prerequisite crawl workflow, which is what an agent needs to call it correctly. The only unaddressed case is degenerate history (no prior crawl) where the agent doesn't know whether to expect an error or empty diff.

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 `since`, `offset`, `max_results`, and `site_key` are already documented in structured fields, and the description's `since` wording largely restates the schema's RFC3339 baseline rule. It adds the useful default ("the crawl before it by default") but nothing about pagination or `max_results` interaction. Baseline 3 applies when the schema carries the detail.

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?

"Return added/removed/changed pages between the latest crawl and a baseline crawl" gives a specific verb (return) plus the exact resource (page-level diff between two crawls). It also implicitly separates the tool from list_pages/get_page (content access) and get_freshness (staleness), so an agent can route correctly from names alone.

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 spells out the operational sequence explicitly: "run crawl_site, wait for it to finish, then call diff_crawl without since," naming the sibling tool and the required precondition. It also states the default baseline and the alternative (pass `since`) with the exact selection rule, leaving nothing to inference.

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 readOnly/openWorld/idempotent/non-destructive, and the description reinforces this with 'Never writes the config' while disclosing what probing actually does (robots.txt, llms.txt, sitemap, framework detection) — real behavioral context beyond the hints. It stops short of covering failure modes or network cost/rate limits for the probe.

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?

Front-loads purpose and the no-write guarantee, then moves through the two modes, the overrides format, and the recommended workflow. Dense but zero filler sentences; every clause carries operational 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?

For a 4-param tool with a nested free-form object and an output schema present, the description supplies the missing pieces: overrides field naming/format, the meaning of the preview, and the explicit handoff to save_site. Return-value details are correctly delegated to the output schema.

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 coverage is 100%, so baseline is 3. The description does add value for `overrides` — naming concrete config field names (content_selector, allowed_path_prefix, disallowed_path_patterns, max_depth) and the duration string format ('1s') — which compensates for the nested object having no defined properties, but url/site_key/preview_url semantics are already fully covered by 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 specific verb and resource ('Draft a site entry and preview one page extracted with it') plus a negative scope clause ('Never writes the config'). This clearly separates it from the sibling save_site, which is named explicitly as the follow-up step.

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?

Gives an explicit branching rule: with `url` it probes a new docs site the way `doc-scraper add` does; with only `site_key` it starts from an existing configured entry without probing. It also states the full iteration loop (judge preview → re-draft with overrides → pass entry to save_site), naming the alternative tool that commits.

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, non-destructive, closed-world behavior, so the description's added value is the decision-relevant content: age_seconds, dir presence, and any running job. It goes beyond restating annotations by describing what state the agent will see, though it doesn't say how freshness should be interpreted.

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 the return payload and closing with the decision use case. Dense but nothing is wasted; the parenthetical field list is long yet earned.

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?

Complete for a single-parameter read tool with annotations and an output schema: the agent knows what it returns and why to call it. The only gap is guidance on interpreting age_seconds to judge staleness, which the agent must infer.

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 coverage is 100% and the single site_key parameter is fully documented in the schema, including a pointer to list_sites. The description adds no parameter-level detail, so baseline 3 applies.

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 ('return the most recent crawl summary for a site') and enumerates the payload (last_crawl start/end, total_pages, mode, age_seconds, dir presence, running job). This is clearly distinguishable from crawl_site, get_job_status, and other siblings.

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?

Explicitly frames usage as a decision step: 'Use this to decide whether to query the existing crawl or run crawl_site first,' naming the alternative tool. It never states when not to use it or what threshold makes a crawl stale, but the routing intent is unambiguous.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral detail beyond that: the call returns as soon as the job completes, fails, or is cancelled, or when the wait expires, and reports status at that moment. It doesn't discuss error behavior for unknown/expired job IDs.

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 what the tool does, then the non-obvious wait semantics. No padding or restatement of the title.

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?

A two-parameter read tool with an output schema, full schema coverage, and complete annotations; the description covers the one non-obvious behavior (blocking until terminal state or timeout). Nothing an agent needs to call it correctly 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining what wait_seconds actually does semantically — it blocks and returns early on terminal states rather than simply sleeping. That meaning is not obvious from the schema's 'Seconds to wait' wording.

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 ('Get the status and page counts of a crawl job') and names the object precisely enough to separate it from siblings like cancel_crawl, get_freshness, and list_pages. An agent knows exactly what it gets back conceptually without opening the schema.

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?

Explicitly contrasts the long-poll mode with the polling alternative ('Set wait_seconds to wait for the job to finish instead of polling'), which is real when-to-use guidance. It stops short of naming sibling tools for adjacent needs (e.g., cancel_crawl to abort, list_pages to inspect results).

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 it read-only and open-world, but the description adds materially: bypassing crawl storage and site config, truncation at max_bytes, and the non-obvious cost that each paginated call re-fetches the page. The only blemish is the reference to a 'next_offset' field that does not exist in the schema (the parameter is 'offset'), which could momentarily confuse an agent.

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, front-loaded with the action and the crawl-independence caveat before the truncation mechanics. Nearly every clause earns its place; the 'next_offset' wording is the one piece of noise that should have been 'offset'.

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 4-parameter fetch tool with full schema coverage and an output schema, the description covers what an agent must know: it is live, it ignores stored/config state, and large pages are truncated with a re-fetch cost. 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 coverage is 100%, so the baseline is 3 and all four parameters already carry descriptions. The description adds real meaning for offset/max_bytes by tying them to truncation and the refetch requirement, but it does so under a mismatched name ('next_offset'), so the added value is partial rather than clean.

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 ('Fetch an HTML page live over the network and return its content as markdown') and immediately scopes it against the crawl-based siblings by saying it does not read stored crawl output. An agent can distinguish this from read_page/list_pages/crawl_site without opening any schema.

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?

Explicitly frames the tool as an on-demand live fetch independent of any crawl and notes it ignores the site's content_selector and scope, which is exactly the condition that decides between this and the stored-crawl siblings. It stops short of naming the concrete alternative (read_page) or stating when a live fetch is wasteful, so it is clear context rather than full routing 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?

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds behavior beyond them: results are sorted by URL, only metadata is returned (URL, title, depth, crawled_at, content_length), and the stored copy vs live fetch distinction between read_page and get_page. It doesn't discuss pagination termination or total counts, but the added context is substantial.

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 dense sentences with zero filler: purpose and return shape first, then the routing rule, then the sibling disambiguation. Every sentence earns its place and nothing is buried.

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?

An output schema exists so return values needn't be spelled out, yet the description still names the key metadata fields. For a simple, annotation-covered read tool with fully documented parameters, nothing an agent needs in order to call it correctly 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%, and the schema already documents offset, site_key provenance (list_sites), and max_results defaults/caps. The description only implies pagination ('paginated') and adds no parameter-level syntax or bounds beyond the schema, so the baseline 3 applies.

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 names a specific verb and resource ('List crawled pages for a site') plus scope details (paginated, sorted by URL) and return shape (metadata only). It also explicitly distinguishes itself from both read_page and get_page, so an agent can tell the three apart without opening any schema.

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 explicit routing: 'Pass any URL returned here to read_page to get its stored markdown' and clarifies that 'get_page re-fetches a URL live rather than returning the crawled copy.' That's a when-to-use plus a named alternative with its selection condition.

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, destructiveHint=false and a closed-world scope, so the safety and side-effect profile is fully covered elsewhere. The description adds no behavioral context beyond that (e.g., empty-list behavior, scope of 'configured'), so it neither contradicts nor enriches the 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?

A single front-loaded sentence with no filler; the verb and scope come first and nothing is wasted.

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 nullary list tool, the annotations cover the safety profile and the output schema covers the return shape, so the description need not explain result structure. Nothing an agent needs to call this correctly is absent.

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 tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. No parameter-related value is expected or missing.

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+resource (list sites) plus scope ('all configured', 'available for crawling'), which implicitly separates it from mutation siblings like crawl_site. It does not explicitly distinguish itself from the other list-style sibling list_pages, so it stops short of a top score.

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: 'available for crawling' hints this is a discovery step before crawl_site, but there is no explicit when-to-use, when-not-to-use, or mention of an alternative tool. Adequate but leaves the agent to infer the workflow.

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 readOnly, idempotent, closed-world, non-destructive, so the safety profile is carried elsewhere. The description nevertheless adds real behavioral context: no network access, content_selector already applied, truncation at max_bytes, and continuation via the next_offset returned in the response. Minor gap: it does not mention that offset values are byte-based here, though the schema covers that.

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?

Five short sentences, each carrying distinct information: what it returns, how it differs from get_page, the discovery workflow, the anchor shortcut, and pagination. No filler and the differentiation is front-loaded.

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 an output schema present, return values need not be explained, yet the description still covers truncation and continuation. For a 5-parameter read tool with full schema coverage and annotations, nothing an agent needs to call it correctly 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 coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it links anchor to search_docs results, explains offset as continuation of a truncated page, and explains max_bytes truncation behavior. It also references a next_offset return field, which pairs with the offset parameter rather than duplicating it.

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 (return a page's markdown from stored crawl output) and immediately contrasts it with the sibling get_page, explaining the exact difference (crawled copy with content_selector applied vs live re-fetch). An agent can distinguish the two without opening either schema.

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?

Explicitly routes the agent: list_pages to discover URLs, read_page to read them, get_page for live fetching, and passing a search_docs anchor to read only a section. This covers both when to use it and which sibling to pick instead.

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 beyond the annotations by disclosing scoping ('only the entry's lines change in the file'), the partial-merge semantics ('fields left out are unset'), and the two refusal conditions (active crawl, config-writes flag). These details substantially reduce the risk of an incorrect destructive call, and the safety annotations already flag the mutation.

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, front-loaded with the action and immediate effect, then behavioral constraints, then failure conditions. No filler and no restated schema text.

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?

An output schema exists, so return values need not be described. Given a destructive tool with nested parameters, the description supplies everything else an agent needs: the write's scope, merge semantics, replace requirement, and both refusal conditions.

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 coverage is 100% and each parameter has a description, but the description adds meaning the schema cannot: the entry object is empty in the schema, yet the description explains it is keyed by config field name, is normally derived from draft_site, and leaves omitted fields unset. It could state the field names explicitly, which is why this is not a top score.

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 (write a site entry to the config file and load it into the running server) and names what becomes possible afterward (crawl_site, search_docs, read_page). A reader can distinguish it from draft_site, which only drafts an entry.

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?

Explicitly says the entry normally comes from draft_site with modifications, when replace:true is required for overwrites, when it is refused (while crawling, or servers started without -allow-config-writes), and that omitted fields are unset. When-to-use, prerequisites, and failure conditions are all covered.

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?

Adds context beyond annotations: BM25/stemming ranking, zero-network guarantee, stored-index-only scoping, and result shape (URL, heading path, [marked] snippet). Annotations already declare readOnly/idempotent/openWorld=false; the description reinforces and enriches rather than contradicting. Query relaxation behavior lives in the schema, so a small gap remains.

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?

Front-loads purpose and ranking, then follows with return format, syntax, and prerequisites. Every sentence carries information; slightly dense but 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?

Despite an output schema existing, the description still explains result contents and how to continue to full pages. Combined with the schema, an agent has everything needed to call and follow up 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 coverage is 100%, so parameters are already fully documented including ANDing, relaxation, and limit capping. The description's FTS5 syntax note largely duplicates what the schema states, so it adds little beyond the structured baseline.

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 ('Full-text search across all crawled documentation') plus ranking mechanism (BM25 with stemming). Clearly distinguishes itself from read_page and crawl_site, which are named as follow-up/prerequisite 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?

Explicitly routes the agent: 'follow up with read_page for the full page' and 'run crawl_site first for uncrawled sites.' Both alternatives and the conditions selecting them are named, so the agent needn't infer anything.

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