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

Goes beyond annotations by disclosing the non-idempotency ('calling twice adds the URLs twice'), the CONFLICT failure for closed/finished jobs, and the exact return shape. Annotations already cover idempotentHint=false and openWorldHint, so credit here is for the conflict semantics and return fields.

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 dense sentences with zero filler: purpose, vocabulary constraint, failure condition, idempotency warning, and return shape. The critical non-idempotency warning is front-loaded enough to be caught.

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 the operation's key gotchas (mutual exclusivity, CONFLICT on closed jobs, non-idempotency) despite an output schema existing. An agent has everything needed to invoke correctly and interpret the response.

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 schema carries the parameter burden. The description adds value by flagging the mutual exclusivity of `urls`/`items` and that shared settings apply to new items, but this largely restates what the schema already documents.

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 (append) and resource (URLs to a batch job), and scopes it precisely to jobs submitted with `open: true`, which distinguishes it from spicrawl_batch_submit and other batch 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?

Explicitly names the sibling it shares item vocabulary with (spicrawl_batch_submit) and states the precondition (job must be open) plus failure mode (CONFLICT). Lacks explicit 'when to use this vs spicrawl_batch_retry' guidance, but the open-job scoping is a clear routing signal.

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?

Goes well beyond the annotations (destructiveHint, idempotentHint, readOnlyHint=false) by specifying exactly what is destroyed (items not yet started), what is preserved (finished items keep results), and how in-flight items are handled. It also discloses irreversibility, the 'cancelling' -> 'cancelled' state transition, and the recovery path (resubmit), which annotations cannot express.

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 and packed with high-value behavioral detail in a compact form; no filler sentences. The trailing 'Returns the job object' is mildly redundant given an output schema exists, a minor inefficiency rather than a flaw.

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 tool with full annotation coverage and an output schema, the description supplies everything else an agent needs: scope of destruction, state-machine behavior, irreversibility, and remediation. No meaningful gap remains.

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?

Only one parameter, job_id, and the schema documents it fully (100% coverage, including its provenance from spicrawl_batch_submit/spicrawl_batch_list). The description adds no format, constraint, or edge-case detail about the id, so baseline 3 is appropriate when the schema already carries the parameter contract.

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 job') and immediately scopes the semantics to per-item lifecycle behavior, so an agent knows exactly what operation this is. It never names or contrasts the adjacent spicrawl_batch_close sibling, which is the one plausible confusion, so it falls short of full sibling differentiation.

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 description communicates that this stops a job and that running items must drain, which tells an agent the appropriate operational moment. However there is no explicit when-to-use/when-not, no prerequisites, and no mention of when spicrawl_batch_close or spicrawl_batch_retry would be preferred instead.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description reinforces idempotency with a concrete case ('closing a closed job succeeds'). It also adds the non-obvious asynchronous semantic that the job does not stop immediately but drains its queue, which annotations 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?

Three short sentences, each carrying distinct information: the action, the idempotency guarantee, and the return value. Nothing is padded or restated.

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 with full annotation coverage and an output schema, the description covers behavior, idempotency, and drain semantics adequately. The only gap is not routing the agent between this tool and spicrawl_batch_cancel.

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 job_id parameter is documented with its origin ('returned by spicrawl_batch_submit or spicrawl_batch_list'). The description adds no further parameter meaning, so the baseline of 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?

The description states a precise verb and resource ('Stop an open batch job accepting items') plus the post-condition ('completes once its queued work drains'). This separates it from the sibling spicrawl_batch_cancel, which an agent would otherwise confuse for immediate termination.

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 graceful-drain framing implies the when ('you want the job to finish its queued work rather than abort it'), but no alternative is named outright. The sibling spicrawl_batch_cancel is never mentioned, so the choice between graceful close and hard cancel is left to inference.

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

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

