GetMyData

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

Beyond the destructiveHint and idempotentHint annotations, the description explains concrete outcomes: delivered rows remain available, the order settles as partial, the undelivered share is refunded pro rata to the original payment method, and the person is emailed. It also instructs the agent to tell the person the refund amount shown in collection.refund first, which is operationally important context.

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

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

The description is dense but front-loaded with the explicit-use condition, then states the key side effects and the refund-message instruction. Every sentence carries actionable information without repetition.

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

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

For a destructive, idempotent cancellation tool with no output schema, the description covers the trigger condition, required order status, side effects, refund behavior, and user notification well. The main gap is that it leaves order_capability and idempotency_key semantics unaddressed despite low schema coverage.

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 only 33%, and the description does not explain order_capability or idempotency_key. It provides useful order state context around order_id, but it does not compensate for the undocumented parameters.

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

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

The description uses a specific verb and resource: stop continued collection of a guaranteed-N order whose get_order status is collecting. It also states the required order state, making the tool's purpose distinguishable from siblings such as get_order or cancel_request.

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

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

The description gives a clear gating condition: only when the person explicitly asks, and only when the order status is collecting. It does not name an alternative sibling tool or spell out when-not cases beyond the prerequisite status, so it falls short of full alternative 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 already cover the safety profile (destructiveHint=true, idempotentHint=true, readOnlyHint=false), so the bar is lower. The description still adds real behavioral context beyond them: coupon release side effects and the fact that paid orders fail and must go to support.

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

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

Two sentences, no waste, with the eligibility constraint front-loaded before the paid-order exception.

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?

Eligibility and side effects are covered and annotations handle safety, but for a destructive mutation with four undocumented required parameters and no output schema, the description leaves concurrency semantics and parameter meaning unexplained.

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 0% across four required parameters, so the description carries the full burden, yet it explains none of them. request_capability and expected_revision in particular are opaque – an agent gets no hint that expected_revision is a concurrency guard or what a capability token is.

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 (cancel) and resource (request) plus a scoping condition: only unpaid requests where payment has not started. It does not name the closest sibling, cancel_collection, so an agent can't distinguish those two purely from the description.

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

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

The description gives a clear positive condition (unpaid, payment not started) and an explicit exclusion (paid orders require support), which is real when-to-use guidance. It stops short of naming cancel_collection as the alternative for collection-level cancellation.

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

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

Annotations already declare the mutation is non-destructive, idempotent, and closed-world, so safety is covered. The description adds real value by explaining the redundancy with start_order, but says nothing about revision-mismatch behavior, failure modes, or what confirmation changes downstream.

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

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

Two tight sentences with no filler; the purpose comes first and the follow-up routing second. The phrase 'for quote_id and revision' is slightly opaque but earns its place by naming the key inputs.

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 mutation with five required parameters, 0% schema coverage, and no output schema, yet the description explains only two of the five inputs and no return behavior. An agent still cannot determine what request_id, request_capability, or idempotency_key should contain.

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 0%, so every one of the five parameters is undocumented in structured fields. The description only touches quote_id and implies expected_revision; request_id, request_capability, and idempotency_key (with its 32-char minimum) are left entirely unexplained.

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: 'Record final quote confirmation' for a given quote_id and revision. It also distinguishes itself from the sibling start_order by noting that start_order can record the same selection, which lets an agent tell the two apart.

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

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

Gives explicit sequencing: 'Use start_order next', and clarifies that start_order also records this selection if not already confirmed, which effectively tells the agent this step can be skipped. It stops short of listing exclusions such as when a quote is not eligible to be confirmed.

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, is idempotent, and is non-destructive; the description adds important behavior beyond that. It explains the asynchronous quote preparation, that the quote is emailed with a payment link, and that the agent must poll get_request on a schedule rather than in a loop.

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

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

The description is compact and front-loaded, with three dense sentences and no wasted text. The core action, asynchronous behavior, polling warning, and next steps are all stated efficiently.

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

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

