Extract web pages, crawl and map sites, search the web. Extract needs no key; other tools need one.
Scored across 16 tools
The core actions (extract, batch, crawl, map, search) are clearly distinct in target and behavior, and descriptions explain when to use each. The main ambiguity is among the job-polling tools: bare 'job'/'jobs' retrieves and lists extraction jobs, while 'batch_status', 'crawl_status', 'map_job', 'search_job' each poll a different job type, so an agent must remember which poll tool maps to which submission tool.
Names are readable snake_case but the pattern for the same concept varies: batch/crawl use a '_status' suffix, map/search use '_job', and extraction uses bare 'job'/'jobs'. Only cancel_batch/cancel_crawl use a verb prefix, leaving a mixed noun-only vs verb-prefixed convention across the set.
16 tools is on the higher side, but the count is largely earned because five job-producing domains (extract, batch, crawl, map, search) each need a start plus a poll/list companion. Nothing appears obviously redundant, though the parallel job/status/status_list triads add bulk.
Each domain has start plus status/list coverage, giving broad lifecycle support, and statistics rounds out usage monitoring. The notable gap is that batch and crawl have explicit cancel tools but async extraction jobs have no cancel counterpart, and batch lacks a batch-list equivalent to 'jobs'/'map_jobs'/'search_jobs'.
Start an asynchronous batch extraction job from an explicit list of URLs. Supports HTML and Markdown output formats, optional JavaScript rendering, proxy settings, custom headers, and the grouped wait_config browser wait policy. Omit wait_config or set it to null to keep adaptive browser settling for child extractions; send {} or concrete values to opt every child extraction into explicit mode. Returns a job ID that can be polled with the 'batch_status' tool. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| batch_request | Yes |
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.
Retrieve the status and paginated results of a batch extraction job by its job ID. Returns item counts, invalid URLs, and the current page of per-URL extraction results. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| job_id | Yes | ||
| api_key | No | ||
| page_size | No |
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.
Cancel a batch job by its job ID. Stops scheduling new batch items while allowing in-flight child extractions to drain. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| api_key | No |
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.
Cancel a crawl job by its job ID. Stops scheduling new crawl pages while allowing in-flight page work to drain. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| api_key | No |
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.
Start a website crawl job from a seed URL. Crawls pages breadth-first (BFS) up to the 'depth' parameter (BFS levels from the seed) and the 'limit' parameter (maximum number of pages to crawl). Supports Markdown and HTML output formats, optional JavaScript rendering, proxy geo-targeting, domain filtering, and the grouped wait_config browser wait policy. Omit wait_config or set it to null to keep adaptive browser settling for page extractions; send {} or concrete values to opt every page extraction into explicit mode. Returns a job ID that can be polled with the 'crawl_status' tool. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| crawl_request | Yes |
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.
Retrieve the status and results of a crawl job by its job ID. Returns the current status (queued, running, completed, or failed), page counts, and once completed, the crawled page results with extracted content. Results are paginated; use 'page' and 'page_size' to navigate. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| job_id | Yes | ||
| api_key | No | ||
| page_size | No |
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.
Extract content from a web page. Supports HTML and Markdown output formats, optional JavaScript rendering via headless browser, proxy geo-targeting, custom HTTP headers, and explicit browser wait controls via the wait_config object. Can run synchronously (returns content immediately) or asynchronously (returns a job ID that can be polled with the 'job' tool). Use 'render_js=true' for pages that require JavaScript to load their content; supplying wait_config also enables browser rendering automatically. Omit wait_config or set it to null to keep the adaptive browser settle path; send {} or concrete values to opt into explicit mode. Without an API key, extraction is synchronous only, without JavaScript rendering or request headers other than Accept-Language, and limited to a small per-client rate and daily volume. An API key, sent as the X-Api-Key header, lifts these restrictions; the plan's own limits apply instead.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| extract_request | Yes |
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.
Retrieve the result of an asynchronous extraction job by its job ID. Returns the current status (pending, running, completed, or failed) and, once completed, the extracted content and metadata. Use this tool to poll for results after submitting an extraction with processing_mode='async'. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| api_key | No |
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.
List extraction jobs with optional filters. Filter by full job ID (exact match), status (pending, running, completed, failed), output format, or date range. Results are paginated; use 'page' and 'page_size' to navigate large result sets. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| job_id | No | ||
| output | No | ||
| api_key | No | ||
| end_date | No | ||
| page_size | No | ||
| job_status | No | ||
| start_date | No |
Discover all URLs under a base URL by combining sitemap parsing with HTML link extraction from the seed page. By default discovery is scoped to the exact seed host (a leading 'www.' is treated as equivalent) and, when the URL includes a path, to URLs under that path; sibling subdomains and outbound links are excluded. Set include_subdomains=true to widen the scope to the whole registrable domain and probe common subdomains (docs, blog, help, support). The optional 'search' parameter filters the discovered URLs by case-insensitive substring match — it does NOT query a search engine. Runs synchronously and returns the discovered links immediately. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| map_request | Yes |
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.
Retrieve the full details and discovered links for a map job by its job ID. Returns the current status and, once completed, the discovered links and their source. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| api_key | No |
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.
List map jobs for the authenticated user with optional filters. Filter by status (pending, running, completed, failed) or date range. Results are paginated; use 'page' and 'page_size' to navigate. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| api_key | No | ||
| end_date | No | ||
| page_size | No | ||
| job_status | No | ||
| start_date | No |
Run a web search and return ranked results. Supports locale targeting (a language code like 'en', a language-region tag like 'en-US', or 'all'), pagination via 'page', safe-search filtering, and restricting results to a recency window via 'time_range'. By default the service rotates across its engines and falls back on failure; set 'engine' to pin one engine with no fallback. Returns the result list, the engine that served it, query suggestions, and any spelling correction. An empty result list means the engine answered and found nothing; such a search is not charged. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| search_request | Yes |
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.
Retrieve the full details and results for a search job by its job ID. Returns the current status and, once completed, the search results, suggestions, and any spelling correction applied. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| api_key | No |
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.
List search jobs for the authenticated user with optional filters. Filter by status (pending, running, completed, failed) or date range. Results are paginated; use 'page' and 'page_size' to navigate. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| api_key | No | ||
| end_date | No | ||
| page_size | No | ||
| job_status | No | ||
| start_date | No |
Retrieve aggregated extraction statistics for the authenticated user. Returns metrics such as total jobs, success and failure counts, and usage breakdowns over the specified date range: at most 366 days, counted back from the end date (an older start date is moved up; an end date after now is moved back to now). Defaults to the last 30 days when no dates are provided. Requires a Geonode API key, sent as the X-Api-Key header.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | ||
| end_date | No | ||
| start_date | No |
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
jobs2 fields changedInput schema / properties / job_id / anyOfPrevious value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "format": "uuid",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / urlRemoved value: -{
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Url"
-}map_jobs1 field changedInput schema / properties / urlRemoved value: -{
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Url"
-}search_jobs1 field changedInput schema / properties / queryRemoved value: -{
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "title": "Query"
-}batchbatch_statuscancel_batchcancel_crawlcrawlcrawl_statusjobjobsmapmap_jobmap_jobssearchsearch_jobsearch_jobsstatisticsextractExtract public webpages as Markdown, map sites, and run bounded crawl jobs. API key required.
Markdown scrape, site map, page metadata, screenshots, web search and PDF to text. Pay per call
Web search, read any page, verify or find emails, screenshots, keyword data. One key, pay per call.
32 tools: web pages, JS apps and PDFs as text, feeds, sitemaps, search. 25 free calls.
Add one secure layer between your agents and this server.