Octocrawl

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

Adds substantial context beyond annotations: hosted jobs run in slices, 500-page crawl vs 1,000-URL batch limits, per-page credit cost with maxCredits cap, and 7-day retention. It also flags that invalid URL entries are skipped when ignoreInvalidURLs is set, which matters for a non-destructive but billable 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?

Front-loads purpose and return value in the first sentence, then follow-up tools, then pricing/retention caveats. Dense but every sentence carries information; the long parenthetical about formats is the only mildly crowded passage.

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?

Covers start-of-job semantics, the async continuation path, credit and retention constraints, and idempotency safety. With an output schema present, the description need not detail result payloads, and it correctly spends its space on job-level behavior instead.

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?

With only 38% schema coverage over 21 parameters, the description compensates well: it names formats, onlyMainContent, includeTags, waitFor, timeout, verify, maxCredits and idempotencyKey, and delegates the rest to scrape's parameter docs. Undocumented booleans like fastMode, blockAds and removeBase64Images are still left to inference.

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 scope: 'Run 1-1000 known URLs as one persistent job' and names the immediate return ({ taskId }). The 'known URLs' framing implicitly separates it from crawl, which discovers URLs.

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 routes the agent through the lifecycle siblings: wait_batch waits, get_batch_items pages results, get_batch_errors lists failures. It does not explicitly contrast with crawl or scrape for choosing between tools, which keeps it below 5.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description does add one genuinely non-obvious fact beyond them: items already read remain readable after cancellation, implying partial results survive. It says nothing about in-flight items, error/partial-failure behavior, or permissions, so a 3 is warranted.

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 front-loaded sentence with two clauses, both of which carry information (the handle and the post-cancel state). No filler or preamble, though it is terse enough to leave the reader wanting more on usage.

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 one-parameter mutation tool with annotations covering safety and no output schema, the essentials are present, and the note about surviving items is helpful. It still leaves open what happens if the batch already finished and whether cancellation is immediate, which idempotentHint only partially covers.

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% and the single parameter is named "id" with no schema description, so the description carries the burden. It does clarify that the id is the batch's taskId, which adds real meaning, but gives no format, source, or example of where to obtain it.

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 ("Cancel a batch") and identifies the required handle as a taskId, so the agent knows exactly what operation this is. It does not explicitly differentiate itself from sibling cancellers like cancel_crawl or cancel_monitor_run, but the resource noun makes the target 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?

No guidance on when to cancel versus alternatives such as wait_batch, get_batch, or hand_off_batch is given. The agent must infer that this is the abort path for an in-progress batch, and no preconditions or exclusions are stated.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context beyond the annotations: 'Completed pages remain queryable,' telling the agent that cancel is non-rollback and already-scraped data persists. It stops short of explaining whether a cancelled crawl can be resumed via resume_crawl.

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 short sentences, zero waste, with the action and the key post-condition front-loaded. Nothing redundant or padded.

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 single-parameter mutation with no output schema, the description is adequate on what happens to existing data but omits parameter sourcing and resumability behavior. An agent can call it, yet its required argument and follow-up options remain underspecified.

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% and the single parameter 'id' is undocumented in both schema and description. The description never states whether the id refers to a crawl task id and where to obtain it (e.g., from crawl or list_active_crawls), leaving the required identifier semantics unexplained.

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+resource ('Cancel a crawl task'), which is unambiguous about the operation. It does not, however, distinguish this from sibling cancel-style tools (cancel_batch, cancel_monitor_run) or clarify what 'a crawl task' means relative to get_crawl/resume_crawl.

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?

There is no guidance on when to cancel versus alternatives such as resume_crawl or simply letting the crawl finish, nor any preconditions (e.g., must the crawl be running). The agent is left to infer all usage context.

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 only cover safety and openness; the description adds substantive behavior they cannot carry: slice limits (500 pages per crawl, 1,000 URLs per batch), per-page credit cost against maxCredits, 7-day result retention, and that collapsed/refused links are still counted in discovery. That is exactly the async-job context an agent needs before starting a paid 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?

