AgentDrives

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, and a closed world, so the safety profile is covered. The description adds value beyond that by disclosing the auth requirement (API key) and the substantive return content — balance, expiry, per-top-up receipts, and daily/refund history — which is not derivable from 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?

A single front-loaded sentence establishes the resource ('Your prepaid credit for paid calls') before listing what it reports. It is dense but every clause names distinct return content, so little is wasted; the parenthetical list is slightly heavy but 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?

With no output schema, the description carries the burden of describing what comes back, and it does so reasonably well (balance, calls paid, expiry, receipts, history). Combined with the API-key prerequisite, an agent has enough to call and interpret it correctly, though date-range or pagination behavior for the history is unstated.

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

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

The tool takes zero parameters, so the baseline is 4. There is no parameter surface to document and the description appropriately spends its words on return semantics instead.

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 resource — prepaid credit / balance for paid calls — and enumerates its contents (balance, expiry, per-top-up receipts, call history). It references the sibling action top_up, giving an agent a clear handle on what this reads versus what that writes, though it does not distinguish itself from closer siblings like pay_check or my_orders.

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

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

Usage is only implied: an agent can infer 'check my credit/balance,' and the description supplies a prerequisite ('Needs your API key') plus a link to top_up. There is no explicit when-to-use-this-vs-alternatives guidance naming pay_check, my_orders, or withdraw_order.

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?

Adds meaningful behavior beyond annotations: cancellation runs to the end of the paid period and the listing remains with its date. Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so this timing/lifecycle detail is the true value-add. It does not specify auth requirements or how to recover a cancelled drive, but covers the key behavioral nuance.

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, zero waste, front-loaded with the verb and resource. The lifecycle note and listing-persistence note each earn their 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?

Complete for a single-parameter mutation tool: it explains scope, timing, and post-cancellation state. With no output schema, it reasonably omits return-shape details since the description says the listing persists, making the resulting state predictable.

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 schema already documents order_id and the leave-out-to-cancel-all semantics. The description repeats this scoping behavior but adds no format, syntax, or sourcing detail beyond what the schema provides; 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 verb+resource (cancels the Monthly drive) with clear scope: one product via order_id or all of them. The tool is distinguishable from siblings like drive_stop and switch_monthly 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?

