web_index

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

With no annotations, the description carries the full burden and does so well: it discloses where state is persisted (DATA_DIR/index/<host>.json), recursion caps (20 files, 2 layers), the 20-URL refetch budget for content checks, the deadline_ms budget behavior, proxy-pool fallback, and that reset discards the old baseline. The dry_run flag is explained as a preview-only mode, and reset's destructive effect on the baseline is stated explicitly.

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 purpose is front-loaded in the first line, followed by sitemap-discovery rules and then a compact per-parameter list. Every sentence adds information, but the block is long and the parameter documentation is dense enough that an agent must scan carefully; a short summary line before the Args would tighten it.

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 10-parameter tool with no annotations and an output schema, the description covers discovery fallbacks, recursion limits, persistence path, diff categories (added/changed/unchanged/removed), and each parameter's behavior. The output schema handles return shape, 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 0%, so the description must fully compensate, and the Args block documents all 10 parameters with semantics, defaults (limit 1000, hard cap 5000), and edge behavior (include/exclude regex, no filter when omitted; check_content only refetches lastmod-changed entries). This is richer than any schema would typically provide.

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 opening line states a specific verb and resource: read the site's sitemap, enumerate page URLs, and diff against the previous list. The scope is concrete (sitemap discovery via robots.txt or /sitemap.xml, recursive expansion) and an agent can tell this is an inventory/diff tool. It doesn't explicitly say how it differs from sibling web_map, which likely also produces URL maps, so it stops short of 5.

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 implied by the diff/baseline framing: use it to track which pages appeared, changed, or disappeared on a site. However there is no explicit when-to-use or when-not-to-use guidance, and no comparison against the 15 sibling tools (web_map, web_crawl, web_watch) that plausibly overlap. The reader must infer the routing decision.

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