Annotations already declare the safe-read profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real context beyond them: project scoping, newest-first ordering, and the cursor-based pagination contract, which an agent needs to page correctly.

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, front-loaded with purpose and scope, then the return/pagination contract. No filler; every clause 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 explaining return values is optional, yet the description still sketches the shape and pagination loop usefully. It is complete for calling the tool; the only gap is that sibling boundaries (vs batch_status) are not drawn.

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 all three parameters are already documented, including the status enum. The description reinforces the cursor linkage but adds no syntax or meaning beyond what the schema states, 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+resource ('List ... batch jobs') with clear scope (this API key's project) and ordering (newest first). However, it does not differentiate itself from the sibling spicrawl_batch_status, which likely also surfaces job status, so an agent may hesitate between the two.

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 explicit when-to-use versus alternatives is given. The pagination instruction ('pass next_cursor back as cursor') is procedural help, not guidance on selecting this tool over batch_status or batch_results.

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 the read-only/idempotent safety profile; the description goes well beyond them by disclosing that unfinished items are not yet listed, the exact paging contract, the expiry-and-410 behavior, and the large-body result_url fallback. This is exactly the behavioral context annotations cannot express.

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 leads the sentence, followed by pagination and retention details in priority order. Dense but efficient, though the first sentence packs several concepts into a nested parenthetical that could be split for faster scanning.

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?

Output schema exists, yet the description additionally explains the page shape and cursor handoff, plus what happens on expiry and where large bodies live. For a paginated read tool with three inputs, nothing an agent needs in order to call 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 description coverage is 100%, and the description's parameter-level content (cursor round-trip, page size, status filtering via the job's items) is already stated in the schema. It restates the paging loop without adding new syntax or constraints, so the 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 (Return) and resource (a page of FINISHED items of a batch job), and the scope word 'FINISHED' immediately distinguishes it from job-level status siblings and from per-task content fetches. An agent can identify the tool's role 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?

It gives clear operational context: results only appear once items finish, pages are walked by passing next_cursor back as cursor, and results expire (410 Gone). It also points at the result_url path for large bodies rather than the sibling spicrawl_batch_task_content. What's missing is an explicit when-to-use comparison against spicrawl_batch_status or spicrawl_batch_list.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds real value on top: only failed items are re-queued, succeeded items are preserved, and a no-failure job is a no-op. It doesn't discuss re-dispatch semantics for a non-idempotent operation (e.g., duplicate side effects), which would have fully earned 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?

Two tight sentences, front-loaded with the action and its scope, followed by the return shape. Every clause carries information and none is 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?

An output schema exists, so the description needn't detail return values, yet it still names the return fields. The mutation behavior is well covered; only deeper operational detail (auth/session requirements, effect on a currently running job) is 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?

Schema description coverage is 100% and the single job_id parameter is already documented in the schema as coming from spicrawl_batch_submit or spicrawl_batch_list. The description adds nothing about the parameter beyond what the schema states, so the 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 ('Re-queue'), resource ('FAILED item of a batch job'), and scope ('every FAILED item', 'succeeded items untouched'). An agent can distinguish this from spicrawl_batch_submit, spicrawl_batch_cancel, and spicrawl_batch_results without opening any 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?

Gives a clear selection condition implicitly by scoping the operation to jobs with failures and noting a job with no failures returns unchanged. It doesn't explicitly name alternative tools (e.g., resubmit vs cancel) for when retry isn't the right move, so it stops short of full when/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 readOnly/idempotent/non-destructive, so safety is covered; the description adds genuine behavioral context by enumerating the progress counters and credit charging, and by defining which statuses are terminal. It stops short of stating polling cadence, rate limits, or behavior for an unknown/expired job_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?

