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

Annotations already establish readOnly/openWorld/non-destructive, and the description adds real context beyond them: synchronous execution, immediate return of links, and a required Geonode API key sent as X-Api-Key header. It also discloses exclusion rules (sibling subdomains, outbound links) and active subdomain probing, though it says nothing about rate limits or behavior on very large sites.

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 action, then scope defaults, then the widening flag, then the filter caveat, then execution/auth facts. Five dense sentences 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?

With no output schema, the description usefully states that discovered links are returned immediately and that execution is synchronous. Auth and scoping are covered; the remaining gap is guidance on switching to the async map_job siblings for large or long-running maps.

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 measures 0% at the top level, and the api_key parameter carries no description, so the mention of the X-Api-Key header is genuinely additive. The description also reinforces and contextualizes include_subdomains (widening to registrable domain plus probing docs/blog/help/support) and clarifies that 'search' is a substring filter rather than a query; only ignore_query_parameters goes unmentioned.

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: discover all URLs under a base URL by combining sitemap parsing with HTML link extraction. The mechanism is named, and it is clearly distinguishable from siblings like crawl (fetch pages), search (query engine), and extract (pull content).

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 implicitly disambiguates the 'search' parameter from a search engine, which helps against the sibling 'search' tool, and explains default vs widened scope. However, it never states when to choose map over crawl/extract, nor when the asynchronous map_job/map_jobs siblings should be preferred for large sites.

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