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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond those annotations: the tool returns immediately with a batchId instead of waiting, processes each URL independently, has a 10-15 second polling cadence, costs 2 credits per URL, and refunds unprocessed items on cancellation. This gives the agent important operational expectations.

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 about 120 words, front-loaded with the core behavior, followed by a 'Best for' section and a short workflow. Every sentence contributes actionable information—scope, async behavior, polling cadence, costs, and cancellation—so conciseness is excellent without sacrificing substance.

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?

Given the tool's complexity (9 parameters, async batch processing, no output schema), the description covers the full operational loop: how to invoke, immediate return, polling until terminal state, avoidance of resubmission, cost implications, retries/cancellation, and distinction from sibling tools. This is sufficient for an agent to use the tool correctly without additional documentation.

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 56%, so the schema carries a moderate amount of parameter meaning. The description reinforces URL count limits, the need for a unified prompt/schema per URL, and that omitting prompt yields raw markdown. However, it does not add clarity for undocumented parameters like output, cookies, scrapeMode, or extractContentOnly, leaving those gaps unresolved.

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?

Description states a specific verb ('Scrape'), a concrete resource ('a list of 2-50 known URLs'), and the processing model (each URL independently with its own result). It also explicitly distinguishes itself from spidra_scrape, making the tool's purpose unmistakable compared to siblings.

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 provides explicit 'Best for' scenarios, contrasts with spidra_scrape, and gives a clear workflow: call the tool, get a batchId, poll spidra_check_batch_status every 10-15 seconds until terminal state, and do not resubmit while pending. It also mentions spidra_cancel_batch for failures, offering concrete alternative usage.

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

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

The description goes beyond the destructiveHint annotation by explaining the consequences: refunds for unprocessed items and preservation of finished results. This adds valuable behavioral context not available in structured data. It does not contradict 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 concise (two sentences) and front-loaded with the main action. Every sentence adds value, with no unnecessary words 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?

Given the tool's simplicity (one parameter, no output schema), the description covers the key behavioral aspects: what it cancels, refund behavior, and item preservation. It is sufficiently complete for an agent to invoke correctly, though it does not describe potential errors or return values.

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 schema has one parameter (batchId) with 0% description coverage, and the description does not explain what batchId refers to or where to obtain it. The parameter semantics are under-specified, although the name 'batchId' is self-explanatory, it lacks guidance on its provenance or validation.

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 clearly states the action ('Cancel') and the resource ('a pending or running batch scrape'), distinguishing it from sibling tools like spidra_cancel_crawl by specifying scrape type. It also mentions outcome details (credits refunded, finished items kept), making the purpose 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?

The description provides clear context for when to use: canceling a batch scrape that is pending or running. It does not explicitly name alternatives or exclusions, but it is evident that this tool is for batch cancels, not crawls or individual scrapes. Lacks explicit when-not guidance.

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 this as destructive (destructiveHint=true). The description adds valuable behavioral context beyond that: partial preservation of processed pages (retrievable via spidra_crawl_pages) and credit refunds for unprocessed pages. This helps the agent understand the consequences. No contradiction with 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 compact and front-loaded with the core action. It consists of two sentences, each contributing meaningful information (what is canceled and the consequences). No fluff 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?

The tool is simple—one parameter, no output schema. The description explains the immediate effect (cancellation), the state of processed pages, and the refund policy. It does not describe the response format, but that is not critical for a cancel action. It could mention edge cases (e.g., canceling a completed job), but that is a minor gap.

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 schema has one required parameter, jobId, with 0% description coverage. The description does not elaborate on the format or source of jobId beyond its name. However, the context of 'cancel a crawl job' makes it clear the parameter identifies the job. Since the description adds minimal meaning beyond the schema, a 3 is appropriate.

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 clearly states the tool cancels a crawl job, using a specific verb ('Cancel') and resource ('crawl job'), and qualifies the state ('queued or running'), distinguishing it from sibling tools like spidra_check_crawl_status or spidra_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?