Two sentences, no filler. The return shape is front-loaded and the lifecycle guidance follows immediately, so the agent gets the essential contract in the first clause.

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 need not explain the payload, and the polling workflow is fully covered. The only unaddressed edge is failure handling for an invalid or expired job_id, which is minor given the read-only, idempotent annotations.

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 job_id parameter is fully documented in the schema, including its provenance. The description adds nothing about the parameter itself, so the baseline 3 for schema-carried semantics 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 and resource ('Return one batch job with its status and progress') and pins the scope to a single job, which cleanly separates it from the list-shaped sibling spicrawl_batch_list. An agent knows exactly what this returns 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?

Gives explicit sequencing: poll this after spicrawl_batch_submit, and once status is completed/failed/cancelled, switch to spicrawl_batch_results. Both the when-to-use and the alternative are named with the condition that selects them.

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 non-read-only, non-idempotent, non-destructive behavior. The description adds genuine context beyond that: the job is asynchronous, it returns a job object, and an open job 'never finishes until you call spicrawl_batch_close' — a lifecycle trap the annotations do not convey. It stops short of stating credit/auth side effects or that concurrent submission of the same URLs will duplicate work.

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 in the first clause, followed by constraints, return shape, routing, and the alternative-tool guidance. Six sentences, each carrying distinct information, with no restatement of the name or 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 20-parameter, nested-object, async submission tool with a full output schema and 100% schema coverage, the description supplies exactly the missing layer: mutual exclusivity, open-job lifecycle, and the sibling tools to poll/read/extend with. No essential calling information is 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?

Schema description coverage is 100%, so baseline is 3. The description adds real meaning beyond the schema by stating the mutual exclusion of `urls` and `items` ('not both') and the minimum-content rule ('at least one URL, unless `open` is true'), which the schema does not express as a constraint.

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 (submit many URLs as one asynchronous job) and immediately scopes it with 'shared settings applied to every URL'. It explicitly distinguishes itself from the scrape sibling and from batch_add_items/batch_close, so an agent can identify it without opening 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?

States the selection condition outright: 'Use this instead of many spicrawl_scrape calls when you have tens or thousands of URLs.' It also names the downstream lifecycle tools (batch_status to poll, batch_results/batch_task_content to read, batch_add_items/batch_close for open jobs) and the exclusive condition for urls vs items.

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 a genuinely new layer: the error contract. It explains that CONFLICT is ambiguous between 'not finished yet' and 'finished as failed, will never produce content', and that the message disambiguates — this is behavior an agent cannot infer from the schema or 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 dense sentences, front-loaded with the primary purpose, then the cost/routing rationale, then the failure semantics. No filler, and each sentence carries distinct 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?