Front-loaded with the crawl scope and return value, then limits and costs — good ordering with almost no filler. Some sentences pack several distinct facts ('Similar URLs fold into one page, and every collapsed or refused link is counted in get_crawl's discovery') and would read better split.

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 32-parameter asynchronous job tool, it covers the return shape, the follow-up tools, cost and cap behavior, dedup semantics and retention. The output schema carries the result structure, so the description only needs to explain the task lifecycle, which it does.

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?

With 32 params at 56% schema coverage, the description earns credit for stating the maxPages default of 100, the maxDepth link-traversal meaning, and for delegating the page-level options to scrape's documented parameters rather than restating them. It leaves the traversal-policy cluster (allowExternalLinks vs allowlistedDomains, crawlEntireDomain, allowSubdomains) to the schema, which is a real but moderate gap.

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 plus crawl scope: 'follow links in the start path's subtree on its host and www twin'. That scope statement alone separates it from scrape (single page) and map (URL discovery) without needing their schemas.

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 lays out the full pipeline — this returns { taskId }, then wait_crawl, then get_crawl_pages — which tells the agent exactly what to call next. It stops short of an explicit exclusion ('use scrape for a single page, map for URL lists only'), so the when-not case is inferred rather than stated.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds that the read returns state, item counts and the items awaiting a person, which is useful operational context, but says nothing about polling behavior, freshness, or what happens for an unknown/expired id.

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 sentence that front-loads the verb and resource and then enumerates the returned fields; no filler or redundancy.

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?

An output schema exists, so return values need not be spelled out, and the annotations carry the safety profile. The definition is nearly complete for a simple read tool, with the only gap being how to obtain the taskId and when to poll versus using wait_batch.

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% and the lone parameter is the opaque name 'id'; the description supplies the key semantic that this id is a taskId, which the schema does not. It stops short of giving the id's format or where it comes from (e.g. the value returned by batch_scrape).

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 (Read) and resource (a batch's status), and names the salient return fields (state, item counts, waitingForPerson items). It distinguishes itself from the more generic crawl/scrape siblings, though it does not explicitly contrast with the closest ones like get_batch_items and wait_batch.

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?

There is no when-to-use guidance and no mention of alternatives, despite siblings wait_batch, get_batch_items and get_batch_errors that an agent could confuse it with. Usage is only weakly implied by 'read a batch's status'.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes further by disclosing the return shape ({ items, nextCursor, hasMore }), the page size limit of 100, and the blockReason semantics for robots.txt-refused URLs, adding genuine behavioral context.

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 sentence, front-loaded with purpose before qualifications. Efficiently packs statuses, return shape, pagination, and edge-case behavior, though the run-on structure slightly reduces readability.

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 correctly supplies the return shape and pagination envelope, plus the non-obvious status enumeration that defines what an 'error' is. Minor residual gaps remain around the id parameter and debug semantics.

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 only 25% (only 'debug' is documented in the schema), so the description must compensate. It clarifies cursor and limit semantics ('in pages of up to 100 (cursor, limit)'), but leaves 'id' and the debug flag unexplained, so compensation is partial.

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 a batch's items') and explicitly scopes it to non-success statuses (failed, blocked, cancelled, budget_exceeded). It also names the sibling it mirrors with identical output shape ('as get_batch_items lists it'), letting an agent distinguish it from get_batch_items and get_batch without opening a 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?

The status filter clearly implies when this tool is appropriate versus get_batch_items (all items), giving strong context for selection. However, it never explicitly says 'use this instead of get_batch_items when...' nor names an exclusion condition, so it falls short of fully explicit routing.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuine behavioral context beyond them: that maxResults switches the tool into a self-cursor-following mode that pages internally at most 50 at a time and returns a summary envelope. It does not explain 'stoppedBy' or any rate/consistency traits.

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 sentence with no filler; the primary paging behavior and the maxResults variant are both front-loaded, and the parentheticals carry real information rather than restating the name.

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?

An output schema exists, so the return envelope need not be explained, and the description still names its fields. The remaining gap is around operational preconditions (batch state, whether items are only available after completion) and the meaning of stoppedBy, which leaves the agent guessing for a 5-parameter tool.

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 only 20%, so the description must compensate, and it largely does: id is identified as the batch taskId, limit is bounded at 50, cursor is explained as the paging position, and maxResults is described as auto-following cursors. Only 'debug' is left entirely undocumented in both places.

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: paging through a batch's results, keyed by taskId, with explicit cursor/limit semantics. It is distinguishable from get_batch (metadata) and get_batch_errors in the sibling list, though it never names those siblings to disambiguate directly.

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 guides the choice between two invocation modes (manual cursor paging vs. maxResults auto-follow), which is real usage guidance. However it gives no guidance on when to use this tool rather than get_batch, wait_batch, or get_batch_errors, and no prerequisites (e.g. whether the batch must be finished).

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, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description usefully adds what the payload contains (page counts, collapsed/refused link counters), but says nothing about polling behavior or what an in-progress status looks like.

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?

One compact sentence that front-loads the verb, resource, and key. The trailing clause about discovery counters is slightly jargon-dense but still earns its place by telling the agent what data comes back.

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 an output schema present, return values need not be explained, yet the description still previews the payload shape. For a single-parameter read tool this is nearly sufficient; only the relationship to wait_crawl/get_crawl_pages is left ambiguous.

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 100% and the single parameter is already documented as 'taskId from crawl'; the description's 'by its taskId' merely restates it. No extra syntax, format, or sourcing detail is added.

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 (Read) and resource (a crawl's report) keyed by taskId, and enumerates the report contents (status, page counts, discovery counters). It implicitly separates itself from get_crawl_pages/get_crawl_errors by naming the aggregate report, though it never names those siblings explicitly.

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 — an agent can infer this is the polling/status lookup for a crawl, but there is no guidance on when to call it versus wait_crawl, get_crawl_pages, or get_crawl_errors, and no stated prerequisites beyond the taskId.

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, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds that results are paginated, which is useful context beyond the annotations, but it says nothing about error entry shape, retention, or how paging interacts with attempts.

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 front-loaded sentence with no filler; the verb and scope come first. It is efficient, though arguably undersized for a five-parameter paginated tool.

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 five parameters, 20% schema coverage, and no output schema, the description should explain cursor-based paging and the attemptId/debug options. It mentions pagination but not how to page or what is returned, leaving material gaps for an agent to call 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 only 20%, so the description carries most of the burden. It clarifies that the required 'id' is a task id, but says nothing about 'cursor', 'limit', 'attemptId' or 'debug', leaving four of five parameters undocumented in both the schema and the description.

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 ('read/list'), resource ('crawl errors') and scope ('by task id'), which cleanly separates it from get_crawl, get_crawl_pages and get_batch_errors. It does not explicitly name a sibling alternative, but the resource 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?

There is no guidance on when to use this instead of get_crawl, get_crawl_pages, or get_batch_errors, nor any stated preconditions (e.g. crawl must be finished). Usage is only implied by the resource noun.

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 cover the read-only/idempotent/non-destructive profile, so the bar is lower. The description adds genuine behavioral context beyond annotations: default omission of routing audit and trace, omission of status-duplicate pages, and self-following cursor behavior bounded by maxResults. It stops short of disclosing auth or rate-limit characteristics.

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?

Dense but efficient, packed into essentially one long sentence with the core purpose front-loaded. No filler, though the single-sentence form makes it slightly harder to scan than a lightly structured version would be.

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?

An output schema exists, so return values need not be detailed, yet the description still names the shape ({ items, nextCursor, hasMore, stoppedBy }), which is helpful. With annotations covering safety and the description covering filtering behavior, an agent has enough to call 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 only 29%, so the description must carry weight and largely does: it clarifies id (task id), attemptId, debug, includeDuplicates, and maxResults semantics. Only limit and cursor get little to no narrative treatment (cursor is partly implied by 'follows cursors').

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: 'Read a paginated list of crawl page results by task id.' The scope (task id, latest attempt) is precise. It does not explicitly contrast with siblings like get_crawl or get_crawl_errors, but the operation itself 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?

Explains when certain parameters apply (attemptId for non-latest attempts, debug to include audit/trace, includeDuplicates for repeated pages, maxResults for cursor-following), which implies usage. However, there is no explicit guidance on when to choose this tool over get_crawl or get_crawl_errors, nor any when-not conditions.

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 cover readOnly/idempotent/destructive, so the description's added value is the payload scope (no page body) and the 10-minute retention window, both genuinely useful. It does not say what happens when the record has expired, which is the remaining behavioral gap.

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?

One dense sentence plus a two-word retention clause; the identifier source is front-loaded and every element earns its place.

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?

An output schema exists, so return values need no prose; the description still summarizes the payload and flags the retention limit. Nothing an agent needs to invoke it correctly 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 coverage is 100% and the single parameter's description ('metadata.scrapeId of a scrape response') is mirrored nearly verbatim in the description. No extra syntax or edge-case meaning is added beyond the schema, so baseline 3 applies.

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 (read) and resource (one scrape call's record), enumerates exactly what is returned (request, verdict, metadata, warnings, hints) and what is not (no page body). This clearly separates it from the sibling scrape tool that performs the call.

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?

Tells the agent the precondition and the key input: use the metadata.scrapeId found on a scrape response. The 'Kept 10 minutes' clause signals the time window in which retrieval is valid. It stops short of naming alternatives or exclusions explicitly, so not a 5.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds useful behavioral context beyond that: results are ordered oldest first, each entry includes id/start URL/status/pages, and an empty list is returned when no active crawls exist.

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?

It is a single tight sentence with no wasted words. The active-filter scope and ordering are front-loaded before the returned fields and empty-case behavior.

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 zero-parameter list tool with no output schema, the description gives enough: scope, ordering, returned fields, and empty-result behavior. Nothing essential for correct invocation 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?

There are zero parameters, so parameter semantics carry the baseline score of 4. The description does not need to explain any inputs.

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 ('List this account's crawls') and narrows scope to 'queued or running, oldest first,' which clearly separates it from siblings like get_crawl or wait_crawl. It also names the returned fields, so an agent can identify the tool without inspecting 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?

The 'queued or running' phrasing implies this is for in-progress crawls, but it never explicitly says when to use this versus get_crawl, wait_crawl, or cancel_crawl. The usage context is inferable but not directly stated.

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/idempotent/non-destructive, and the description adds substantial behavior beyond them: robots.txt compliance and its override, URL scope rules (host, www twin, subtree, assets excluded, folding), the deadline/partial-result contract (stoppedBy timeout), no title fetching, and compact-vs-debug output modes. This is rich, non-obvious context.

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 core purpose and scope lead the paragraph and every clause carries information about behavior, but it is extremely dense and parenthetical, which taxes readability. Efficient rather than padded, though a structural break would help.

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 15-parameter, open-world crawler with an output schema already present, the description covers everything an agent needs to call correctly: scope, robots handling, deadline semantics, partial-result behavior, and output verbosity. Return-value detail is properly left to the output 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?

Schema coverage is 100%, so the baseline is 3, but the description reinforces and clarifies semantics: it defines what mode governs (the declared identity), what happens at limit/timeout (status completed, stoppedBy), and folding/counting behavior (refused.collapsed, deduplicateSimilarURLs). It adds value beyond the schema text rather than merely restating it.

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+resource combo up front: 'List a site's URLs without reading each page.' It also scopes exactly what is listed (start page's links over HTTP plus declared sitemap entries) and names the boundary against its sibling with 'Not for: reading pages.' An agent can distinguish this from scrape 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?

The description gives a clear negative use case ('Not for: reading pages, as one page body is read at most') which directly routes to scrape, plus scope conditions (robots.txt applies unless ignoreRobotsTxt is set). It lacks an explicit 'use this when you need X' positive trigger, but the exclusion is strong and actionable.

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, it discloses the HTTP-first then browser fallback, the Evidence Record contents, compact versus debug output, warning codes such as client_rendered_suspected and robots_overridden, agentHints, and metadata.scrapeId for follow-up via get_scrape. These are substantive behavioral details not captured by 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 dense and front-loaded: core action, scope exclusion, output shape, then key response metadata. Every sentence adds useful routing or behavioral information without boilerplate.

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 complex 19-parameter tool with an output schema and rich schema descriptions, the description supplies the essential scope, fallback behavior, warnings, hints, and follow-up identifier. It does not need to restate the full parameter or return 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?

Schema description coverage is 95%, so the schema already carries most parameter semantics. The description reinforces a few behaviors such as compact output, debug audit, and scrapeId, but it does not add much detail beyond the already rich schema.

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: 'Read one URL as Markdown.' It also names the returned Evidence Record and explicitly scopes the tool to a single URL, distinguishing it from multi-URL or site-section tools.

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 'Not for: many URLs or a whole site section,' which gives the agent a strong when-not condition. The relevant alternatives such as batch_scrape or crawl are implied but not explicitly named, keeping this just short of a full routing statement.

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, idempotent, openWorld and non-destructive. The description adds useful extra context by noting access is anonymous (no login needed) and that no schema/model setup is required, but it says nothing about rate limits, throttling, or failure behavior for invalid URLs.

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 short sentences, front-loaded with the core action and scope. The trailing 'No schema or model setup needed' is mildly promotional but still informative about setup cost.

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 single-URL scrape tool this covers the essentials, but with no output schema the description gives only 'JSON' with no hint of the returned fields, and the undocumented debug parameter leaves a gap an agent cannot resolve.

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 partially does by revealing the URL shape (/dp/{ASIN} on amazon.sg), but the optional 'debug' parameter is never explained in either schema or description.

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: fetch JSON for one anonymous Amazon.sg /dp/{ASIN} product. The 'one product' scope implicitly separates it from batch_products and the generic scrape sibling, though it does not name them.

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?

There is no explicit when-to-use / when-not-to-use guidance and no named alternative. A reader must infer that this is the single-product path versus batch_products or the generic scrape tool based on the word 'one'.

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, idempotent, and non-destructive behavior. The description adds useful behavioral detail: the default and maximum timeout, and that a timeout returns the status so far rather than failing.

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 a single well-packed sentence with no wasted words. Purpose, timeout behavior, and the follow-up action are front-loaded and easy to parse.

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?

An output schema exists, so return shape need not be described. The description covers the key waiting behavior, timeout limits, and what to do after a timeout, though it could clarify the id parameter and get_batch distinction.

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 documents timeoutMs default and maximum, but does not explain the required id parameter beyond implying it identifies the batch.

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: wait for a batch to finish and return its status. It clearly distinguishes waiting from reading batch items at timeout, though it does not explicitly contrast with the immediate-status sibling get_batch.

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 clear usage context by saying to wait again or read get_batch_items if the timeout is reached. It does not explicitly say when to use wait_batch rather than get_batch for immediate status checks.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: the default timeout (30000), the maximum (120000), and that a timeout is not an error but a partial-report return. It doesn't say how long a call may block relative to the requested timeout or whether partial reports are marked, which keeps it below a 5.

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 sentence, front-loaded with the action and bound, followed by the timeout consequence and the recovery path. No filler and no repetition of the title or annotations.

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 an output schema present, the description needn't explain the report contents, and it covers timeout semantics, bounds, and the fallback path. The only remaining gap is the relationship to get_crawl (the non-blocking alternative) for agents deciding between blocking and polling.

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 50%, and the description compensates well for the undocumented timeoutMs by supplying both the default (30000) and the upper bound (120000), which the schema does not state. It says nothing beyond the schema about the required id, but the schema's 'taskId from crawl' already handles 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 (wait), the resource (a crawl), and the outcome (finish and return its report), which lets an agent distinguish it from the polling sibling get_crawl without opening either 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?

The description gives clear operational guidance for the timeout path ('wait again or read get_crawl_pages'), but it never explicitly contrasts with the non-blocking get_crawl sibling or states when blocking is preferred over polling. That leaves the main sibling choice implicit.

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