The description explains the asynchronous workflow and next tools well, which matters because there is no output schema. However, with five parameters and zero schema description coverage, it does not provide enough parameter context for fully reliable invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, but it only clarifies sample_id and revision. It leaves request_id, request_capability, and idempotency_key unexplained despite being required for invocation.

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 and resource: confirm the current immutable sample_id and revision and request a fixed quote. It is clear what the tool does, but it does not explicitly distinguish this from the sibling confirm_quote tool.

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

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

The description gives clear workflow guidance: the quote is prepared asynchronously, check get_request on a schedule and never in a loop, and after the final quote use start_order or create_order. It names alternatives for the next step but does not state when to choose confirm_scope over confirm_quote.

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 the safety profile (not read-only, idempotent, non-destructive), and the description adds meaningful operational context beyond them: the mandatory human-in-the-loop payment step ('Never submit payment for them'), the need to persist order_id and order_capability before sharing confirmation_url, and the session-loss recovery path via get_order. This is strong supplemental disclosure.

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

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

The purpose and code-handling guidance are reasonably front-loaded, but the confirmation_url instruction is split and partly repeated ('Give confirmation_url to the person to review codes and pay themselves' then 'before passing confirmation_url to the person'). Efficient enough but with redundancy that 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 7-parameter order tool with low schema coverage and no output schema, the description covers the human payment workflow and post-payment recovery well, but leaves most required parameters (quote_id, expected_revision, idempotency_key, capabilities) unexplained. It is adequate on process but incomplete on inputs.

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 only 14% across 7 parameters, so the description must compensate but largely does not. It explains coupon_codes semantics (renewal/referral/channel codes and valid/invalid status), but leaves quote_id, expected_revision, request_id, request_capability, and idempotency_key entirely undocumented. Most parameter meaning is missing.

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 conveys that this prepares an order for the final quote, adds coupon codes, and yields a confirmation_url for the person to pay. But the opening verb 'Read or update the order' is muddled against the name create_order and title 'Prepare order,' and it never differentiates this from siblings like start_order or confirm_quote. Purpose is inferable but not crisp.

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 explicit procedural guidance: pass coupon codes before payment starts, hand confirmation_url to the person, and never submit payment on their behalf. It also routes to the alternative get_order 'after payment, even if the original session is lost.' It stops short of stating when to choose this over start_order/confirm_quote, but the when/when-not framing is largely present.

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

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

Annotations only cover the read-only/non-destructive surface; the description adds genuinely non-obvious behavior: XLSX returns base64 bytes with a content type, all rows pages for one file count as a single token use, a full download counts once each, and the token is bound to the current session. Those are quota and auth semantics an agent cannot infer elsewhere.

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 action and precondition, then formats, then quota/failure handling. Nearly every sentence carries distinct information, though the format enumeration is dense and could be tightened by grouping the extra.* variants.

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 heavy lifting on return format for XLSX and for the rows/fields pages, and covers quota, session binding, and token refresh. It is slightly thin on what the plain list and rows responses actually contain and on offset/limit paging semantics.

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 only 20% (only order_id is documented), so the description must compensate; it does by mapping every enum value to a meaning (list vs rows vs json/csv/xlsx, plus the paid excess-rows extra.* variants) and flagging the base64 encoding for XLSX. However, limit and offset paging parameters are never explained, leaving two of five parameters undocumented in both places.

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 concrete verb+resource pair: list files or read rows for a paid order using a delivery token. It also enumerates the output formats (json, csv, xlsx, fields.json, extra.*) so the agent knows exactly the kind of content this returns, which distinguishes it from get_order and get_payment_status in the sibling set.

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 precondition ("After payment"), an explicit failure branch ("On expiry or download_limit, call get_order with your order capability for a fresh token"), and a recovery path when the session itself is gone (initialize a new session, then get_order). The alternative tool is named, not implied.

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

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

Beyond the readOnly and idempotent annotations, the description discloses credential sensitivity, session-expiry behavior, token renewal semantics, post-refund add_on behavior, token scope limited to extra.* files, and how delivery.rows_url/null and 410 responses behave. These are substantial behavioral details an agent could not infer from the annotations or schema.

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 front-loaded with the primary action and credential requirement, then covers important edge cases. The latter half is dense and field-specific, but most sentences carry non-obvious behavioral information rather than 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?

