AUTOGROK Desk

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

Goes well past the annotations (readOnlyHint=false, openWorldHint=true) by disclosing the async job model, 24-hour turnaround, the polling endpoint, pricing (0.25 USDC or a pack credit), and refund behavior for failed calls under both payment modes. This is exactly the non-obvious operational context an agent needs before spending money.

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 what the tool produces and its async nature, then cost and billing caveats in the right order. The billing/refund sentences are long conditional chains but each carries information an agent would otherwise have to guess.

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

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

With no output schema, the description compensates fully by enumerating the finished brief's fields (title, summary, markdown body, source links, word count) and explaining how to retrieve them for free. Turnaround, cost, and failure semantics are all covered.

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 both parameters are already documented. The description restates the 500 default and 50-1500 range for max_words and adds that at least 3 public web sources are cited, which is mild added value rather than new syntax or constraint detail.

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

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

The first sentence names a specific deliverable (a cited research brief) and immediately flags the async, made-to-order nature. It never names the closest sibling, deep_brief, so an agent cannot tell from this text alone which of the two to pick.

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 through workflow: submit, get a job id and due time, then poll GET /v1/jobs/:id. But there is no explicit when-to-use/when-not guidance and no routing to alternatives like deep_brief or brief_status, which are directly relevant siblings.

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 safety profile (readOnlyHint, openWorldHint=false); the description adds cost (free), the delivery SLA (24h, usually same day), output size (50–1500 words, ~500 default), source-link guarantees, and the exact return shape including the nested result object. That is substantial disclosure 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?

Compact and front-loaded: the free/cost signal leads, then what it checks, then timing, then the return payload. Every clause carries information an agent needs to decide and call, with 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?

With no output schema, the description does the work of explaining the return payload (status, dueBy, result{...}), which is exactly right. It leaves minor gaps: no enumeration of possible status values or guidance on polling cadence while a job is pending.

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 id parameter is already documented as the job id returned by brief, so the schema carries the burden. The description adds only a marginal clarification that the id may also come from deep_brief, which is slightly more than the schema states but not a meaningful expansion.

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 (check) and resource (a brief ordered via brief/deep_brief), which cleanly separates it from the ordering siblings. An agent can tell immediately this is the polling/status counterpart to brief and deep_brief.

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 says the brief must have been ordered with brief or deep_brief, which establishes the precondition for use, and gives the delivery window as context. It does not explicitly say whether to poll repeatedly, how often, or what to do while status is pending, 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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true) by disclosing the async contract: a job id and due time returned immediately, report ready within 24 hours, polling free at GET /v1/jobs/:id. It also documents payment rails, per-call pricing, and failure semantics — 'failed calls aren't charged when you pay per call with x402' and credit return for pack credits — which is exactly the risk information an agent needs before spending money.

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 deliverable and its word count before the delivery mechanics, then the money terms. Every clause carries information, though the billing paragraph is dense and restates the $9.00 price already in the title, which is slight redundancy.

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

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

This is a paid, asynchronous, open-world tool with no output schema, and the description covers everything an agent needs: what comes back immediately (job id, due time), how to retrieve the result, the latency bound, the cost, and the refund behavior on failure. Nothing material is left to inference for a paid call.

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

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

Schema description coverage is 100% with only two parameters (topic, focus), both already documented in the schema, so the description carries little extra burden. It does convey that the tool produces operator-checked cited research, but adds no syntax, formatting, or scoping guidance for topic/focus beyond the schema text — baseline 3 is appropriate.

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

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

States a specific deliverable (in-depth research report with cited sources) plus concrete output shape: ~1,500 words, executive summary, key findings, and at least 8 cited public sources. The phrase 'for decisions that need more than a quick note' implicitly separates it from the lighter `brief` sibling, so an agent can route 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?

