Spicrawl

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

Discloses non-obvious behavioral traits beyond the annotations: explicit 'Not idempotent: calling twice adds the URLs twice' directly explains the idempotentHint=false, and the CONFLICT-on-closed/finished rule is a failure mode not derivable from annotations. Also returns the result envelope shape, which is genuinely useful 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?

Four dense sentences, zero filler, and the critical preconditions (open: true, mutual exclusivity, non-idempotency) are front-loaded. Every sentence carries unique 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 11-param mutation tool with nested objects is fully covered: precondition, mutual-exclusivity rule, failure mode, idempotency caveat, and return shape are all present. With an output schema available the description need not expand further on 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?

Schema coverage is 100%, so the baseline is 3, but the description adds value the schema cannot: the mutual exclusivity of `urls` vs `items` ('EITHER ... not both') is only implied across two separate schema descriptions, and the 'shared settings for these new items' framing clarifies how the 11 params apply. Not a full 5 since most param detail lives in the schema.

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

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

States a specific verb+resource ('Append URLs to a batch job') and pins the precondition ('submitted with open: true'), clearly distinguishing it from sibling spicrawl_batch_submit which creates the job. An agent can tell these apart 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?

Explicitly scopes when this applies (only jobs submitted with open: true) and names the CONFLICT behavior when the job is closed/finished, which routes the agent toward spicrawl_batch_close semantics. No direct alternative tool is named, 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?

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the description only needs to add context — and it does: asynchronous lifecycle semantics ('an open job never finishes until you call `spicrawl_batch_close`'), the mutual-exclusivity rule, and the returned job fields. It stops short of discussing credit consumption behavior, rate limits, or partial-failure handling beyond the schema's failure_threshold.

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 purpose in sentence one, then progressively narrower operational guidance. Every sentence carries a distinct constraint (exclusivity, return shape, polling path, open-job lifecycle) with no restatement of the tool name 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?

For an 18-parameter, nested, asynchronous mutation tool with an output schema and annotations, the description supplies the operational context structured fields cannot: exclusivity rules, the open/close lifecycle, the follow-up tool chain, and when to prefer it over spicrawl_scrape. Return values are delegated to the output schema, which 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 description coverage is 100%, so the baseline is 3. The description goes beyond the schema by stating the urls/items exclusivity, the 'at least one URL unless `open` is true' rule, and the markdown default for `format` plus per-item override behavior — real semantic value not present in the field descriptions.

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 (submit) and resource (batch scrape job) with scope ('many URLs ... as one asynchronous job, with shared settings applied to every URL'). It also names the sibling it replaces ('instead of many `spicrawl_scrape` calls'), so an agent can differentiate it from the single-URL tool 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 when-to-use ('tens or thousands of URLs'), explicit alternatives (spicrawl_scrape for singles; spicrawl_batch_status/results/task_content for follow-up), and a hard exclusion ('Give EITHER `urls` or `items`, not both'). The `open: true` path and its dependency on spicrawl_batch_close is spelled out rather than 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 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?

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, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: pages over 60000 characters are truncated and the text says so, and only pages under https://docs.spicrawl.com/docs can be read.

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

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

Four tight sentences, all front-loaded with the core action first, then accepted input forms, then the domain limit, then routing to alternatives. 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?

Output schema exists so return values need no explanation; what remains an agent needs (accepted path formats, anchor semantics, truncation behavior, domain restriction, fallback tools) is all present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description genuinely enriches the single `path` parameter: it accepts a page path, a docs URL from search (url or md_url), or either with a `#anchor`, and clarifies the anchor only names the section to look at while the whole page is returned.

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 ('Fetches one Spicrawl documentation page as Markdown') and scopes it to a single page, which cleanly separates it from siblings like spicrawl_docs_search and spicrawl_docs_index.

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 alternatives and the condition for using them: '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 domain restriction on which pages can be read.

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?

With annotations only declaring readOnly=false/destructive=false/idempotent=false/openWorld=true, the description adds substantial behavioral context: per-call credit billing with failures costing 0, cache-hit billing equivalence, that non-GET methods and mutating actions can change state on the target, and the exact return shapes (image blocks for screenshots, resource block for PDFs, JSON envelope fields including status/credits/engine/warnings). This is exactly the operational detail structured fields 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?

Seven dense sentences for a 33-parameter tool, front-loaded with the core verb and return formats before moving to billing and mutation caveats. It is defensible in size, though the cache sentence restates the `cache`/`cache_ttl` schema descriptions nearly verbatim, which is mild redundancy rather than earned 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?

For a highly complex open-world tool with 33 params, nested action objects and an output schema, the description covers the decision-critical surface: formats, extraction modes, billing model, caching semantics, mutation risk, and return envelope composition. An agent has enough to invoke it correctly without opening the schema for behavior, even though return fields are additionally documented in the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it groups the parameters that flip the response into the JSON envelope (format:json, extract, autoparse, links, screenshot, network_capture) and explains the credit/cache interaction that governs cost-bearing parameters. It stops short of syntax detail for individual selectors, which the schema already owns.

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 ('Retrieve a web page and return its content as markdown/text/HTML/JSON/PDF') and enumerates the concrete capabilities (extract, autoparse, links, screenshot, DOM scoping). An agent can instantly tell this is the general-purpose page-fetch tool. It does not, however, explicitly distinguish itself from siblings like spicrawl_request_get, leaving that boundary to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives real when-to-use guidance for several flags: 'set cache=false for time-sensitive pages', 'set render for single-page apps or pages whose content is painted client-side', and 'set a method other than GET/HEAD/OPTIONS, and the actions... only when the user asks for that'. What is missing is routing against alternative tools (batch vs. request_get vs. this), so it stops short of an explicit alternatives map.

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 declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the agent already knows this is a non-idempotent creator rather than a safe read. The description adds meaningful context beyond those hints: session persistence across scrapes, sticky exit IP, the lifetime-fixed rendering tier, and the explicit release requirement. It doesn't cover expiration semantics in depth (though expires_at is returned), but the added value is substantial.

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 sentences, front-loaded with the definition and moving through usage, behavior, and cleanup. Dense but every sentence earns its place; the return-value sentence is concise and enumerates the returned fields cleanly.

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 needn't be explained, but the description still names them briefly. It addresses the session lifecycle (create → use via session_id → release), the engine's fixed-tier constraint, and the default engine choice — everything an agent needs to call and chain 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 schema already documents engine, ttl_seconds, domain_scores, and session_context, including enum values and constraints. The description reinforces the engine's fixed-lifetime behavior and the 'leave it out' default, but this repeats schema content rather than adding syntax or semantics. With full schema coverage the baseline is 3.

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 (Create) and resource (a browsing session), then defines it precisely as 'a persistent browser identity (cookie jar, localStorage, a fixed rendering tier and, by default, a sticky exit IP) that survives across scrapes.' This clearly distinguishes it from sibling lifecycle tools like spicrawl_session_release, spicrawl_session_delete, and spicrawl_session_get.

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 names the use case ('multi-step flows — log in, then fetch pages behind the login'), explains the mechanism for chaining (pass the returned `id` as `session_id` to `spicrawl_scrape`), and names the cleanup sibling with a condition ('Release the session with `spicrawl_session_release` when done'). When and how to use it are fully specified.

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.