Geonode Scraper MCP

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

Beyond the sparse annotations, it discloses the asynchronous job behavior, the returned job ID, the X-Api-Key authentication requirement, and subtle wait_config behavior including auto-enabling render_js and rejecting ambiguous render_js=false combinations. This is substantial operational context an agent would not get from the annotations 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?

The definition is front-loaded and compact: purpose first, then capabilities, then the nontrivial wait_config edge case, then return value and auth. The longer wait_config sentence earns its place because it prevents a likely misuse.

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 an async job-start tool with no output schema, the description explains the return value (job ID) and the polling path via batch_status, and it covers auth requirements. It could say more about invalid URL handling or batch limits, but those are documented in the 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?

The description highlights formats (HTML/Markdown), render_js, proxy settings, headers, and the grouped wait_config policy, adding meaning about the omit-vs-{} opt-in behavior. It does not mention every parameter such as ignore_invalid_urls, and much of the nested schema is already well documented, so it is helpful but not fully compensatory.

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 first sentence states a specific verb and resource: 'Start an asynchronous batch extraction job from an explicit list of URLs.' The phrase 'explicit list of URLs' immediately distinguishes it from sibling site-crawling tools, and the job ID/polling reference ties it to batch_status.

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 makes clear this is for a supplied URL list and that polling should use batch_status. It stops short of explicitly naming extract or crawl as alternatives or stating when not to use this tool, so it is strong but not fully exhaustive.

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 state readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the description does not need to repeat safety behavior. It adds useful context by disclosing pagination, returned fields (item counts, invalid URLs, per-URL results), and the required Geonode API key header. It stops short of describing error behavior or status states.

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 three tight sentences with the core action and return contents front-loaded. Every sentence contributes useful information: purpose, response shape, and auth requirement.

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 status/results tool with no output schema, the description gives enough context to call it correctly: job ID lookup, paginated results, returned fields, and API-key auth. It could be stronger with job-state semantics or error behavior, but the essential completeness is there.

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 carry the burden for four parameters. It clarifies that job_id identifies the batch extraction job, that results are paginated by page, and that api_key is sent as the X-Api-Key header, but it does not explain page_size semantics, limits, or defaults beyond what the schema already shows.

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 gives a specific verb and resource: retrieve the status and paginated results of a batch extraction job by job ID. It clearly distinguishes this from creation or cancellation siblings such as batch and cancel_batch by focusing on status/results retrieval.

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 implies the tool is used when you have a batch job ID and need its status/results, but it does not explicitly say when to use this versus alternatives like batch, job, or jobs. There are no exclusions or guidance on polling versus one-time retrieval.

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 (destructiveHint=true, readOnlyHint=false), the description discloses genuinely useful behavior: cancellation is not abrupt — new batch items stop being scheduled while in-flight child extractions drain. It also states the auth requirement (Geonode API key in the X-Api-Key header). It does not cover idempotency or what happens when cancelling an already-completed job.

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 tight sentences: the operation and identifier come first, followed by the drain semantics and auth note. Every clause carries information an agent would otherwise have to guess.

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 and only two parameters, the description covers the essentials: what is cancelled, the partial-stop behavior, and the auth mechanism. Missing edge-case behavior (cancelling a finished job, repeat calls) is minor but prevents a full score.

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 0%, so the description must carry the parameter burden, and it largely does: job_id is tied to the batch job being cancelled, and api_key is explained as a Geonode API key transmitted via the X-Api-Key header, which the schema does not say. It stops short of noting where job_id comes from (e.g., a batch creation response).

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 ('Cancel a batch job') and immediately scopes it by identifier ('by its job ID'), which distinguishes it from sibling cancellation tools like cancel_crawl and from read-only batch/job inspection tools. An agent can identify the operation 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?

Usage is implied rather than stated: the drain semantics hint at when a soft cancel is preferred, but the description never says when to pick this over batch_status or job, nor does it note any prerequisites such as the job being in a cancellable state. No explicit alternatives or exclusions are given.

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 flag destructiveHint=true, but the description adds real substance beyond that: cancellation is graceful, stopping new page scheduling while letting in-flight work drain. It also discloses the auth requirement (Geonode API key as X-Api-Key header), which annotations do not cover.

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 action, then the cancellation semantics, then the auth requirement. No filler or repetition 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?