Gives a clear selection criterion ('decisions that need more than a quick note') and explains the delivery path via GET /v1/jobs/:id, pointing at the polling flow. It never explicitly names the alternative tools (`brief`, `brief_status`) or states when not to use this tool, so the routing signal is implied rather than spelled out.

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/openWorld annotations by disclosing that parsing is rule-based with no LLM (so deterministic and fast), the 50k character input ceiling, and the billing behavior including non-charge on error for both x402 and pack-credit paths. The only gap is that the shape of the returned 'notes' is never characterized.

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 and scope are front-loaded in the first two sentences, with usage and pricing trailing appendices. The billing paragraph is long relative to the parsing content, though it earns some place given this is a paid tool with two payment paths.

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

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

With no output schema, the description must carry the return contract, and it does partially (object built from schema_hint names, plus match notes). An agent would still like to know how unmatched fields or parse failures are reported, which is the remaining hole for a two-parameter tool whose annotations are minimal.

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 real meaning: schema_hint determines the field names of the output object rather than being a mere format flag. The 50k limit is repeated from the schema, which is the only redundancy.

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 ('Turn messy text into structured JSON') plus the two accepted input forms (JSON blob or key: value lines) and the output contract (object keyed by schema_hint field names, plus match notes). This is far more specific than any sibling (brief, page_extract, url_probe), which do unrelated work.

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 positive contexts ('normalizing tool output, logs or form dumps before further processing') and an explicit exclusion ('Not for free-form language understanding or writing'), which is exactly the boundary an agent needs to not confuse this with an LLM extraction tool.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantive context beyond them — clutter removal, no browser needed, private-host refusal, pricing model, and that failed x402 or pack-credit calls are not charged. That failure/refund behavior is exactly the kind of operational detail an agent cannot infer from 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?

Front-loads the core action and return shape, then moves to exclusions and pricing. The billing/refund sentences are long but arguably earn their place since the price is in the title and failure semantics affect invocation risk; still, they could be tightened.

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

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

With no output schema, the description fully compensates by naming the returned fields and the transformation applied. Input, exclusions, cost, and failure behavior are all covered — an agent has everything needed to call it correctly.

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

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

Only one parameter exists and the schema documents it at 100% coverage ('Public http(s) HTML page URL'), so the baseline would already be high. The description reinforces the constraint ('one public http(s) HTML page', non-HTML rejected), adding marginal value but nothing a schema reader couldn't infer.

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 ('extract') and resource ('readable text of a web page') and enumerates the return shape (markdown body, title, meta description, byline, excerpt). An agent can distinguish this from generic fetch or search siblings without reading 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 clear positive contexts ('summarizing, quoting, or feeding a page to an LLM or RAG index') and explicit exclusions ('logged-in, paywalled or non-HTML URLs... private hosts are refused'). It stops short of routing to a specific sibling (e.g., url_probe or brief), so it earns a 4 rather than a 5.

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

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

Annotations already declare this is not read-only, not destructive, not idempotent, and closed-world. Beyond that, the description adds important behavior: authentication via X-Entitlement-Key or email, that no automatic reply is sent, that a human responds usually within one business day, and that a HELP-XXXX id is returned.

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 four tight sentences, front-loading the purpose before authentication, return value, and response expectation. Every sentence adds useful information without redundancy.

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

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

For a low-complexity, three-parameter support tool with no output schema, the description supplies the missing return-value example, authentication expectation, and human-response timeline. The schema and annotations already cover the remaining structural details.

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 three parameters, including the topic enum and email default. The description restates the topic categories but does not add syntax, format, or constraint details beyond what the schema provides.

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 starts with a specific verb and resource: 'Open a support ticket with the people behind AUTOGROK Desk.' It clearly distinguishes support_request from metadata-oriented siblings like brief, page_extract, and json_shape, which are unrelated to contacting human support.

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 parenthetical lists concrete triggering situations (payment or receipt, a failed job, credits, anything else), which tells the agent when this tool is appropriate. It does not name an alternative support tool or explicitly state when not to use it, but no sibling competes for the same purpose.

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 destructiveHint=true and non-idempotent, but the description adds material context they don't carry: no new charge is made, the pack balance is cleared to zero, the action is irreversible, and an X-Entitlement-Key header is required. That is exactly the extra behavioral disclosure expected on top of 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 with zero filler, front-loaded with the action and its trigger, followed by the safety/irreversibility note and then the call protocol. Every sentence carries information the agent needs.

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

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