It explicitly says when to use the tool: for queued or running crawl jobs. This implies it is not for canceled or completed jobs, and not for batch jobs (which have their own cancel tool). It does not explicitly name alternatives, but the context makes the usage clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral detail: returns per-URL statuses, defines terminal vs in-progress states, and warns that completed batches can still contain failed items—key nuances for interpreting the result.

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 sentences with no fluff. It front-loads the purpose, then efficiently explains status categories and an important exception. Every sentence 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?

For a simple read-only tool with one required parameter and no output schema, the description fully covers what the agent needs: status meaning, return contents, and a critical edge case. It is self-contained and actionable without being verbose.

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 parameter description already explains batchId is returned by spidra_batch_scrape. The tool description adds no new parameter-level meaning beyond restating that connection, so it aligns with the baseline for well-covered 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?

Description clearly states 'Check the status of a batch scrape by batchId', identifying the specific verb-resource pair. It distinguishes from sibling spidra_check_scrape_status by explicitly saying 'batch' and detailing what it returns (per-URL statuses, results).

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?

Provides clear usage context by tying batchId to spidra_batch_scrape and explaining status semantics (in-progress vs terminal). It does not explicitly name alternatives or exclusions, but the singular purpose and batch-specific language implicitly guide correct selection.

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 readOnlyHint annotation, the description adds valuable behavioral detail: it explains that running jobs return progress (pagesCrawled/maxPages) and completed jobs return extracted data. It also categorizes job statuses into in-progress and terminal, which is helpful 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 description is three sentences long, with the main purpose in the first sentence and relevant details about return values and statuses in the following sentences. There is no redundant or extraneous content.

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?

Given the simplicity of the tool (one parameter, read-only) and the absence of an output schema, the description adequately explains what the caller can expect: progress for running jobs, extracted data for completed jobs, and the meaning of each status. It is complete for its purpose.

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 schema already provides full coverage for the single parameter with the description 'The crawl job id returned by spidra_crawl.' The tool description only reiterates that it is checked by jobId, adding no new semantic information beyond what the schema states.

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 clearly states the tool's function: 'Check the status of a crawl job by jobId.' It distinguishes itself from sibling tools by focusing specifically on crawl jobs and by describing the returned data based on job 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 clearly indicates this is for checking crawl job status, and the parameter description specifies the jobId comes from spidra_crawl. It does not explicitly name alternatives like check_scrape_status, but the context is clear and unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by explaining what the job statuses mean (in-progress vs terminal), which goes beyond the annotations. No contradiction exists.

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 two sentences, front-loaded with the core purpose, and every word adds value. It is concise without being under-specified.

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 status-check tool with one parameter and no output schema, the description provides the trigger condition and lists status categories, which is sufficient for an agent to understand the tool's role and expected result. It could optionally describe the return format, but the status list implies it.

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% for the single parameter jobId, with a description 'The scrape job id' in the schema itself. The tool description adds nothing semantically beyond repeating 'by jobId', so the baseline 3 is appropriate.

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 clearly states the tool checks the status of a scrape job by jobId, using a specific verb and resource. It distinguishes itself from sibling tools like spidra_check_batch_status and spidra_check_crawl_status by explicitly targeting 'scrape job' 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 gives an explicit condition: 'Only needed when spidra_scrape reported that its wait window was exceeded.' This provides clear when-to-use context, but it does not name alternatives like spidra_check_batch_status, so it falls short of a full 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?

Beyond the annotations (readOnlyHint, openWorldHint, destructiveHint), the description discloses that the tool returns immediately with a jobId and runs asynchronously. It warns not to resubmit while pending, explains the cost implications of maxPages, and details how crawlInstruction and transformInstruction affect link-following and extraction. These are valuable behavioral details not present in 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 well-structured with a clear opening sentence, then 'Best for', 'Not for', workflow, behavior notes, and a usage example. Every section contributes useful information; there is no repetition of schema details or fluff. It is appropriately detailed for a complex async tool, and front-loads the most important 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?

