acp-sandbox

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 mutation profile is covered. The description adds the one thing annotations cannot express — that no charge is incurred — which is the key consequence an agent needs; it does not say what happens to the checkout state afterwards, which would have made it a 5.

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

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

Two short sentences, zero filler, with the action stated first and the reassuring consequence second. Nothing to trim.

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 cancel tool with no output schema and reasonable annotation coverage this is close to adequate, but it omits the resulting checkout state, behavior on non-open/already-completed checkouts, and any session_id sourcing guidance.

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%: api_key is documented in the schema, but session_id has no description and the tool description does not compensate at all — it never mentions what a session_id is, where to obtain it, or that the api_key is optional when the connection carries one.

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 ("Cancel an open checkout") and scopes it to open checkouts, which implicitly separates it from complete_checkout and get_checkout. It does not explicitly name siblings, so it stops short of the top score.

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 "open" qualifier and by the sibling set, but there is no explicit when-to-use/when-not guidance (e.g. what to do if the checkout is already completed or expired) and no prerequisites are 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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that: the PayPal capture happens before the order, and the order only commits if the exact total is confirmed — a conditional-success behavior an agent cannot infer from annotations.

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

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

Three short sentences, front-loaded with the core action, then the default paypal path, then the testing escape hatch. 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?

For a 3-param mutation with no output schema and full annotation coverage, the description covers the critical behavior (conditional order placement, payment capture sequencing, mock caveat). It stops short of saying what a successful call yields or what happens on PayPal rejection, but nothing essential to invoking 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 coverage is 33%, so the description has real work to do; it explains both enum values for "payment" (capture-and-verify vs. test-only mock), which is meaningful added meaning. But the required "session_id" parameter is left entirely unexplained in both schema and description, so compensation is only partial.

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?

"Place the order" gives a concrete verb+resource that reads clearly as the terminal step distinct from create_checkout/cancel_checkout/update_checkout siblings. It never names those siblings explicitly, so differentiation relies on the verb rather than an explicit 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?