With an output schema present, return values need not be described, and the description instead covers the two non-obvious gaps — cost trade-off versus paging and the ambiguous CONFLICT failure mode. Nothing an agent needs to call and interpret this tool 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 description coverage is 100%, so both `seq` and `job_id` are already documented in the schema, including the 0-based submission-order semantics that the description restates. The description adds no syntax or format detail beyond the structured fields, so the baseline of 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 (return), resource (one batch item's full payload), and the addressing key (`seq`), and explicitly contrasts itself with the sibling that pages results. An agent can identify the tool and its scope 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?

Gives an explicit selection rule ('Cheaper than paging results when you need one URL's output') that routes against spicrawl_batch_results, and additionally routes on failure states by telling the agent to poll spicrawl_batch_status on CONFLICT. When-to-use and the recovery alternative are both covered.

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?

Despite annotations covering safety hints, the description adds substantial behavior beyond them: single-use URL, 60-second window, options locked into the token (URL edits refused), token never exposes the API key, endpoint requires --with-cdp, key needs `browser` scope, and 404/403 failure modes. This is unusually rich disclosure for a token-minting tool.

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 the critical 'coming soon, do not rely' warning, which is the most important thing an agent can read. The body is dense and every clause carries operational detail, though it is long and could be tightened slightly.

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 return values, and it still covers auth, scope requirements, deployment prerequisite, token lifetime, single-use constraint, and failure codes. Nothing an agent needs to call or avoid this tool 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 description coverage is 100%, so the schema already documents all six parameters including enums, patterns, ranges, and mutual exclusions. The description only echoes this at a high level ('only with the options given here') without adding syntax or semantics 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+resource ('Mints a single-use connect URL for Spicrawl's remote browser'), names the underlying endpoint, and distinguishes itself from the sibling alternative ('use `actions` on spicrawl_scrape'). An agent immediately knows what it does and that it is currently non-functional.

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 when NOT to use it ('Coming soon... do not rely on this tool') and routes to the working alternative for scripted page interaction today. It also gives the timing rule (call right before connecting, again per session) and the Authorization-header variant.

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, so the safety profile is covered. The description adds useful context beyond them: the content is a static llms.txt index and what each entry carries, which tells the agent this is a cheap catalog lookup rather than a live query.

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 sentences, front-loaded with the resource and its contents, followed by when-to-use and the read follow-up. No filler and nothing repeated from the schema 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?

A zero-parameter catalog tool with an output schema, so return-value details need not be spelled out; the description still summarizes the entry shape. Nothing needed to select or 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?

Zero parameters, so the schema carries nothing to misinterpret and the baseline is 4. The description explicitly confirms 'No parameters', which matches the empty schema and removes any doubt about required input.

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 resource (the Spicrawl docs llms.txt index) and exactly what it contains: every page with title, one-line description and Markdown URL. It names spicrawl_docs_read as the follow-up and implies spicrawl_docs_search, so an agent can distinguish it from its siblings 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?

Gives explicit conditions: use it to find the right page when a search fails, or to get an overview. It names spicrawl_docs_read as the alternative for actually reading a page, though the search tool it complements (spicrawl_docs_search) is referenced only as 'a search' rather than by name.

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, open-world, so the safety profile is covered. The description still adds real operational detail beyond them: the 60,000-character truncation with an in-text notice, the domain restriction, and the anchor behavior (whole page returned, anchor merely names the section). It does not mention whether authentication is required, which is a minor remaining 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?

Three tight sentences, front-loaded with the core action, then accepted path forms, then limits and fallbacks. No sentence is redundant with the title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with an output schema, everything an agent needs is present: accepted input forms, domain restriction, truncation behavior, and escape hatches to sibling lookup tools. Return-value detail is correctly omitted since an output schema exists.

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; the description exceeds it by explaining that `path` accepts three distinct forms (a bare page path, a url/md_url returned by spicrawl_docs_search, or either with a `#anchor`) and by clarifying the anchor's semantics. That is meaningfully more than the schema's one-line 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?

"Fetches one Spicrawl documentation page as Markdown" gives a precise verb, resource, and output format. It is immediately distinguishable from spicrawl_docs_search (find pages) and spicrawl_docs_index (list all pages), so an agent can pick it 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?

It explicitly routes the agent: "Don't know the path? Use spicrawl_docs_search, or spicrawl_docs_index (llms.txt) for the list of every page." It also states the boundary condition "Only pages on the Spicrawl docs (https://docs.spicrawl.com) can be read," so both when-to-use and when-not-to-use are covered.

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, openWorld, non-destructive). The description adds meaningful behavior: the result shape (best-matching pages with title, matching sections, snippets, url, md_url) and the fact that error-code searches carry a direct link to that code's entry. It doesn't mention rate limits or result ranking behavior, so not quite 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?

Front-loaded with purpose and dense throughout, with no obvious filler. It is on the long side for what it covers, but each sentence carries distinct information (purpose, input guidance, return shape, next step).

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 output schema already exists, the description needn't explain return values yet chooses to summarize them, and it fully documents when to use the tool, how to phrase queries, and how to chain to spicrawl_docs_read. An agent has everything needed 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by clarifying what the query should contain (feature, parameter, error code or question) and by explaining the error-code lookup behavior with a concrete example, adding genuine semantic value.

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 (full-text search) and resource (Spicrawl documentation), and names the scope of the corpus (guides, API reference, errors, limits). An agent can distinguish it from sibling docs tools like spicrawl_docs_read and spicrawl_docs_index without opening any 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?

Explicitly says when to use it (look up a parameter/value for a spicrawl_* tool, or explain an error) and how to handle errors (search the error code itself). It also routes the agent to the correct follow-up, telling it to call spicrawl_docs_read with the returned md_url or url.

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?

Goes well beyond the readOnly/idempotent annotations by disclosing the auth requirement (needs `read` scope for other projects' requests) and precise failure semantics — not_found is returned both for unknown ids and for ids past the retention window. It also enumerates the content actually returned (status, error_code/detail, attempts, engine/proxy, block rules, latency spans, credits).

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 the provenance of the id, the debugging use case, the record contents, and the failure conditions — every clause carries information, and the multi-item lists are compact rather than 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?

With an output schema already present, return shape needn't be explained, yet the description still completes the picture with auth prerequisites, retention-window behavior, and cross-project access rules. Nothing an agent needs to call and interpret this 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 description coverage is 100% and the single `id` parameter is already documented as a ULID from X-Request-Id or a list row. The description repeats rather than extends this (mentioning the X-Request-Id header), so it adds no meaning beyond the schema — baseline 3 for a fully-covered single param.

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 — 'The full log record of one past API call by its request id' — and the singular 'one ... by its request id' clearly contrasts with the plural spicrawl_requests_list sibling. An agent can distinguish this from the list tool and from session/batch tools 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?

Explicitly names the use case: 'this is the tool for debugging a failed or slow scrape.' It gives clear context for when to reach for it, but does not name an alternative or state an explicit when-not (e.g. preferring requests_list for scanning many).

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?

Goes well beyond the readOnlyHint/idempotentHint annotations by disclosing the retention window (page.retention_hours/retained_since), the meaning of an empty page, the exact 403 ERR::AUTH::INSUFFICIENT_SCOPE failure mode and required `read` scope, and the pagination contract. This is behavior an agent cannot infer from 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?

Dense but front-loaded: core purpose first, then filtering, scope, retention, pagination, and the billing caveat. Every sentence earns its place, though the enumeration of returned fields is dense enough to slightly slow the opening.

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 paginated, retention-bounded, scope-sensitive list tool, the description covers pagination mechanics, retention semantics, scope requirements, error behavior, and the distinction from the totals tool. An output schema exists, so omission of return formatting is appropriate.

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; the description still adds value by tying parameters together (paginate via page.next_before/next_before_id into before/before_id, keep all_projects stable across pages, only_errors semantics) and reinforcing intent behind status filtering.

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?

Starts with a precise verb+resource+ordering statement ('Recent API calls in your key's project, newest first') and enumerates the fields returned, so the agent knows exactly what this list yields. It also distinguishes itself from sibling spicrawl_request_get (single call) and spicrawl_usage (totals) by naming the latter 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?

Gives explicit use cases ('find failing calls (only_errors=true)' and 'spot patterns across a target') plus a strong when-not directive ('Not billing-grade: use spicrawl_usage for totals'). Also names the alternative scope mode (all_projects=true) with its precondition.

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?

Goes well beyond the annotations: credits billing per successful call with failures free, cache-hit billing parity (cache saves time, not credits), the warning that non-GET methods and click/fill/script actions can mutate the target site, and the tier escalation behavior. The annotations only say readOnly=false, openWorld=true, destructive=false, idempotent=false; the description explains why those are true and what the practical consequences are.

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, then options, then billing, then safety, then return shapes, so an agent can stop reading early. It is dense and long (heavy parentheticals), but with 39 parameters and several cross-cutting behaviors almost every clause carries non-redundant 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 highly complex open-world tool, the description covers cost model, caching semantics, state-change risk, format-dependent return shapes, screenshot/PDF content blocks, and the JSON envelope fields. Even with an output schema present, nothing an agent needs to invoke it safely 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%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not state as a whole: 'With format: json, or when extract, ai_extract, autoparse, links, screenshot or network_capture is set, it returns the JSON envelope.' It also flags unavailable parameters (ai_extract) and clarifies defaults, which helps an agent pick among the 39 options.

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 and resource ('Retrieve a web page and return its content as markdown (default), text, HTML, a JSON envelope, or a printed PDF'), and the enumeration of output formats plus the fetch/browser handling makes it unmistakably the general-purpose single-URL scraper among its batch/session/usage 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?

Gives concrete usage conditions: 'set `cache=false` for time-sensitive pages', 'set them only when the user asks for that' for state-changing methods and actions, and 'With the defaults it only reads the page.' It does not route the agent to siblings (e.g. batch_submit for multiple URLs), but within the tool the when-to-use guidance is explicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds genuinely new behavioral context: the result contains live login cookies and other secrets and must not be echoed to the user or logs unless asked. That is important disclosure beyond the structured fields, though the failure mode for a non-LIVE session is left unstated.

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: payload contents first, downstream cloning use second, sensitivity warning last. Every sentence carries distinct information and nothing is 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?

With an output schema present, return values need only light description, and the description still characterizes them (cookies, fingerprint, domain scores). The secrets-handling warning closes the main risk gap; only edge behavior for expired/non-live sessions 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?

One parameter with 100% schema description coverage, and the schema already explains that session_id comes from spicrawl_session_create or spicrawl_session_list. The description adds no format, validity, or lifecycle detail beyond what the schema provides, so the baseline of 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 and resource ('Return the full stored state of a LIVE session') and enumerates the payload (cookies, localStorage, credentials, fingerprint, domain scores), which is far richer than a tautology. It does not explicitly contrast itself with the near-named sibling spicrawl_session_get, so an agent must infer that this returns raw stored state rather than session metadata.

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 a concrete downstream use case — passing the session_context object to spicrawl_session_create to clone the session — which tells the agent why and when to call it. It offers no explicit 'when not to use' or comparison against session_get/session_list, so the guidance is contextual rather than exclusionary.

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 are sparse (readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false). The description adds that the rendering tier is fixed for the session's lifetime, that sessions survive across scrapes, and that they must be released with spicrawl_session_release, which is meaningful for resource management. However, it doesn't disclose default TTL or expiration behavior beyond what the schema already shows.

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 dense paragraph with no wasted sentences and is front-loaded with the essential definition. It is slightly long, but every clause (persistent identity, multi-step flow, engine fixed, release step) 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?

Given that an output schema exists, the description doesn't need to enumerate return values, though it helpfully mentions key fields. It covers the critical lifecycle (create → use via session_id → release), which is exactly what an agent needs for this stateful resource.

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%, so the schema already documents every parameter thoroughly. The description adds a small amount of guidance (leave `engine` out and one is chosen) but not enough to go beyond the baseline 3 when the schema does all the heavy lifting.

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 (Create) and resource (a session/browsing identity), and elaborates exactly what a session is: a persistent state container (cookie jar, localStorage, fixed rendering tier, sticky exit IP). It distinguishes itself from siblings by naming spicrawl_session_release and spicrawl_scrape and describing their relationship.

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 when to use it (multi-step flows—log in then fetch pages behind the login) and how to use it with a sibling (pass the returned `id` as `session_id` to spicrawl_scrape calls that should share state). It also names a related lifecycle tool, spicrawl_session_release, for cleanup.

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

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

Annotations already flag destructive=true and idempotent=true, but the description adds real behavioral context beyond them: what gets destroyed (the record and stored state), that repeat deletes succeed, and that deletion is refused while a scrape holds the lease unless force is set.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with zero waste; the destructive scope is front-loaded, followed by the alternative and then edge-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?

With an output schema covering return values and annotations covering safety, the description supplies everything else an agent needs: destruction scope, idempotency, lease precondition, and escape hatch.

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%, so both parameters are already documented in the schema. The description reinforces the force semantics ('unless force is true') but adds no syntax or format detail beyond what the schema provides; 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+resource ('Permanently delete a session and its stored state') and explicitly scopes it against the sibling spicrawl_session_release, so an agent can differentiate 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?

Names the alternative explicitly ('prefer spicrawl_session_release if you only want to stop using it') and states the selection condition, plus the refusal precondition involving an active lease. When-to-use and when-not-to-use are both covered.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds valuable non-obvious behavior: it never returns credentials and points to the sibling tool that does, plus it lists the metadata fields exposed. It does not cover error behavior or lease semantics in depth.

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 tightly written sentences with no wasted words. The returned fields are front-loaded, and the credential limitation and alternative are appended as the key exception, making the structure 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?

For a single-parameter read tool with an output schema and rich annotations, the description is complete enough. It clarifies the return contents and the credential boundary, and the output schema handles the detailed response structure, leaving no critical gap for correct 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?

Schema description coverage is 100%, so the session_id parameter is already fully documented in the schema, including where it comes from. The description adds no additional syntax, format, or constraint details for the parameter, so the baseline score of 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?

The description states a specific verb (Return) and resource (one session's metadata) and enumerates the exact fields returned. It also explicitly distinguishes itself from the sibling spicrawl_session_context by noting it never returns credentials, so an agent can tell the two apart 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?

It gives a clear context for use (fetch a session's metadata) and an explicit alternative for the credential case ('use spicrawl_session_context for that'). However, it does not state when to prefer this over spicrawl_session_list or describe prerequisites for calling it, so it falls short of full when/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 readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds a security-relevant trait: "Never includes the stored credentials." It also discloses the return envelope shape and that next_cursor is the pagination handle, going beyond structured fields.

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, front-loaded with scope and ordering, then return shape and pagination, then the credential caveat. No filler and every clause 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?

An output schema exists, so return values needn't be fully explained, and the description covers scope, ordering, pagination, and the credential exclusion. It stops short of noting how the engine/status filters interact, 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?

Schema coverage is 100%, so all four params are self-documented, making 3 the baseline. The description's note that next_cursor is passed back as cursor largely restates the cursor param's own schema text, adding little beyond 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+scope ("List this API key's project's sessions") and adds ordering semantics ("newest first"). An agent can tell this is a paginated list apart from the singular session_get / session_context siblings, though it doesn't explicitly name an alternative.

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 verb (list = enumerate sessions) and it explains the pagination loop, but there is no explicit when-to-use/when-not guidance or routing against siblings like requests_list or session_get. Adequate but with clear gaps.

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 say destructive/idempotent/not-read-only; the description goes well beyond them by disclosing exactly what is destroyed (exit IP, browser state, cookies and storage, irrecoverably), what survives (the record, status `released`, history inspectable), the lease-refusal behavior, and the `force` override. This is the richest part of the definition.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight clauses in two sentences, front-loaded with the action and its consequences, then the refusal rule and return. No filler and no 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 destructive, idempotent session-ending tool with an output schema already present, the description covers everything an agent needs: scope, irreversibility, downstream effects on spicrawl_scrape, retained record, and the lease conflict path. Return-value explanation is correctly omitted since the output schema carries 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%, so the baseline is 3, but the description adds the missing trigger condition for `force` — refusal happens while a scrape holds the session's lease — which the schema only describes as 'break an active lease'. That contextual 'when is force needed' detail is genuine added value over the field-level text.

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?

Specific verb + resource ('End a session') with the consequences spelled out: frees exit IP and browser state, purges cookies/storage, record remains as status `released`. This distinguishes it from the sibling spicrawl_session_delete, which would imply record removal, without the agent having to open 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?

States the trigger clearly ('when you are done with it'), names the blocked follow-on ('can no longer be used with spicrawl_scrape'), and gives the recovery path ('start a new session and log in again'). It also documents the refusal condition and the escape hatch (`force` true). It never explicitly routes the agent to spicrawl_session_delete as the alternative, which keeps it just short of 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 cover only the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial context beyond them: the default 30-day window, the EXCLUSIVE end date with a worked example, a hard 400-day window cap, the stale_seconds freshness field, the requirement for the `read` scope, and the blind spot for keyless usage. That is a rich, non-obvious behavioral disclosure.

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 dense paragraph rather than a bulleted spec, which hurts scannability slightly, but the most important facts (what it returns, what it excludes, then window/date semantics, then auth) are front-loaded and each sentence carries non-redundant information. 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?

An output schema exists, so the description rightly does not enumerate return fields; it still flags the one response property worth knowing (stale_seconds). Combined with window bounds, exclusivity, grouping caveats and the required scope, an agent has everything needed to call 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 already 100%, so the baseline is 3, but the description goes further by explaining semantics the schema only gestures at: `to` is exclusive with a single-day example, the default window is last 30 days including today, and group_by=key changes both the source table and the returned counter shape. Minor gaps remain around how metrics interact with grouping, but the added meaning is real.

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: billing-grade org usage over a date window, drawn from the usage_daily rollup and groupable by day/project/engine/feature/key. It even names the alternate source table (usage_key_daily) for key grouping. It never names its obvious siblings (spicrawl_usage_summary, spicrawl_usage_reconciliation), so the agent gets no explicit differentiation within the usage family.

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 a concrete usage condition: "Use it to answer 'how many requests/credits did I use, and where'", and supplies negative scoping for group_by=key (keyless dashboard usage is absent; a project-scoped key only sees its own project). It stops short of stating when to prefer this over spicrawl_usage_summary or spicrawl_usage_reconciliation.

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, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-derivable context: the required `read` scope and the reason for the yesterday default (today's rollup is still accumulating), which is exactly the kind of behavioral detail annotations cannot carry.

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 sentences, no filler. The core behavior is front-loaded and the operational caveats (default, today's instability, required scope) follow in a single compact clause.

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 no explanation, and the description covers scope, defaulting and auth. The only gap is operational cost: re-deriving a full day from the request log may be expensive or slow, and nothing here warns about that.

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 `day` parameter is fully documented there, so the baseline is 3. The description goes slightly beyond by justifying the default (yesterday, because today always shows drift), which helps an agent decide whether to pass the parameter at all.

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?

Names a specific verb and resource ('re-derives usage from that day's request log and compares it with the billed daily rollup') and scopes it to ONE day, which separates it in an agent's mind from the raw-usage siblings spicrawl_usage and spicrawl_usage_summary. The 'drift report' framing makes the output intent 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?

States when the tool applies (a settled UTC day) and effectively excludes one case: 'today is still accumulating and would always show drift.' It never names the sibling alternatives (spicrawl_usage, spicrawl_usage_summary) that an agent might reach for instead, so 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.

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds two things annotations cannot: the auth requirement ('Requires the `read` scope') and the data-freshness caveat implied by 'from the daily rollup' (totals are rolled-up, not real-time). Missing only a note on lag magnitude or pagination, so not a full 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?

Two sentences, front-loaded with what the tool returns, followed by the routing guidance and the auth prerequisite. No filler; every clause 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?

An output schema exists, so return values need no prose. With annotations covering safety and the description covering scope, freshness source, alternative routing, and auth scope, an agent has everything needed to call 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?

Zero parameters, so the baseline is 4. The description explicitly confirms 'No parameters', which matches the empty schema and prevents an agent from hunting for filter options.

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+scope: a current-period, org-level usage summary sourced from the daily rollup. It explicitly distinguishes itself from the sibling spicrawl_usage by naming it and the axis of difference (compact current totals vs. windowed breakdown).

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 an explicit when-to-use ('quick how much have I used so far') and names the alternative tool plus the condition that selects it ('use spicrawl_usage for a windowed breakdown'). No inference required.

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