For a two-parameter mutation tool with no output schema, the description covers action, semantics, and auth. A note on what state the job ends in or what is returned would make it fully self-sufficient, but 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 compensate. It explains job_id as the crawl job identifier and clarifies the api_key parameter's transport (X-Api-Key header), which the bare schema does not. It does not clarify whether api_key is optional or falls back to an environment variable.

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 ("Cancel a crawl job by its job ID") and clarifies scope with crawl semantics. It does not explicitly distinguish itself from nearby siblings like crawl_status or cancel_batch, but the action verb is unambiguous.

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: cancellation presupposes an existing crawl job, presumably found via crawl_status or jobs. There is no explicit when-to-use/when-not guidance or routing to cancel_batch for batch jobs, leaving the agent to infer the boundary.

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 cover the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), and the description adds genuinely useful behavior: the job-ID return value, the required X-Api-Key header, BFS traversal order, and the non-obvious rule that a non-null wait_config auto-enables JS rendering while render_js=false plus wait_config is rejected. Some of that (auto-enable, rejection) restates schema prose, but the auth and async-job traits are description-only.

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 purpose, then capability summary, then the wait_config nuance, then the return/auth facts. The wait_config sentences are dense and slightly over-explained relative to everything else, but every sentence carries 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 long-running, authenticated, open-world crawl job with no output schema, the description supplies the missing pieces an agent needs: what is returned (a job ID), how to retrieve results, and how credentials are passed. Deeper result-shape details are correctly deferred to crawl_status.

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?

Although the reported coverage metric is 0%, the nested schema is densely documented; the description still adds value by explaining depth as BFS levels and limit as a page cap in plain terms, and by spelling out the tri-state wait_config (omitted/null = adaptive settle, {} or concrete = explicit mode). It does not cover proxy geo-targeting defaults or formats in the same detail, so it is strong but not exhaustive.

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?

Opens with a specific verb+resource ('Start a website crawl job from a seed URL') and immediately distinguishes itself from the sibling 'crawl_status' by positioning this as the job-creating call and that as the polling call. No ambiguity about what the tool produces.

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 tells the agent to poll results with 'crawl_status' and states the authentication prerequisite. It does not contrast against nearby alternatives like 'batch', 'map', or 'extract', so the agent must infer when a single-site crawl beats a batch or map job.

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 and non-destructive behavior. The description adds substantial value beyond them: it lists the exact status values (queued, running, completed, failed), says page counts and crawled page content are returned once completed, and discloses the API-key/header requirement.

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 tightly written sentences, front-loaded with what the tool returns and then covering pagination and auth. No sentence is redundant or padding.

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 present, the description compensates by describing the return shape (status, page counts, crawled page results with extracted content). Auth and pagination are both covered, so an agent needs nothing else to invoke this 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 0%, so the description must carry the parameter burden. It explains the roles of job_id, page, page_size, and api_key (including the X-Api-Key header), though it does not mention the default values or the 1-based page convention that the schema's defaults imply.

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 ('Retrieve the status and results of a crawl job by its job ID') and explicitly distinguishes this polling/retrieval role from the sibling 'crawl' that starts a job. An agent can immediately tell this is the status/result lookup 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?

It clearly says this is for retrieving status and results by job ID, and explains that page/page_size navigate paginated results. It stops short of naming alternatives (such as batch_status or map_job) or stating when not to use this tool, but the intended polling usage is obvious.

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/non-destructive, and the description layers substantial extra context: unauthenticated calls are sync-only with limited rate/volume, an X-Api-Key header lifts restrictions, and the plan's own limits then apply. It also flags rejection behaviors (ambiguous render_js=false with non-null wait_config) and the returned job-ID contract for async. This is well beyond what the annotations convey.

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?

Purpose is front-loaded and each sentence carries distinct information about modes, rendering, and auth tiers. It is dense and sentence-heavy, packing several distinct behaviors into long clauses, but there is little outright padding given the tool's surface area.

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 with an extensive nested schema and no output schema, the description covers the critical decision paths: sync vs async and how to poll, JavaScript rendering triggers, wait_config modes, and auth/rate-limit consequences. An agent has enough to call this correctly without opening the 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?

Top-level schema coverage is reported as 0%, and api_key in particular carries no schema description, so the description's explanation of the X-Api-Key header and its effects on rate limits, rendering, and headers is genuinely additive. For the nested request it also clarifies non-obvious semantics (null wait_config vs {} vs concrete values, render_js auto-enable), though some of that is echoed from the nested schemas.

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?