The description implicitly establishes the prerequisite (an approved PayPal payment) and states that "mock" is for testing only, which helps an agent pick a payment mode. However it never says when to call this versus create_checkout or cancel_checkout, nor what to do if the payment is not yet approved.

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 (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the description's job is to add what they don't say. It does: it names the return payload (session id, cart, total) in the absence of an output schema, and it discloses the side effect that a sandbox API key is minted when none is supplied. It stops short of warning that a second call creates a new session rather than resuming one.

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 action and inputs, then returns, then the conditional api_key behavior. 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, the description usefully summarizes the return values, and annotations carry the mutation safety profile. The remaining gap is lifecycle context — whether the session must be subsequently completed or can be abandoned, and whether repeated calls duplicate sessions.

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 three parameters are already documented in the schema, including that product_id comes from list_products and what api_key means. The description's mention of products, quantities, and the api_key fallback largely restates that; 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 ('Start a checkout') and expands the concept into 'Agentic Commerce Protocol checkout session' with the inputs it takes and values it returns. It doesn't explicitly contrast itself with siblings like get_checkout or complete_checkout, but the create-vs-read-vs-complete split is self-evident from the resource framing.

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 the usage context ('with the products and quantities the user wants') but never states when to prefer this over alternatives or what prerequisite state is needed. There is no explicit 'call get_checkout to poll' or 'then call complete_checkout' routing, so the agent must infer the lifecycle from sibling names.

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 and openWorldHint=false, so the safety profile is covered. The description adds useful context about what checkout data is returned, but it does not mention authentication requirements or the optional api_key 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 with no wasted words. It is appropriately concise for a simple read operation.

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, but the description partly compensates by naming the returned checkout fields. However, it leaves the required session_id undocumented and provides no usage context, leaving clear gaps for an agent selecting and invoking the 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 description coverage is only 50%: api_key is documented in the schema, but the required session_id has no description. The tool description mentions no parameters at all, so it does not compensate for the undocumented required parameter.

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, 'Read', and resource, 'checkout', and enumerates the retrievable fields: cart, total, payment status, and order. It is clear what the tool does, though it does not explicitly contrast itself with sibling tools like update_checkout or complete_checkout.

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 no guidance on when to use this tool versus alternatives such as update_checkout, cancel_checkout, or complete_checkout. It also does not state prerequisites or when not to use it.

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 and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it says 'everything' (no pagination/filtering), and discloses that results carry product ids and prices denominated in USD — useful because there is no output 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?

Two short sentences, front-loaded with the resource scope, followed by the concrete return content. Nothing is repeated from the title and no sentence 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?

For a trivial zero-param read tool with no output schema, the description covers scope, returned fields, and currency. Minor gaps remain: no mention of what an empty catalog returns or result ordering, but nothing an agent would need 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?

The tool takes zero parameters and the schema is empty, so the baseline of 4 applies. The description correctly implies no filtering arguments exist, consistent with the empty 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 (list the store's products) and even names the fields returned (ids, prices) plus the currency. It does not explicitly contrast with siblings, but the siblings (create_checkout, wait_for_payment_approval, etc.) are all checkout-flow tools, so confusion risk is minimal.

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-to-use or when-not-to-use guidance. For a zero-parameter catalog listing called from a checkout flow, the appropriate moment to call it is strongly implied but never 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, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description usefully adds that it is sandbox-only and returns the approve_url, but does not clarify the consequence of the non-idempotent hint (e.g., whether repeated calls create duplicate payments) or error 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?

Two tight sentences with zero waste, front-loading the action and the amount scoping before the return value. Nothing extraneous.

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 small mutation tool with annotations covering the behavioral flags and no output schema, the description explains the key return value (approve_url) and the exact-total behavior. Minor gaps remain around duplicate-call behavior given non-idempotency and what happens without api_key, but it is largely 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 description coverage is only 50%: the api_key parameter is documented in the schema, but session_id has no description anywhere. The description never references either parameter and only loosely implies that the amount is derived from the checkout tied to session_id, so it does not compensate for the coverage 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?

States a specific verb and resource ('Create a PayPal (sandbox) payment') and scopes it to the checkout's exact total, plus declares the key return value (approve_url). It is distinguishable from siblings like complete_checkout or wait_for_payment_approval by naming PayPal and the approve link, though it does not explicitly contrast with 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?

The phrase 'for the checkout's exact total' and the approve_url return imply this is the step that produces the user-facing payment link, giving some flow context. However, there is no explicit when-to-use vs siblings (e.g., when to call this instead of complete_checkout or wait_for_payment_approval), nor any exclusions or prerequisites beyond sandbox.

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 mark the tool as destructive and idempotent. The description adds critical context: that any PayPal payment for the old total is dropped. This discloses a specific destructive consequence not apparent from the annotations alone, though it does not mention permission requirements or rate limits.

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: the first front-loads the core action, the second adds a key side effect. No wasted words; every sentence earns its place.

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

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

The description conveys the main purpose and a critical destructive side effect, but it omits important contextual details: it does not clarify that the session must be open, does not mention the replacement of all existing items, and does not address the required parameters given sparse schema documentation. For a destructive mutation tool, more guidance would be helpful.

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 provides no information about the parameters. It does not explain the session_id, the items structure, or the optional api_key. With such low coverage, the description should compensate but does not.

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 ('Replace') and resource ('items in an open checkout'), making it clearly distinct from create_checkout or get_checkout. It gives an example of when this might be used, but does not explicitly name a sibling tool to contrast with.

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

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

The parenthetical 'e.g. the user changed their mind' implies a use case, but there is no explicit guidance on when to use this tool versus alternatives like create_checkout or cancel_checkout. The reader must infer that this is for modifying an existing open session.

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 and openWorldHint=true, and the description adds genuinely new behavioral facts: the call blocks for up to 45 seconds and returns a non-terminal still_waiting status instead of failing. It does not state whether waiting can time out permanently or what happens on the approval side after repeated polls.

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, zero filler, with the blocking constraint and the non-approval outcome front-loaded. Nothing could be removed without losing 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?

No output schema exists, so the description must describe return values, and it only names the still_waiting case. An agent still does not know the success payload or what to do after a still_waiting result on a read-only, open-world polling 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 description coverage is only 33%: api_key is documented in the schema, but session_id is undocumented in both schema and description, and timeout_seconds is only implied by the '45s per call' phrasing. The description partially compensates by tying the wait window to the timeout cap but adds no meaning for the required session_id.

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 (wait) plus the exact external condition (PayPal reports user approval) and the polling window. This is clearly the polling/waiting tool among siblings such as complete_checkout and request_paypal_payment, though it never names an alternative 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?

'Wait (up to 45s per call)' and the still_waiting return value imply a retry loop, which is useful context, but it does not say when to call this versus complete_checkout, nor whether to re-invoke after a still_waiting result. Usage 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.