The description implies usage (leave order_id out to cancel all) but gives no explicit when-to-use context, no prerequisites, and does not name alternative tools like switch_monthly or drive_stop that an agent might consider.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description then adds genuinely useful behavioral context beyond them, since there is no output schema: it explains what each returned state means ('waiting (an answer is on its way)', 'answered (with the answer)') and covers the dispute re-drive states. It stops short of describing pagination or the overall response shape.

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 whole definition is a single semicolon-chained sentence that is compact but cryptic and not front-loaded with the operation. The phrase 'the next step; a dispute's re-drive (queued, running, done)' is dense and context-dependent. Every clause is short, but the structure forces the reader to parse instead of scan.

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 carries the burden of explaining return values, and enumerating the case states partially discharges that. However, ambiguous fragments like 'the next step' are undefined, and the way to distinguish case_id from case_token is left unclear. Adequate for a simple read-only status tool but with noticeable 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 description coverage is 100%, so both parameters are already documented. The description adds only marginal semantics ('the key of the case's account, or the case_token ... without a key'), which is a slightly confusing rewording of the either/or the schema already states. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The name 'case_status' and title 'A support case's status' already signal the resource, and the description restates this by enumerating the possible states (open, waiting, answered, closed). It never states a verb like 'retrieve/get the status', so the purpose is implied by the value list rather than declared. It does not explicitly differentiate itself from siblings like support_ask or dispute_result, which only appear as sources of the id.

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

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

There is no explicit when/when-not guidance or named alternative. Usage is only implied by the reference to 'the case_token support_ask gave', which hints that this is called after support_ask creates a case. An agent can infer the workflow but the description never states the condition that selects this 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?

Goes well beyond the annotations: it discloses the tiered verification logic (account email on the domain verifies instantly), the carve-out for mailbox providers and its own domains (agentdrives.com, matfy.com) with a queued free private check, the failure feedback via 'pending', and the four alternative proof methods with concrete artifact paths. For a write operation (readOnlyHint=false) this is unusually rich behavioral context.

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

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

It front-loads the workflow position well, and nearly every clause carries real information, but the middle is a dense run-on chain of nested conditions that is hard to parse. Tighter grouping (instant-verify / queued-check / alternative proofs) would preserve the content with better structure.

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 what happens after the call (verification outcomes, pending reasons, returned proof methods). An agent has enough to invoke it correctly; only the absence of any next-step pointer to verify_claim leaves a small gap.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description adds nothing about parameter syntax or semantics and never mentions the optional 'tool' (directory slug) parameter at all, 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 and resource ('adds your product's domain') and situates it explicitly as step 1 of a named 3-step workflow (claim, verify, order), which cleanly separates it from siblings like verify_claim, order, and send_claim_code. An agent can tell what this does and where it sits in the flow without opening the schema.

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

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

The 'Step 1 of 3' framing implies when to reach for it and names the downstream sequence; pointing at send_claim_code for the verification code is explicit routing. It never names verify_claim as the mandatory next call, so the handoff is implied rather than stated.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true): it discloses the auth failure mode (403 claim_not_verified), the case-opening workflow, the async re-drive queuing rule keyed to a 30-day window, and the fact that the re-drive result only appears on the listing once reviewed.

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 verb and resource are front-loaded in the opening clause, and the parenthetical checkpoints and re-drive condition each carry real information. It drifts into a dense multi-clause run-on with nested parentheses, which slightly hurts readability without being wasteful.

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 job of explaining returns (case_id, the re-drive's state and the next step) and routes the eventual written answer to case_status. Auth, workflow, and return payload are all covered, leaving little an agent needs 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 75%, so most parameters are documented structurally, including the full checkpoint enum. The description reinforces the checkpoint list and characterizes claim as 'what is true' and product as the caller's own product, but adds no format or constraint detail beyond the schema, 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 (Disputes) and resource (the published result of your own product), and enumerates the checkpoint scope that maps to the enum. It distinguishes itself from case_status by designating the latter as the channel for the answer, but gives no direct sibling comparison to tools like recheck_after_fix or followup_drive.

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 prerequisite is explicit (an API key with a verified claim on its domain; else 403 claim_not_verified), and the 30-day re-drive condition is stated. However, there is no guidance on when to dispute versus alternatives such as recheck_after_fix or followup_drive, so the choice is left implicit.

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 safety (destructiveHint=false, idempotentHint=true), but the description adds substantive side-effect scope: published results persist with their date, and the caller's own orders keep running while stopped. That is genuine behavioral context beyond the structured fields, though reversibility of other state is 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?

It is short and the stop/restart action is front-loaded, but the phrasing is convoluted ("Stops our drives of your own product (a verified claim)") and the trailing read-mode clause reads awkwardly. Compact, yet not every sentence parses cleanly on first read.

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-parameter tool with full schema coverage and no output schema, the description covers the write/read duality and key side effects well. The main gap is the undefined domain term "drives" and what the read result actually represents beyond a stopped/not-stopped flag.

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 and the tri-state behavior of 'stop' (true/false/omit) are already documented in the schema. The description's restatement of "stop true or false" adds no format or semantics beyond it, 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?

The description names a verb pair (stop/restart) and a resource ("our drives of your own product"), and ties it to a verified claim. However, "drives" is never defined, so an agent must infer the domain concept and cannot confidently distinguish this from the sibling followup_drive. Purpose is recognizable but muddled.

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 states one real prerequisite (the claim must be verified) and clarifies the read case ("Without stop: whether our drives of it are stopped now"). It names no alternative tools and gives no explicit when-not-to-use guidance, leaving selection against verify_claim/followup_drive 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, so the bar is lower, yet the description adds real behavioral context: result ordering rules, empty-list behavior when nothing matches, and the semantics of every result code (done, partial, plan_gated, failed, blocked, not_tried, unknown) and level scale. It does not cover auth or rate limits, but the read-only profile is already anchored by annotations.

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

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

The core purpose is front-loaded, which is good, but the rest is a single dense run-on paragraph stuffed with parentheticals and semicolon lists. Much of the field enumeration could be tightened, and the readability cost is real even if the information is useful.

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 carries the return-shape burden and does so thoroughly: it names each field, defines enum values, states sort order, default/cap on limit, and the empty-result case. Coverage is strong; only the absence of explicit sibling-routing guidance leaves a small gap.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including self_signup and limit bounds. The description restates self_signup and the limit cap/default but adds no format or interaction detail for category and min_level, 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 and resource with scope: 'Ranks the products AgentDrives has test-driven for a task given in plain words', with concrete task examples. It also distinguishes itself from the sibling get_tool ('returns one product in full'), 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?

Usage is implied by the input description ('a task in plain words') and there is a one-line pointer to get_tool for full product detail, but there is no explicit when-to-use/when-not guidance or comparison against siblings like search_tools or list_categories. The agent must infer the selection criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered without the description's help. The description still adds real behavioral value: the exact error semantics for an unknown slug, and the fact that fields like works_assisted can be null ('not measured yet') and that after_wall is 'never part of the level'. That is context 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?

This is a single monolithic paragraph of run-on sentences with deeply nested parentheticals that make it hard to parse. While there is no output schema so field documentation is warranted, the structure is hostile to reading and the front-loaded purpose is immediately swallowed by hundreds of words of field enumeration. Conciseness and structure are the weakest aspects.

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 assumes the burden of documenting the return shape and does so exhaustively: level, five outcomes, checkpoints, pay_options, agent_check, after_wall, works_assisted, robots, level history, rules_date, and the newer routes/checkout/docs/claims fields. The null and error cases are disclosed. It is nearly complete, losing only points for legibility rather than missing substance.

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 'slug' parameter is fully documented in the schema, including the provenance and an example. The description reinforces the same point ('search_tools gives the slug; an unknown slug is an error') but adds no format or syntax detail beyond it, 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?

The opening clause gives a specific verb and resource: 'Returns one product's full test-drive result.' It also routes the agent by naming the sibling that supplies the input ('search_tools gives the slug'), so it is distinguishable from search_tools. The rest of the purpose signal is buried under an enormous parenthetical dump, which dilutes an otherwise clear statement.

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 implies the retrieval workflow ('search_tools gives the slug') and notes the failure mode (an unknown slug is an error that says how to find one), which is genuine usage guidance. However, it never states when to use this versus siblings like drive_stop, recheck_after_fix, or followup_drive, and gives no when-not-to-use condition. This is adequate-but-implied 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 and closed-world, so the safety profile is covered. The description adds the return shape and the value domain of one field (agent level 0-5), which is genuine behavioral context beyond the annotations, though it says nothing about ordering, pagination, or empty-directory behavior.

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

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

A single sentence, front-loaded with the verb and scope, with the id's downstream use parenthesized rather than buried. Every clause maps to a concrete field or use case; nothing is padding.

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 and no parameters, the description carries the full burden of describing the response, and it does so field by field (id, name, product count, best agent level 0-5) while tying the id to its downstream consumer. Nothing an agent needs to call and use this tool 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?

The tool takes zero parameters, which sets the baseline at 4 by rule. There is nothing for the description to disambiguate, and it correctly spends no words on parameters.

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

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

States a specific verb and resource ("Lists every category in the directory") and enumerates exactly what each row contains: id, name, product count, and best agent level. It even distinguishes itself from siblings by noting the id feeds search_tools' category filter, so an agent can tell it apart from search_tools without opening a schema.

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

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

The clause "its id (for search_tools' category filter)" gives clear implied routing: call this to discover a category id before filtering with search_tools. There is no explicit when-not guidance or statement of preconditions, but for a zero-parameter enumerator the context is unambiguous.

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

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

Annotations only declare the generic safety profile (readOnly=false, openWorld=true, idempotent=false, destructive=false), and the description adds substantial context beyond them: the full side-effecting sequence including account cancellation/deletion, cost implications (free vs. counting against free checks), concurrency (one at a time), and a per-domain 30-day rate limit.

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, but the prose is dense and somewhat repetitive — the 100% off code purchase step is stated twice — with several stacked parentheticals. Every sentence is informative, but it 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?

For a complex, side-effecting tool with 4 params, no output schema and no nested objects, the description covers process, prerequisites, cost model and rate limits well. It stops short of describing failure modes or what the emailed report contains, but is otherwise complete enough to invoke correctly.

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

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

Schema description coverage is 100%, so all four parameters (url, kind, tool, value) are already documented, including the kind enum. The description echoes the code/sandbox distinction and code semantics but adds little syntax or meaning the schema does not already carry — 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 verb and resource — start a private agent-driven checkout test for a product's pay step — and enumerates the exact sequence (sign up, buy with 100% off code, use a paid feature, cancel, delete). An agent can tell it apart from siblings like pay_code, pay_order and verify_claim, which are named in the flow.

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 conditions: free for a product you've proved yours (verify_claim), otherwise it counts against free checks, plus limits (one at a time, 2 per domain incl. subdomains per 30 days). It names verify_claim as the prerequisite but does not explicitly state when NOT to use it (e.g. vs pay_code/pay_order or drive_stop).

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

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

Beyond the annotations, the description discloses real behavioral traits: the value is 'sealed, never shown back' (only kind, last two chars and status are visible via whoami/my_orders), and the code is 'deleted after the drive that used it.' This lifecycle and secrecy context is genuinely useful. Minor tension: it describes a delete while destructiveHint is false, but the deletion is expected/intended so this is not a clear contradiction.

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

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

A single bloated, semicolon-chained sentence mixes several ideas (buying, add/replace kinds, removal, sealing, lifecycle). It is not front-loaded: the concrete action comes after the vague 'our agent buy your plan' preamble, so the reader must work to extract the point.

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

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

With no output schema, the description correctly covers the return-adjacent behavior (value is hidden; only kind, last two chars, status shown) and the deletion lifecycle. However, it omits the add-vs-replace semantics and required order_id origin details are left to the schema, leaving the picture only partially complete.

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 75%, so the schema already documents kind, value, remove and order_id. The description loosely maps kind to its options ('a discount code, a test-mode login or a seat') and restates the remove flag, adding little beyond what the schema provides. Baseline 3 is appropriate.

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

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

The title ('Add or remove the code for your order') and phrases like 'add or replace a discount code, a test-mode login or a seat' convey a verb+resource, but the description buries this under rambling prose ('Let our agent buy your plan, on an order you placed'). The purpose is recoverable but not cleanly stated, and no sibling (pay_order, pay_check, order) is named for contrast.

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?

'until a drive has it' hints at when the code is consumed and 'remove: true deletes it' covers removal, but there is no explicit when-to-use guidance or routing to alternatives like pay_order or order. The agent must infer the workflow from ambiguous fragments.

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, openWorldHint=false, so the safety profile is covered. The description adds behavioral context about sorting ('Sorted by level, then work done, then minutes to the first call'), pagination ('Up to limit results (default 25, at most 100)'), and empty-result behavior ('none match: an empty list'). That is useful, but it is couched in very dense prose and doesn't clarify rate limits, auth, or whether the search index is live.

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?

This is an extraordinarily long, run-on description - roughly 250+ words in a single paragraph with nested parentheticals. The core purpose (search tested products) and critical usage guidance are front-loaded only if the agent reads the first ten words; the rest is a stream of return-field explanations, filter restatements, and glossary definitions. It is not appropriately sized and forces the reader to parse dense prose to find invocation-relevant details.

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, so the description carries the burden of explaining returns, and it does so thoroughly: level and its name, access, the five outcomes, part scores, wall_type, origin, and page URL. It also covers sorting, pagination, empty results, and routes to get_tool and list_categories. The main gap is that it never states when not to use it versus find_tools_for_task, a sibling that likely overlaps.

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 every parameter is already documented in the schema. The description restates filters and adds the min_level 0-5 meanings (0 Read-only through 5 Autonomous) and access enums, which is additive for a human but largely redundant with the schema. Per the rubric, 100% coverage sets a baseline of 3, and the description does not add syntax or format 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 states a specific verb+resource: 'Searches AgentDrives' tested products by name, domain or what they do'. It clearly distinguishes itself from get_tool (which returns one product's full result) and list_categories (which gives category ids). However, the opening sentence is buried under a 250-word run-on that mixes filtering, sorting, and output-field explanations, so an agent must dig to extract the core purpose.

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 names alternatives explicitly: get_tool returns one product's full result by a slug from here; list_categories gives the category ids. It implies this is the directory search and that get_tool is the drill-down. It does not explicitly say when NOT to use it (e.g. if you already have a slug) or when to prefer find_tools_for_task, which is a sibling that may overlap.

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=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the external side effect and non-idempotency are covered. The description adds that a code is emitted and later checked by verify_claim, but says nothing about resend behavior, code expiry, rate limits, or what happens if the address isn't valid for the claim.

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, front-loaded with the route/step context and then the exclusion, with no filler. The telegraphic fragments ('Step 2 (mail route): a 6-digit code…') cost a little readability but not efficiency.

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 two-parameter tool with fully documented schema, no output schema, and annotations covering the safety profile, the description supplies what matters: the route, the exclusion set, and the follow-up verification step. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description's 'local is the part before the @ (e.g. jane or admin)' merely restates the schema wording. It adds only the indirect hint that the domain comes from the claim rather than the caller, so baseline 3 is right.

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 identifies a specific resource (a 6-digit claim code) and its delivery channel/scoping (mailed to an address at the claimed domain), and places it as 'Step 2 (mail route)' in a workflow. The precise verb is only implied by the tool name and 'mail route', and the counterpart step-1 tool is not named, so it falls just short of a 5.

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 exclusion ('Not for a mailbox provider's domain (gmail.com, tuta.com …)') and redirects those cases to the DNS, meta-tag or file routes, and it points to verify_claim as the check. It still doesn't state positively when the mail route is the right choice versus the other proof methods for a self-hosted domain.

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 it is a non-read-only, non-idempotent, non-destructive call; the description far exceeds that by disclosing the api_key is shown once and goes in x-api-key, the claim link is valid 7 days, the key stops working on claim, and how the account behaves until claimed (1 free check/day, 402 payment, claim_required). It even documents the separate deletion flow, giving rich lifecycle context the annotations cannot convey.

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

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

The core (account + api_key + claim link) is front-loaded, but the body is a dense wall of parenthetical run-on sentences that mixes lifecycle, pricing, and deletion details. Every fact is relevant, yet the structure makes the critical first-step information harder to extract than a split into short ordered sentences would.

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 signup tool with no output schema, the description fully covers inputs, the returned fields (api_key, claim.url), the claim lifecycle, pre-claim limits, and even the exit path. Nothing an agent needs to call it and understand the result 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 already 100%, setting a baseline of 3. The description adds genuine meaning beyond the schema, explaining that the claim link is also sent to the optional email and that the agent name is 'kept on the account', which clarifies each parameter's downstream effect.

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 action (create an agent account) and its immediate output (an api_key plus a claim link), distinguishing it from every other sibling tool, which operate on an already-existing account. An agent can tell this is the bootstrap/entry-point tool 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?

'No key needed' clearly frames the use case as the first step before any keyed operation, and it names related paths (pay_order, claim_required) for the pre-claim state. It stops short of explicitly stating when-not-to-use or naming the prerequisites in a crisp condition, so it is strong context but not full routing 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 only cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds genuinely useful context beyond them: the call is advisory rather than an action, carries no queue placement, and selection is by demand and gaps. That is exactly the kind of expectation-setting annotations can't 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?

Two compact sentences with no filler, and the expectation-setting clause is front-loaded with the core action. Minor looseness in the parenthetical, but nothing wasted.

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

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

For a simple two-parameter, no-output-schema tool with annotations covering safety, the description explains what the call means and what it does not guarantee. It is still thin on where this fits relative to the many sibling tools, which an agent selecting among 25 options would need.

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% — both 'url' and 'why' are documented in the schema, including that 'why' is optional and that 'url' may be an address or a name. The description adds only the scope qualifier ('any product'), so the schema does the heavy lifting and 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: suggests a product for the agent to drive and list, scoped as 'free, anyone, any product'. It distinguishes itself from transactional siblings like order/pay_order, though 'drive' is domain jargon that isn't defined.

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 implies when to use it ('a signal for our planner') and what it is not ('never a promise or a place in the queue'), which sets expectations. However, it gives no explicit when-to-use-vs-alternative guidance among the ~25 siblings, leaving routing 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?

Goes well beyond the annotations (which only say readOnlyHint=false, idempotentHint=false, openWorldHint=false, destructiveHint=false) by disclosing the real side effect — case creation — plus a concrete rate limit (max 3 cases/day per agent), key-dependent enrichment from the caller's own orders and claims, the not_opened outcome for tests, and an explicit disclaimer about what the tool will never promise. This is exactly the mutation and quota context an agent needs.

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 and every clause carries real information — outcomes, rate limit, exclusions. It is information-dense but the long run-on sentences with interleaved field names ('answered: false, case_id; without a key also a case_token') make parsing harder than it needs to be, costing a point.

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 and no annotation detail, the description carries the return-value burden itself and does so: answered/case_id/case_token/case_status/not_opened are all explained, along with auth effects and quotas. 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 description coverage is 100%, so the schema already documents product, question and on_behalf; the description adds no format or syntactic detail for them. Baseline 3 applies: the description clarifies the conceptual role of API keys in shaping answers but does not extend any individual parameter's meaning.

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 ('Answers a question about AgentDrives') and even enumerates the covered scope (prices, plans, levels, method, orders, API, MCP), so an agent can judge in-scope questions. It does not, however, differentiate itself from siblings that touch the same territory, such as my_orders or case_status, which it only mentions as a return field.

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 topic scope, and the description explains the answered/not-answered branching plus the test/placeholder carve-out. But it never says when to prefer this over alternatives, e.g. checking an existing case via case_status or pulling orders via my_orders instead of asking here.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. Beyond that, the description adds real behavioral value: the price points ($29/month vs $290/year) and the carve-out that pre-10 October 2026 subscriptions retain their price and yield a 409 legacy_plan. It still omits what actually happens on switch (proration, effective date).

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 front-loaded sentences with no filler. The second sentence is terse to the point of being cryptic, however: "keeps its price (409 legacy_plan)" packs a price-lock rule and an error code into a parenthetical without explaining the relationship.

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 two-parameter mutation with no output schema, the description covers purpose, pricing, and one important edge case, which is adequate. It leaves gaps an agent would care about: whether the switch takes effect immediately, what happens to in-flight billing, and what a successful or failed call returns.

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 50%: order_id is documented with its source (my_orders), but `to` is only an enum with no prose. The description compensates partially by describing the two states and their prices, but never maps them to the `to` parameter or explains how order_id is validated.

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 names a specific verb (Switches) and a specific resource and scope (the Monthly drive's billing period for one product), with concrete prices distinguishing the two target states. An agent can distinguish it from cancel_monthly or drive_stop, though the tool's internal term "drive" is never reconciled with the clearer title.

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: it's clear this is for toggling an existing subscription's billing period, and the order_id lookup path (from my_orders) is supplied by the schema. There is no explicit when-to-use versus cancel_monthly, drive_stop, or followup_drive, and no stated preconditions such as required account state.

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

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

The annotations declare readOnlyHint=true, yet the description describes a payment that debits a key, creates an agent account with a returned key, and stores credit – unmistakably state-changing behavior. The description is otherwise rich (HTTP 402 challenge flow, idempotency_key semantics, $100 cap, 12-month expiry, VAT/receipt), but this direct contradiction with the read-only annotation is disqualifying.

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 front-loaded with the core action, but the single dense paragraph packs in payment rails, idempotency, balance limits, receipts, and VAT without structural breaks, making it hard to scan. Most sentences carry information, but the wall-of-text form hurts retrieval.

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

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

For a complex, no-output-schema payment tool it covers a lot: the 402 challenge flow, the credential/idempotency mechanics, what a keyed vs unkeyed call returns, and the balance ceiling. It is nearly complete, though the account-creation outcome could be stated more explicitly as a return value.

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

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

There is a single parameter with full schema description coverage and an enum, and the schema already documents that 5 buys 500 calls. The description restates the 5|20|50 values but adds no syntax or meaning beyond the schema, 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 specific action and resource: buying prepaid credit for paid calls, and it explicitly frames it as a distinct operation from pay_order ("as with pay_order") and from balance ("this also gives your balance now"). It also scopes the credit to "calls only, not a report or a drive," so an agent can separate it from sibling payment tools without reading 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?

Usage context is clear: it is the path for funding call credit, and the note that it "pays for calls only, not a report or a drive" implicitly routes report/drive purchases to pay_order. However, no explicit "use this when / do not use when" rule names the alternative, so the routing is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, openWorldHint=true and destructiveHint=false. The description adds value beyond those flags: the ordered fallback chain for verification and the side effect that a newly verified product gets a free check while remaining private until a drive. It is consistent with 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?

It is compact and front-loads the key framing ("Step 2 of 3"). Sentences are dense with parentheticals but every clause conveys behavioral or routing information, so little is wasted.

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 carries the burden of explaining mechanics, and it does so well (both verification paths, ordering, side effects, privacy). It stops short of describing what a success/failure response looks like or auth prerequisites, but overall it is nearly complete for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline would be 3. The description adds real meaning by explaining what the code parameter does when supplied (checks the mailed code) and what happens in its absence (DNS TXT → meta → file), which the schema does not convey.

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 ("verifies a claim") and frames it in a workflow ("Step 2 of 3"). It distinguishes the two paths (with code vs. without) and names the sibling send_claim_code as the source of the code. The only weakness is that steps 1 and 3 of the workflow are left unnamed.

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

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

It clearly separates the two invocation modes: with a code, use the mailed 6-digit code; without, fall back to DNS TXT, then meta tag, then file. It also gives the business context ("Every order but the free check needs a verified claim") that motivates use. It does not name when NOT to use it or an explicit alternative 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 already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered structurally. The description adds only the content disclosure that claimed domains and orders are included, which is mildly useful but not behavioral 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?

A single short fragment with no wasted words; it is front-loaded and cheap to read. Its brevity is appropriate for a zero-argument lookup, though the fragment form costs it a point.

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

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

For a zero-param read tool with no output schema, the description gives a rough sketch of the returned sections (account, claimed domains, orders), which is adequate but not complete—it never states the tool takes no arguments or that it identifies the current caller.

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

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

The tool takes zero parameters, so the schema has nothing to document and the baseline is 4. There is no parameter meaning the description could or should add.

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 is a noun phrase that names the data the tool returns (account, claimed domains, orders), which gives some substance beyond the title, but it omits any verb and largely restates the title 'Your account'. It does not clearly distinguish this identity/profile lookup from siblings like my_orders or balance, which cover overlapping data.

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

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

There is no statement of when to use this tool versus alternatives such as my_orders or balance, despite obvious overlap on the 'orders' data. An agent is left to infer that whoami is the identity entry point.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the agent knows this is a destructive, repeatable mutation. The description adds the unpaid-order precondition, which is useful gating context, but says nothing about what withdrawal actually does (void vs. delete), whether it is reversible, or what error occurs if the order is already paid.

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

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

A single short sentence with the precondition front-loaded; nothing is wasted. It is efficient but minimal — there is no second sentence that would carry the behavioral detail the tool 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?

For a destructive mutation with no output schema, the description covers the eligible state but omits outcome and failure semantics (irreversibility, already-paid behavior, what the caller gets back). Annotations carry the safety profile, so this is thin but not unusable.

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 schema already explains order_id comes from my_orders. The description adds no additional meaning about the identifier's format or sourcing, 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 (withdraws) and resource (order) plus a key scope condition: the order must not have been paid yet. That condition meaningfully separates it from pay_order, but the description never names the sibling or the my_orders lookup that supplies order_id.

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 precondition "has not been paid yet" implies when the tool is applicable, but there is no explicit when-to-use/when-not-to-use guidance and no named alternative for orders that are already paid (e.g., a refund or dispute path among the siblings).

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