Opens with a specific verb+resource: 'Extract content from a web page.' An agent immediately knows this is a page-content extraction tool. No siblings exist to differentiate from, and the title mirrors the description, so there is no further distinction to draw.

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 concrete when-to-use conditions: use render_js=true for JavaScript-dependent pages, supplying wait_config auto-enables rendering, and omit/null wait_config to keep the adaptive settle path while {} opts into explicit mode. It also names the polling alternative ('job' tool) for async mode. It stops short of stating when not to use the tool at all, but the branching guidance is explicit.

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 read-only, non-destructive, closed-world behavior. The description adds valuable context beyond that: status lifecycle (pending/running/completed/failed), that content and metadata are returned only once completed, and the authentication requirement via X-Api-Key header.

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 compact sentences, front-loaded with the core action and return behavior, followed by usage context and auth requirement. 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 getter without an output schema, the description covers what the tool does, when to use it, what it returns (status and completed content/metadata), and how authentication works. An agent has enough to invoke 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 0%, so the description must carry parameter meaning. It explains the job_id purpose and clarifies that api_key is sent as the X-Api-Key header, but it does not specify the job ID format or whether api_key is optional, leaving some ambiguity.

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 ('Retrieve the result of an asynchronous extraction job by its job ID') and distinguishes it from sibling listing tools like 'jobs' by emphasizing retrieval of a single job's result. The status values further clarify what the tool returns.

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 to use this tool to poll for results after submitting an extraction with processing_mode='async', giving a clear usage context. It stops short of naming exclusions or alternatives (e.g., 'not for listing all jobs'), so it is strong but not exhaustive.

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 readOnly=true, destructive=false, openWorld=false, so safety is covered. The description adds genuinely non-derivable context: an API key is required and must be sent as the X-Api-Key header, and results are paginated. It stops short of describing sort order or what a result row contains.

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 short sentences, front-loaded with purpose then filters, pagination, and auth — no filler. The one redundancy is restating 'page' and 'page_size' by name when they are already visible in the schema.

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 9-parameter, no-output-schema, read-only listing tool, the definition covers filters, pagination, and authentication — the three things an agent needs to call it correctly. What is missing (default page_size=100, ordering, and correct enum values) is small in volume but the enum error is consequential.

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 0%, so the description must carry parameter meaning — and it does map most parameters (job_id, url, job_status, output, start_date/end_date, page, page_size). However, it documents the status vocabulary as "pending, running, completed, failed," which conflicts with the schema enum (queued, processing, completed, failed, cancelled); an agent following the description would send invalid values. api_key is described only as a header, not as a parameter.

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?

Clear verb + resource: "List extraction jobs with optional filters." The tool's read/listing nature and supported filter dimensions are unambiguous. It does not, however, distinguish itself from near-name siblings like `job`, `search_jobs`, or `map_jobs`, so an agent must infer that this is the general listing endpoint.

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 rather than stated: filters and pagination guidance ('use page and page_size to navigate large result sets') tell the agent how to shape a call, but there is no explicit when-to-use-this-vs-`job`/`search_jobs` and no stated exclusions. The auth prerequisite is the only hard precondition given.

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 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.

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

Annotations already establish that this is a safe read-only, non-destructive, closed-world operation. The description adds useful context beyond annotations by stating that it returns current status and, after completion, discovered links and their source, and by disclosing the Geonode API key header requirement.

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 three efficient sentences with no waste. The purpose is front-loaded, followed by return behavior and then the authentication requirement.

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 two-parameter read-only retrieval tool with annotations and no output schema, the description covers the main call purpose, return content, and auth mechanism. The remaining gap is the unclear relationship between the optional api_key schema field and the stated API key requirement.

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 compensate. It explains that job_id identifies the map job and that an API key is sent via X-Api-Key, but it does not clarify the optional/nullable status of the api_key parameter or provide format details for job_id.

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 and resource: retrieve a map job's full details and discovered links by job ID. This clearly identifies the operation, but it does not explicitly distinguish it from sibling tools such as map_jobs, job, or search_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?

Usage is implied: call this when you have a map job ID and need its details or discovered links. However, the description gives no explicit when-not guidance or alternatives, so the agent must infer the boundary against map_jobs and other job-retrieval 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful context the annotations lack: it acts only on the caller's own jobs, results are paginated, and an API key must be supplied in the X-Api-Key header. However, it lists statuses ('pending, running') that do not exist in the schema, which actively misleads.

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, purpose front-loaded, then filters, then pagination, then auth prerequisite. No filler, though the auth sentence could sit earlier as a prerequisite.

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 and 0% parameter description coverage, the description must fully specify the contract; it covers every parameter at a high level but withholds return shape (what a job record contains) and supplies an incorrect status vocabulary. Adequate scaffolding, but not a reliable contract.

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 carry the parameters, and it does cover url (partial match), date range, page, page_size, and api_key. But the status values it enumerates ('pending, running, completed, failed') contradict the schema enum ('queued, processing, completed, failed, cancelled'), a substantive accuracy failure for a filter parameter.

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 ('List map jobs') and scopes it to the authenticated user with optional filters, which cleanly separates it from the singular map_job and from job/jobs siblings. It never explicitly names a sibling alternative, so it stops short of a 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?

