map

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well by explaining the return shape (limited URLs, site-wide total, per-section summary), the filtering behavior, and the grouping alternative. It does not cover failure modes or edge cases, but the core behavior is transparent.

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 dense but efficient, with the main purpose front-loaded and parameter behavior woven into contextual prose. It could be slightly trimmed, but every sentence carries useful information and there is 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?

There is no output schema, so the description must convey the return shape, and it does: limit, total, summary, and the group_by path-tree alternative. It also contextualizes search as the primary filtering path. Minor omissions like includeSubdomains behavior are already covered by the schema, so the overall definition is complete enough.

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 is 3. The description adds meaningful context beyond the schema: it explains the default limit, that total/summary always cover the whole site, that search is the primary narrowing mechanism, and that group_by produces a path tree with counts. This is genuine added value.

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: 'Discover a site's URLs fast' and names concrete discovery sources (robots.txt sitemaps, /sitemap.xml, homepage links). It also distinguishes itself from a full crawl, making it easy to differentiate from the sibling crawl tool.

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 clearly states it is for fast URL discovery 'without a full crawl', giving context for when to use it versus crawling. It also explains how to narrow results with search and group_by. It doesn't explicitly name all sibling alternatives or exclusion conditions, but the 'without a full crawl' contrast provides enough guidance.

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