With no output schema, the description still covers everything needed to call correctly: auth header, irreversibility, the preview-then-confirm flow, and the guard value. Annotations handle the safety profile, and the description fills the remaining gaps.

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 alone justifies a 3, but the description goes further by explaining the coupling between the two params: preview with confirm=false, then pass the previewed total as expect_usd to confirm. It also notes the tip is refused if the total changed, which is a semantic constraint beyond the schema 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?

States a specific verb and resource (tip remaining unused credits plus pack balance to AUTOGROK Desk) and quantifies the scope. An agent knows exactly what action this performs and that it is unrelated to the sibling tools (brief, page_extract, url_probe, etc.), so no sibling differentiation is needed.

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 trigger condition ("When you're done with a pack") and spells out the required two-step call sequence: confirm=false/omitted to preview, then confirm=true with expect_usd. Nothing about when or how to invoke 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 cover safety (readOnlyHint, openWorldHint), and the description adds substantial context beyond them: the 8 KB GET cap, redirect following, the exact returned fields, refusal of private/local/logged-in URLs, and the billing semantics for failed calls under both x402 and pack 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-loads the core purpose in one short sentence, then layers return values, restrictions and pricing. The two sentences on payment/refund mechanics are the longest block but are genuinely decision-relevant for a paid tool; the paragraph is dense but nearly every sentence earns its place.

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

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

For a 2-param read tool with no output schema, the description covers what comes back (status, ok, final URL, content type, length, timing), what's disallowed, and the cost/failure model. An agent has everything needed to decide and invoke correctly.

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

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

Schema coverage is 100%, so both the url constraint and the HEAD/GET enum are already documented in structured fields. The description restates 'public http(s) URL' and the HEAD-default/GET-8KB fallback without adding format or behavior details the schema lacks, 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?

Opens with a specific verb and resource ('Check if a URL is up'), then names the exact mechanism (HEAD with GET fallback). It clearly separates itself from heavier siblings like page_extract and deep_brief by framing itself as a cheap pre-fetch check.

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

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

Explicitly states usage context: 'A cheap uptime, health or broken-link check before a heavier fetch,' which implies the alternative without naming it. It stops short of naming sibling tools or stating when NOT to use it, so it's clear but not exhaustive.

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 covering read-only and open-world behavior, the description goes further: it explains the output shape (hash, changed true/false, word count, fetch time), the previous_hash null convention, text normalization, and detailed payment/failure semantics for both x402 and pack-credit paths. This is exactly the extra context an agent needs beyond the annotations.

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

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

Front-loaded with the core action and output shape in the first two sentences, followed by use cases and payment terms. The payment paragraph is long but earns its place because billing and refund behavior are not available elsewhere. Minor trimming could still improve it.

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?

There is no output schema, and the description fully explains the return values (sha256 hash, changed boolean, word count, fetch time). It also covers the first-call null convention, normalization behavior, and billing/failure outcomes. Nothing an agent needs to call 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 coverage is 100%, so the baseline is 3. The description adds real meaning: previous_hash must come from a prior call and should be null on the first check, and the change flag is computed against that value. It also reinforces the URL must be public, but most parameter documentation is already 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 and resource: detects whether a web page changed since last check, fetches a public URL, normalizes main text, returns sha256 hash. It distinguishes itself from a monitoring subscription service ("no webhooks or stored subscriptions"), but does not explicitly differentiate from sibling tools like url_probe or page_extract.

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?

Clear context for when to use: a one-shot change check against a previous hash, for price/policy/docs pages. It rules out webhooks and stored subscriptions, but does not name when an agent should pick url_probe or page_extract instead. No explicit exclusions beyond the one-shot nature.

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