There is no output schema, so the description must carry return-value semantics, and it does explain key fields and behaviors such as add_on, next_action, delivery_available, and rows_url. It could still be clearer about the overall returned order-status structure and error cases, but it is strong for a complex read tool.

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 only 50%, and order_capability has no schema description, so the description meaningfully compensates by explaining it is the credential saved at order creation, that it must remain private, and that it is session-related. The order_id parameter is already well described in the schema, so the remaining gap is minor.

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 and resource: read paid order status and obtain or renew a delivery token using the order_capability from order creation. This is clear and actionable, though it does not explicitly distinguish itself from the sibling get_payment_status, which could also plausibly return payment status.

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

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

It clearly explains the session requirement, that a new valid session can be used if the original expired, and that email recovery is not available. It also implies routing to fetch_delivery when add_on.delivery_available is true, but it does not give explicit when-not-to-use guidance or compare directly against alternatives like get_payment_status.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety behavior is covered. The description adds useful conditional behavior: after payment it returns coupon notifications and a separate delivery token when files are ready. It still omits auth requirements, error behavior, and what happens in non-payment states.

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 only two sentences and contains no obvious filler. It is front-loaded with the checking action, though the second sentence is a dense conditional return description that could be clearer.

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 read-only tool with two required parameters and no output schema, the description should explain parameter meaning and return behavior more fully. It partially describes returns (coupon notifications, delivery token) but does not explain request_capability or clarify when this tool should be used instead of its many siblings.

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 0%, and both request_id and request_capability are required parameters. The description never mentions either parameter, so it provides no meaning or format guidance beyond the schema names themselves.

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 uses a specific verb ('Check') and names several statuses it verifies: email verification, order creation, and verified payment status. It also states that it returns coupon notifications and a delivery token. However, it does not distinguish this tool from close siblings like get_order or get_request, and it blends payment status with broader workflow statuses.

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 guidance on when to use this tool versus alternatives, despite many sibling tools covering related workflows such as verify_email, get_order, and get_request. The post-payment mention implies one context, but it does not state exclusions or routing conditions.

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 clear. The description adds the useful detail that no payment credentials are required, which is behavioral context beyond annotations, but it does not cover other traits like rate limits or response 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?

The description is a single, front-loaded sentence that conveys the key action and a notable constraint with no wasted words.

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 0% parameter description coverage, the description should do more to explain the two required parameters and clarify when this tool is preferred over confirm_quote or get_request. It provides only a minimal high-level purpose and one constraint.

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 0%, and the description does not explain either request_id or request_capability. For a tool with two required, undocumented parameters, the description fails to compensate for the schema gap.

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 ('Read') and resource ('quote or estimated waiting time'), making the tool's core purpose clear. It does not explicitly differentiate from the sibling confirm_quote, but the phrase 'without payment credentials' hints at a pre-payment retrieval use case.

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 through 'without payment credentials,' suggesting this is for obtaining a quote before payment. However, it gives no explicit when-to-use guidance, no exclusions, and does not name the alternative confirm_quote.

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, but the description adds important behavior: the person is emailed on every result and the agent should never loop when waiting. These are valuable operational constraints beyond the structured annotations.

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

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

The description is front-loaded with the read action and remains compact, with each sentence carrying operational content. It is slightly dense but does not waste space on restating the title or annotations.

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

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

For a tool with two required undocumented parameters and no output schema, the description leaves critical gaps: request_id and request_capability are unexplained and the return shape is only partially implied. The behavioral guidance is helpful, but the definition is not complete enough for reliable invocation without external knowledge.

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 0% and both parameters are required, yet the description says nothing about what request_id or request_capability mean, where to obtain them, or how they affect the call. With no schema compensation, an agent lacks essential invocation details.

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 read operation and lists the main data returned: current request, questions, sample, and next action. It does not differentiate from siblings such as get_order, get_payment_status, or get_quote, so an agent cannot fully tell which retrieval tool to choose without more context.

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 some conditional guidance, such as how to handle accepted payment reminders and what to do when next_action is wait with suggested_check_after_seconds. However, it never says explicitly when to use this tool instead of related siblings like get_order or get_payment_status.

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

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