Gives clear operational context: filter by URL partial match, status, or date range, and paginate via page/page_size. It does not say when to prefer map_job, job, or batch instead, so alternative routing is absent.

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 (readOnly/openWorld/non-destructive), it discloses engine rotation and fallback semantics, that a pinned engine failure surfaces as your error instead of being routed around, that an empty result list is a valid answered search, and that such a search is not charged. It also names the auth mechanism (Geonode API key via X-Api-Key header), which no structured field provides.

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 dense paragraph that front-loads the core action, then capabilities, then defaults, then return shape and auth, with no filler sentences. Every clause carries information an agent would otherwise have to infer, even where it overlaps the schema.

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 enumerating the return payload (result list, serving engine, query suggestions, spelling correction). Combined with the auth requirement, billing note, and fallback behavior, an agent has everything needed to call this correctly and interpret common edge cases like empty results.

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 description restates the meaning of locale format, page, safe-search, time_range, and engine, and crucially explains the top-level `api_key` parameter, which carries no description in the schema despite the reported 0% top-level coverage. Most individual parameter detail is duplicated by the nested SearchRequest property descriptions, so it reinforces rather than extends the schema on those fields.

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 ("Run a web search and return ranked results"), so there is no ambiguity about what the tool does. It implicitly separates itself from sibling `crawl`, `extract`, and `map` by being a plain query-to-results lookup, but it never explicitly contrasts with `search_job`/`search_jobs`, which is the nearest alternative an agent must choose between.

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 real decision guidance for one parameter cluster: default engine rotation is stated as what "most callers want," and pinning is framed as trading reliability for control, which is a usable when/when-not rule. However, there is no guidance on when to choose this synchronous search rather than the sibling `search_job` or `batch` tools, so tool-level routing is left 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 read-only, non-destructive, non-open-world behavior, and the description adds useful context about authentication via X-Api-Key and what is returned as status and results. It still does not cover error behavior or polling guidance, but it substantially supplements 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?

The description is three concise sentences with no filler. The primary action and scope are front-loaded, followed by return behavior and authentication.

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 retrieval tool with no output schema, the description adequately explains the status and result content plus authentication. It lacks guidance on error cases or whether the caller should poll, but the core usage context is present.

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 explain parameters, and it does address both: job_id identifies the search job and api_key is sent as the X-Api-Key header. It does not specify job_id format, and it calls the API key required even though the schema marks it optional/nullable, leaving a minor ambiguity.

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: retrieve a search job by job ID, including details and results. It is clear what the tool does, though it does not explicitly name or differentiate from siblings such as search_jobs or 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?

Usage is implied by the need to retrieve a search job using its job ID. The description adds the API key requirement, but it does not state when to use this instead of alternatives like search_jobs or how to handle incomplete jobs.

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 and destructiveHint=false, so safety is covered. The description adds non-trivial context the schema does not carry: it requires a Geonode API key sent as an X-Api-Key header, and results are paginated. It stops short of describing what a job record contains or how results are ordered.

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 with the core action front-loaded and pagination/auth folded in efficiently. No filler, though the status enumeration is the weakest sentence because it is inaccurate.

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 annotations covering the safety profile and no output schema, the description supplies the missing auth and pagination essentials. The main gap is that an agent gets no sense of the returned fields and no warning about the status-value mismatch with the schema enum.

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 carries the burden and does explain query as partial match and maps date range and page/page_size. But it misstates the status values ('pending, running' vs. the schema enum 'queued, processing, cancelled'), never mentions the api_key parameter directly, and omits the defaults (page=1, page_size=10) and the start_date/end_date parameter names.

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+resource ('List search jobs') and states the scope ('for the authenticated user with optional filters'). It does not differentiate from the closely named siblings search_job, jobs, and job, so an agent cannot tell from the description alone which of those to pick.

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 usable context for how to filter (query partial match, status, date range) and how to paginate, which implies the usage scenario. However, there is no explicit when-to-use guidance and no mention of when to prefer search_job, job, or batch_status 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the Geonode API key must be sent as an X-Api-Key header, and out-of-bounds dates are silently clamped (old start moved up, future end moved back to now) rather than rejected — behavior an agent would otherwise not predict.

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, front-loaded with purpose, then return contents, then argument/limit rules, then auth. No sentence is redundant and nothing buries the important constraints.

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 naming the returned metrics (total jobs, success/failure counts, usage breakdowns). Combined with the date-clamping rules and auth requirement, an agent has everything needed to call this correctly in one shot.

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 0%, so the description carries the full burden, and it does: start/end dates define a window capped at 366 days counted back from the end date, omitted dates default to the last 30 days, and api_key is transmitted via the X-Api-Key header. It does not spell out the date string format, but the schema's date-time format covers that.

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 ("Retrieve aggregated extraction statistics") and scopes it to the authenticated user. This is clearly distinguishable from sibling tools like jobs, job, or crawl_status, which deal with individual records rather than aggregates.

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?

Explains when defaults apply (last 30 days when no dates given) and how the date window is constrained, so an agent can pick arguments confidently. It stops short of naming alternatives (e.g., use jobs for per-job detail versus statistics for aggregates), so the routing is implied rather than explicit.

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