The description covers the tool's purpose, async behavior, workflow, cost implications, and key parameters, and provides an example. While it doesn't explain every optional parameter or the exact return format, the schema covers most parameters and the description gives enough context for an agent to select and invoke the tool correctly. The missing output schema is partially compensated by the workflow explanation, but some details about response structure are absent.

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?

While the schema already documents 71% of parameters, the description adds important semantics for the two central instruction parameters (crawlInstruction, transformInstruction) and maxPages, clarifying defaults and cost. It also provides a concrete usage example that shows how to combine parameters. This goes beyond the schema's basic descriptions, though it doesn't explain every optional parameter in depth.

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 clearly defines the tool: it crawls a website from a starting URL, follows links based on a crawlInstruction, and optionally extracts structured data. It also distinguishes itself from related tools by stating what it is 'Not for' and naming alternatives like spidra_scrape and spidra_batch_scrape. This goes beyond a simple restatement, giving a specific verb and resource.

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 explicitly provides 'Best for' and 'Not for' scenarios, naming spidra_scrape and spidra_batch_scrape as cheaper alternatives when URLs are known. It also outlines the required workflow, including polling with spidra_check_crawl_status and canceling with spidra_cancel_crawl. This is model guidance that clearly tells the agent when to use this tool and when to pick a sibling tool.

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 readOnlyHint and destructiveHint annotations, the description adds key context: no pages are re-crawled, only AI token credits are charged, a new jobId is returned immediately, and the source crawl must be completed. This gives the agent a clear model of the tool's behavior and cost implications.

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 focused sentences with no filler. The main action is front-loaded, followed by cost-saving rationale and immediately actionable usage details (polling, precondition). Every sentence contributes value.

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 job-creation tool, the description covers the use case, cost, return behavior, polling workflow, and a required precondition. With good annotations and full schema coverage, no significant information is missing for an agent to decide and invoke 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?

The input schema already provides 100% coverage with descriptions for both jobId and transformInstruction. The description does not add additional parameter-specific details, so it meets the baseline for schema-covered parameters but does not enhance understanding of parameter formats or constraints.

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 clearly states the tool runs a new extraction prompt over an already-completed crawl without re-crawling pages. It distinguishes itself from crawling tools by emphasizing the reuse of completed crawls, and from status tools by being an action that returns a jobId.

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 explicitly conditions usage on the source crawl being 'completed' and positions it as a cheaper alternative to crawling again. It also directs the caller to poll spidra_check_crawl_status with the returned jobId, though it does not name alternative tools for other scenarios.

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

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

The description adds valuable behavioral details beyond the readOnlyHint annotation: links expire after 1 hour, and cancelled crawls return partial results. This informs the user of time-sensitive URLs and the tool's behavior on incomplete crawls, which the annotations alone do not 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?

The description is two sentences, front-loaded with the primary purpose, and contains no filler. Every clause adds useful information: per-page results, signed URLs, expiry, and cancellation 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?

Given the tool's simplicity (single parameter, no output schema), the description covers essential aspects: output type, URL expiry, and behavior on cancelled crawls. It is complete enough for an agent to select and invoke the tool 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?