The description adds substantial behavior beyond the annotations: it says to save the returned header/token, defines a 7-day session validity, a 7-day extension limit per refresh, a 30-day hard lifetime from initialization, and clarifies that request/delivery expiries are unchanged. This is rich lifecycle context that the annotations alone do not provide.

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

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

The description is compact and front-loaded: the trigger condition and action come first, followed by the operational details about saving the token and the lifetime limits. Every sentence carries relevant information.

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

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

For a one-parameter tool with no output schema, it covers the session lifecycle, extension limits, and the need to save the returned header/token. Its main omission is the required idempotency_key parameter, which is not addressed anywhere in the description.

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

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

The schema has one required parameter, idempotency_key, with 0% description coverage, and the tool description never mentions it. With low schema coverage, the description should explain how to generate or reuse the idempotency key, but it leaves that parameter undocumented.

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 uses a specific verb and resource: renew the session before expiry using the current Mcp-Session-Id. This is precise and distinguishes it from the order/request/quote sibling tools, none of which manage sessions.

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 states when to use the tool: before session expiry. It does not name alternatives or explain what to do after expiry, but there are no obvious sibling alternatives for session renewal.

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 idempotent=true and destructive=false; the description adds the critical behavior beyond them — existing samples and quotes are replaced, and revision must be based on the current expected_revision. It still doesn't state what happens to omitted optional parameters (whether they reset), which matters for a full-replace revision.

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 sentences, each carrying distinct information: what it does, the replacement side effect, and the trigger condition. The side-effect warning is placed before the routing hint, which is the right order.

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 19-parameter, no-output-schema, open-world mutation, the description covers revision semantics, precondition, and selection criteria. The remaining gap is whether optional fields are cleared on revise, which the schema does not resolve either.

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 63%, and the description compensates by explaining the semantics of the key parameter (expected_revision must be current) and the full-set-of-fields expectation, which clarifies that this behaves like a replace rather than a patch. It doesn't address the optional fields' reset behavior, leaving a real ambiguity.

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 (revise) plus the constrained resource (an unpaid request) and the mechanism (expected_revision with the full set of required fields). It also distinguishes from siblings implicitly by scoping to unpaid requests, versus submit_requisition for new ones and confirm_quote/start_order for later stages.

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: use it when next_action is revise, including the no_capability reason_code path with guidance to try other sources or fields. It does not name the sibling to avoid (submit_requisition) for a request that was never submitted, so it is not fully routing-complete.

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 readOnly/openWorld/idempotent flags; the description adds the re-verify window, the attempts_exceeded/resend_after rate-limiting concept, the rule that human_email is editable only pre-verification, the escalation to support after one retry, and what the email does and does not contain (no price or payment link). That is substantial 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?

Purpose is front-loaded and each clause does work (trigger, timing, edit constraint, escalation, email content). The single dense paragraph makes the operational instructions harder to scan than bullet-style structure 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 stateful, side-effecting send step with no output schema, the description covers what happens, when it must happen, failure recovery, and what the recipient receives. The remaining shortfall is undocumented required parameters, which matters given zero schema coverage.

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?

With 0% schema description coverage the description must carry parameter meaning, but it only explains human_email ('may be corrected only before it is verified'). request_id, request_capability, and idempotency_key are never characterized, so an agent must infer their purpose from naming alone.

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: 'Send (or resend) the one-time code that verifies the person's email for this request.' The send-vs-verify distinction is unmistakable against the sibling verify_email, and the parenthetical clarifies the resend case.

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

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