The input schema has only one parameter, jobId, with no description (0% coverage). The description does not explicitly explain jobId, but the tool name and the phrase 'for a crawl' imply it is the crawl job identifier. While self-explanatory, the description adds no explicit parameter semantics beyond the parameter name.

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 clearly states the tool's function: 'Get per-page results for a crawl' with specifics about signed download URLs for raw HTML and markdown. It also distinguishes itself from sibling tools like spidra_check_crawl_status by focusing on page-level output rather than 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 provides clear context for when the tool is applicable: 'Works on completed crawls and on cancelled crawls (returns the pages processed before cancellation).' It implicitly guides the user away from using it on active crawls, though it does not explicitly name alternative tools.

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 readOnly/destructive annotations, the description discloses the synchronous wait behavior, timeout fallback with spidra_check_scrape_status, credit costs, CAPTCHA costs, and the combined-answer behavior. No contradiction with annotations; it adds substantial 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 description is fairly long but well-structured with headers and bullets. A few points restate schema descriptions (e.g., untyped schema warning), but the example and prioritization earn their place. Slightly tighter would be perfect.

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 explains returns (content + stats) and timeout behavior. It covers costs, alternatives, usage example, and edge cases like CAPTCHA and proxy. This is a complete guide for agent invocation.

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 schema coverage is 100%, the description adds essential meaning: omitting prompt/schema yields raw markdown, untyped objects come back empty, and the relationship between prompt and schema is clarified. The usage example demonstrates correct argument structure.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: "Scrape 1-3 known URLs and extract their content with AI." It clearly distinguishes from siblings by explaining that multiple URLs produce a combined answer, while independent per-URL extraction belongs to spidra_batch_scrape.

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?

Explicit "Best for" and "Not for" sections name alternatives (spidra_batch_scrape, spidra_crawl). It also gives conditional guidance for actions, proxy, and schema usage, telling the agent when each parameter is appropriate.

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 disclose read-only and non-destructive behavior. The description adds meaningful context beyond annotations: the distinction between listing logs (summaries) versus fetching a single log's full AI output, plus the account scoping and key-usage insight. This enriches the behavioral model without contradicting 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?

Three short, front-loaded sentences: the first states the primary action, the second gives use cases, and the third explains a key parameter mode. Every sentence adds value, with no redundancy or 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?

Given the tool's complexity (5 optional params, no output schema) and strong annotations, the description sufficiently covers purpose, usage, and the uuid behavior. It lacks a description of the returned log format, but overall the agent can infer basic behavior. The gap is minor, so it earns a 4 rather than a 5.

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 60%, partially compensating for parameter details. The description explicitly explains the uuid parameter's special behavior (fetch full output) and mentions 'optional filters,' but leaves page and status without dedicated explanation. The schema and description together cover most semantics, but the generic 'filters' phrase does not fully eludicate all parameters.

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 'List past scrape jobs for this account with optional filters,' which uses a specific verb ('list'), identifies the resource ('scrape jobs'), and scopes it to the account. It also distinguishes a second mode ('Fetch a single log's full AI output') and clearly separates this from siblings like status checkers and scraping 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?

The description provides explicit use cases: 'finding a previous job's result, debugging failures, or checking what a key has been used for.' This gives clear context for when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds meaningful context beyond annotations by specifying the scope ('this account's'), the nature of usage (request/credit/token), and the breakdown granularity (day/week). It doesn't disclose return format or limits, but with annotations covering the safety profile, this is sufficient.

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 two sentences, front-loaded with the core purpose and then a clear use-case statement. Every sentence earns its place; no filler or unnecessary detail. It is exceptionally concise while remaining informative.

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 tool with one optional parameter, no output schema, and no nested objects, the description covers the what, when, and scope. It lacks an explicit description of return format, but without an output schema, the burden is moderate. The use-case framing ('remaining headroom') adds practical context, making this adequately complete for an agent to invoke 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 100%, with the single 'range' parameter fully documented in the schema (enum and default). The description adds no additional parameter-specific meaning beyond repeating the day/week granularity already in the enum. Since the schema does the heavy lifting, a baseline score of 3 is appropriate.

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 clearly states the tool's function: 'Get this account's request/credit/token usage broken down by day or week.' The verb 'Get' and resource 'usage' are specific, and the breakdown by day/week adds clear scope. It also distinguishes from sibling tools, which are all scraping/crawling operations.

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 states when to use: 'Use it to answer "how many credits have I used" style questions or to check remaining headroom before a large batch/crawl.' This gives direct usage context and implicitly separates it from the scraping/crawling siblings, making the intended invocation clear.

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