Explicit trigger: 'Use when next_action is start_email_verification' followed by the exact state enumeration (not_sent, unavailable, expired, replaced, attempts_exceeded after resend_after). It also states the lifecycle points where it is required (before the sample, again before payment if older than the re-verify window).

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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds real value by naming the returned artifacts (order_id, order_capability, confirmation_url) and stating the human must receive the link, but it omits failure modes, concurrency behavior tied to expected_revision, and why order_capability must be retained.

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 dense with no filler, but it is front-loaded with procedural steps instead of the tool's action, and the imperative 'Save order_id...' is agent coaching rather than tool documentation. The parenthetical '(no second code)' is compact and 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?

It partially compensates for the absence of an output schema by naming three return values, which is genuinely helpful for a mutation tool. But with six undocumented parameters, a concurrency-sensitive expected_revision field, and no statement of what the call mutates, the definition is not complete enough for an agent to invoke it confidently.

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 0% across six parameters, so the description carries the full burden and largely fails. Only 'final quote' (quote_id) and 'verified email' (human_email) are obliquely referenced; request_id, request_capability, expected_revision, and idempotency_key are never explained, leaving half the required inputs semantically opaque.

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 text reads as a workflow script ('Select the final quote and read the human confirmation link...') rather than a statement of the tool's action; the actual operation (starting an order from a quote) is only inferable from the title. With siblings like create_order and confirm_quote present, no sentence distinguishes this tool from them.

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 hints at a precondition (a verified email, 'no second code'), which is a useful usage cue, but there is no explicit when-to-use, when-not-to-use, or naming of any alternative. An agent cannot tell from this why it should call start_order rather than create_order or confirm_quote.

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 far beyond the annotations: free sample first, one-off payment by the person, no signup, async sampling, results emailed, capability must be stored privately, and that invalid input fails with HTTP 422 error.missing/error.invalid and is not clarified. Also discloses legal responsibility and prohibited data (passwords, cookies, session tokens).

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 purpose and the free-sample model, and nearly every sentence carries operational value. It is long and interleaves legal boilerplate with the calling workflow, which would be better grouped, but there is 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?

For a 16-parameter, 11-required, async submission tool with no output schema, it covers the verification handshake, async sampling, email delivery, error semantics and capability handling. It stops short of telling the agent what to do next (quote/order/fetch siblings) or what the response contains.

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%, and the description reinforces the required-field contract and tells the agent to derive search_keywords itself, which is actionable semantics beyond the schema. However it enumerates only 8 required fields and omits human_email, row_commitment and idempotency_key, which are also required 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 — 'Request public web data as rows' — plus a disambiguating condition ('when browsing it yourself is impractical'). It does not name any sibling (e.g., revise_requisition for changing an existing request), so it stops 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?

Gives clear process context: collect all fields before calling, generate search_keywords yourself, the person must verify email before the sample is shown. It never states when to use a sibling instead or what to do if the request must change later, so no explicit exclusions.

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

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

Annotations already cover the safety profile (not read-only, not destructive, closed-world), and the description adds real context beyond them: the otp_invalid failure mode with attempts_remaining, the downstream consequence of success (sample visibility or order confirmation link), and the fact that results arrive by email. It doesn't explain what idempotency_key protects against, which matters for a mutation.

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

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

Three tight sentences with the action front-loaded and no filler. The middle sentence is dense with domain shorthand ("the sample becomes visible", "at quote time") that costs some parseability but carries genuine information.

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

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

Behavior is described well, but with no output schema and 0% parameter coverage, an agent still cannot construct a valid call without guessing at request_capability and idempotency_key. For a four-required-parameter mutation, the definition should document those inputs.

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 0% across four required parameters, so the description carries the full burden — and it only indirectly covers otp ("the code the person read"). request_id, request_capability, and idempotency_key are completely unexplained in both schema and description; an agent has no way to know what request_capability is.

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?

A specific verb and resource: submit the emailed one-time code to complete verification. It clearly positions the tool as the second half of the email-verification flow, distinct from start_email_verification, though it never names that sibling explicitly.

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

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

"Submit the code the person read from their email" implies the precondition that a code must already exist, but the prerequisite step (start_email_verification) is left to inference. The one explicit routing hint — use get_request later rather than polling — points at a different tool, not at when to choose this one over alternatives.

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