Printdash

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

Goes well beyond the annotations: clarifies that nothing is ordered or charged, that checkout re-prices, that a failed pricing attempt adds nothing and returns what is missing or nearest combinations, and that a signed-in account is required (unauthenticated calls prompt sign-in). It also discloses the AU-only print/delivery scope and AUD/GST pricing, which no structured field carries.

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

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

Four sentences, front-loaded with the core action before the failure, billing, and auth context. Dense and largely waste-free, though the AU-shipping/currency sentence is scope trivia that could be trimmed without hurting invocation correctness.

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

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

With an output schema and rich annotations already present, the description fills the remaining gaps an agent needs: auth requirement, side-effect boundary (cart only, no charge), failure semantics, and regional/currency constraints. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 50% and the nested configuration is extensively self-documented in the schema. The description adds the useful pointer that option ids follow price_job's format, but gives no field-level guidance of its own, so it hovers at the baseline for a partially documented 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: prices a job with the pricing engine and puts it in the cart. It distinguishes itself from the sibling price_job by saying the configuration is 'as price_job takes them' and notes it mirrors the product page's Add to cart action, so an agent can tell exactly what this does versus the pure-pricing 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?

Explicitly states the failure path ('if the job cannot be priced, nothing is added') and what is not covered ('checkout on printdash.io re-prices, takes artwork and payment'), which effectively routes artwork/payment work to other tools. It does not name update_cart_line, remove_cart_line or clear_cart as the follow-up alternatives, so the routing picture is slightly incomplete.

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, openWorldHint=true and non-idempotence, and the description adds real context beyond them: role gating, the sign-in requirement with the on-the-spot auth prompt, and the differing downstream effects for on-account vs card orders. However, it does not reconcile the destructiveHint=true annotation with its own claim that 'nothing is decided' at this step, leaving ambiguity about whether this call alone mutates anything.

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 actor and the action ('For a Team owner: prepares approving...'), and every clause carries information. The single dense paragraph mixes audience, mechanics, side effects and auth, which is a lot for one block but nothing is genuinely 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 one-parameter, output-schema-backed preparation step, an agent has everything needed: who may call it, where the order identifier comes from, the auth behavior, and what happens on confirm. Return values are covered by the output schema and briefly previewed 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?

Schema coverage is 100% for the single 'order' parameter, so the baseline is 4. The description only adds that the identifier should come from list_pending_approvals, which is a useful pointer but not new syntax or format detail.

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

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

States a specific verb and resource ('prepares approving one held order') plus the two artifacts it returns (summary, confirmation_token). It also names the source sibling (list_pending_approvals) and the completing sibling (confirm), so an agent can distinguish it from reject_order and confirm 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?

Explicit preconditions and exclusions: Team owner role required, order must come from list_pending_approvals, and 'Nothing is decided until confirm is called after they agree' defines the hand-off to confirm. It also names a when-not case ('A member who is not an owner cannot approve').

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 substantial context beyond the annotations: it discloses that an existing file in that slot is replaced (matching destructiveHint=true), that page 1 and 2 previews are generated, that Printdash file checks run and their notices are returned but never block an order, and that a signed-in account is required with a specific unauthenticated behavior. That is exactly the kind of side-effect and auth detail 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?

Two sentences, front-loaded with the prerequisite PUT step, then the effects. Dense but every clause carries information; the parenthetical about design/side and replacement is the only slightly packed section.

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?

Even though an output schema exists, the description still summarizes the return (preview image plus check notices) and clarifies that notices are the same ones checkout shows and are non-blocking. Auth requirements, side effects, and the upstream dependency are all covered, leaving no gap for a destructive single-param mutation.

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 there is a single parameter whose description already says it is 'the upload_id request_artwork_upload returned.' The prose reinforces the handoff from that tool but adds no new format, constraint, or semantics beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb and resource ('puts it on the line', 'Attach an uploaded file to a line') and anchors it to the request_artwork_upload flow, which cleanly separates it from siblings attach_artwork_from_url and attach_artwork_inline. An agent can tell which of the three attach tools applies without opening a schema.

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

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

Gives a clear precondition ('After the file has been PUT to request_artwork_upload's upload_url'), which tells the agent both when to call it and which tool must run first. It never names the alternative attach tools or states when-not to use it, so it stops short of 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?

Adds substantial behavior the annotations don't carry: a 700 MB limit, refusal of HTML pages and mismatched content/extension, the auth requirement that prompts the customer to sign in on printdash.io, and the Canva-specific bleed handling. These are exactly the traits an agent needs before invoking a destructive, open-world operation.

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

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

Front-loaded with purpose and target semantics, then constraints, then the Canva special case, then auth – a sensible order. It is a single dense paragraph, which costs a little readability, but no sentence is redundant.

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 an output schema and fully documented nested params, this covers everything an agent needs: source format constraints, size cap, failure modes, auth requirement, and the exception that applies to Canva exports.

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 100% schema coverage the baseline is 3, but the description adds genuine meaning: when file_name is required (link's own name has no extension) and the mandatory canva-<designId>.pdf convention Printdash uses to recognise Canva exports. That naming rule is not derivable from the schema and materially affects correct 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?

States a specific verb and resource ('fetches the file at an https link ... and attaches it') and explicitly differentiates from the sibling attach_artwork by being URL-based. An agent can tell this apart from attach_artwork_inline (local bytes) and attach_artwork 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 https-link constraint plus the 'like attach_artwork' reference routes the agent: use this when the artwork lives at a URL. It also explains the rejection cases (page link instead of file, extension mismatch), which is real usage guidance. It stops short of naming attach_artwork_inline explicitly as the alternative for local files, so routing to that sibling relies on 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 declare destructiveHint=true and non-idempotent, and the description adds real operational context the annotations don't: the 10 MB decoded limit and the auth flow (without a signed-in Printdash account the connection prompts sign-in on printdash.io). It does not say whether attaching replaces or removes existing artwork, which is exactly what destructiveHint=true implies – that is the one missing piece.

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 audience restriction, then payload mechanics, then auth, with nothing padded. Slightly dense for two-and-a-half sentences, but each clause carries a distinct constraint.

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 a full output schema and 100% input coverage, the description only needs to add the non-schema facts, and it supplies the two critical ones: size limit and auth requirement. The remaining gap is the destructiveness semantics of an artwork attach.

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 target/file_name/data_base64 are already fully documented including side, design and kind enums. The description only restates the extension requirement on file_name and the 10 MB ceiling on data_base64, adding little beyond 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 ('attaches a file sent as base64 in data_base64') and scopes it to programmatic clients, immediately separating it from attach_artwork, attach_artwork_from_url and get_artwork_uploader_link. An agent can route between them 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?

Explicit when-to-use (programmatic clients, inline base64 up to 10 MB, same target/file_name signature as attach_artwork) and explicit when-not ('Never paste a file a customer dropped into a chat here'), with the two named alternatives to use instead. No inference required.

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, it discloses the two-phase safety design (no cancellation until confirm), the token handoff, the eligibility preconditions, and the auth requirement (a signed-in Printdash account, with the connection prompting sign-in on printdash.io). The destructiveHint=true annotation is conservative for a preparatory call, but the description explains the flow rather than contradicting it.

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

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

Four short sentences, front-loaded with the two-step contract, then eligibility, then auth. Every sentence carries information an agent needs; there is no restatement of the title or schema.

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 tool has an output schema, so return values need no prose, and the description covers what remains: preconditions, auth, the confirmation token handoff, and the non-cancelling behavior of this call. 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 coverage is 100% for the single 'order' parameter, whose schema description already explains that it accepts an order number or an id from its link. The description adds nothing further about the parameter, 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 description states a specific verb and resource ('Prepares cancelling one order') and immediately clarifies the two-step contract: it returns a summary plus a confirmation_token, and nothing is cancelled until 'confirm' is called. That distinguishes it cleanly from the 'confirm' sibling and from destructive direct-action tools like reject_order.

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 the explicit precondition (customer must agree, then call confirm with the token) and the eligibility gate (only an unpaid order not in production, matching the order page). It also states what happens otherwise ('it says so'), so an agent knows the failure mode rather than guessing.

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 and idempotentHint=true, so the risk profile is covered. The description adds genuinely new context: cancellation requires a signed-in Printdash account and triggers a sign-in prompt on printdash.io if absent. It does not say what state the request lands in or whether it is reversible.

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, both earning their place: the scoping constraint is front-loaded and the auth behavior follows. No filler or restatement of the title.

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

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

An output schema exists, so return values need not be described, and annotations cover safety and idempotency. The auth gating is a useful addition; only the post-cancellation state of the request is left 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?

Schema coverage is 100% for the single `request` parameter, including the helpful note that it accepts the request number or the id from its link. The description adds no parameter-level detail, 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 ("Cancels a custom quote request") and narrows scope to those "still pending review", which distinguishes it from delete_quote or cancel_order. It stops short of naming the sibling that handles non-pending requests, so it is clear but not maximally differentiating.

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 "still pending review" implies the applicable state, and the auth note tells the agent what happens when unauthenticated. There is no explicit when-not guidance or pointer to delete_quote/reject_order for other cases, leaving the agent to infer which sweep is appropriate.

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 past the readOnly/idempotent annotations: it discloses the auth requirement and the exact failure mode ("the connection asks the customer to sign in on printdash.io"), states that the check never blocks an order, explains that unmeasurable items surface as silence rather than errors, and notes each notice carries a guide link. That is precisely the kind of context an agent cannot get from structured fields.

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

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

A single front-loaded paragraph with zero filler — the long middle list of checks is information-dense rather than redundant. It reads slightly run-on (the layer-items list plus the trailing auth sentence), but 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?

Output is covered by an output schema, and the description fills the remaining gaps an agent needs: auth prerequisite and its failure behavior, non-blocking semantics, silence-means-unmeasured convention, and the image preview return. Nothing material to a correct invocation is missing.

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

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

Schema description coverage is 100% and the nested target object (kind/id/side/design) is fully documented, so the description adds nothing about parameters. The phrase "on a line's artwork" loosely maps to the target, but no format or selection guidance is contributed beyond 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 — "Runs Printdash's file checks on a line's artwork" — and enumerates the exact checks (page size vs ordered size, bleed, spot/cut layers, knocked-out finishes, leftover template guides), so an agent knows precisely what it produces. It never names a sibling such as get_artwork_requirements or attach_artwork, so the differentiation is inferred rather than stated.

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: it says it runs "the same ones the product page and checkout show" and "Never blocks an order", which hints at pre-order validation, but there is no explicit "use this instead of X" or precondition beyond being signed in. Alternatives like get_artwork_requirements or get_artwork_guide are not contrasted.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds real context beyond them: saved quotes are untouched, a confirmation step is required for carts the customer did not fill, and authentication is mandatory with a concrete sign-in fallback on printdash.io. This is exactly the extra behavioral detail 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?

Three tight sentences ordered by importance: action, scope exclusion, then safety and auth requirements. No sentence is redundant.

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 destructive mutation, the description covers action, side-effect boundary (quotes preserved), confirmation etiquette, and auth prerequisites, and an output schema exists to explain return values. Nothing material 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, so there is nothing for the schema or description to disambiguate; the baseline of 4 applies. The description correctly signals that the target cart comes from the ambient 'current buying context' rather than an argument.

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 precise verb and resource ('Removes every line from the cart') and scopes it to 'the current buying context', which implicitly separates it from remove_cart_line's single-line scope. An agent can tell exactly what this deletes.

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

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

Gives a clear when-to-use condition plus an explicit caution ('Ask the customer before emptying a cart they did not just fill') and excludes saved quotes. It does not explicitly name remove_cart_line as the narrower alternative, so it falls just short of a 5.

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

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

Beyond the annotations (destructive/idempotent/openWorld), it explains the idempotency contract concretely: retrying with the same key returns the first outcome and never acts twice. It also discloses that a missing signed-in account triggers an interactive sign-in prompt on printdash.io, which is behavior an agent cannot infer from 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 precondition and consent constraint are front-loaded ahead of parameter and auth details, and every sentence carries information. The ten-tool enumeration is long but functionally necessary for routing; slight density cost only.

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

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

With an output schema present, the description need not explain return values, and it still covers preconditions, idempotency, retry semantics, and the auth flow. Nothing an agent needs to invoke this destructive tool safely is missing.

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

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

Schema coverage is 100% and both field descriptions already explain confirmation_token and idempotency_key. The description echoes the same guidance ('pass its confirmation_token and a new UUID') and adds only the provenance link back to the prepare tool, so it contributes marginal value over 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?

The description opens with a specific verb and scope: it 'carries out an action prepared by' a named set of prepare/approve tools, so the agent immediately understands this is the execution half of a prepare-then-confirm pattern. It distinguishes itself from sibling state-changing tools like place_order and approve_order by being the generic confirmation step for tokens those tools return.

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 the precondition explicitly (the customer has seen the summary and said yes), adds a hard exclusion ('Never call it without the customer's agreement'), and enumerates the exact sibling tools whose tokens it consumes. No ambiguity about when to reach for it versus the prepare tools.

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 substantial behavioral context beyond the annotations: no order is placed, a checkout link is returned, only the quote owner can invoke it, every line needs artwork unless priced, and authentication is required. It does not clarify how existing cart contents are affected despite destructiveHint=true, which is the main remaining gap.

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 core action and outcome, then moves through constraints and authentication. Every sentence carries useful information with no wasted wording.

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 mutation tool with annotations and an output schema, this is nearly complete: it covers the action, side effect boundary, return link, permissions, artwork precondition, and auth behavior. The missing piece is clarity about whether existing cart lines are preserved or replaced.

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 only one parameter and schema description coverage is 100%, so the schema already documents that it accepts a quote number or quote id. The prose reinforces that it operates on a saved quote but adds no syntax or format details beyond 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: puts a saved quote's lines in the cart and returns the checkout link. It explicitly distinguishes the outcome from placing an order, which separates it from siblings like place_order and prepare_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?

Clearly explains when this is appropriate via the quote-page conversion analogy and notes that checkout/payment happens afterward. It also lists key preconditions (owner-only, artwork requirement, signed-in account), though it does not explicitly name alternative tools for related cart or checkout steps.

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 carry the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds real value on top: the auth requirement, what happens without an account, and a hard rule against fabricating addresses. It does not warn that repeat calls create duplicate records despite idempotentHint=false.

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 the core action and field set front-loaded, followed by the sourcing rule and the auth caveat. No filler and no repetition of schema 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 an output schema present, return values need no explanation, and the description covers auth, data provenance, field scope and the default option. It is nearly complete; duplicate-creation behavior and the boundary with update_address remain unaddressed.

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 45%, so the description compensates by naming nearly every field in the parenthetical, including format cues ('state code, four-digit postcode'). Minor gaps: address_line2 and the home/business meaning of 'type' are not explained.

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

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

The description opens with a specific verb plus resource ('Saves an Australian delivery address to the address book') and scopes it to 'the current buying context'. It enumerates the captured fields and notes the optional default flag, which distinguishes it from set_default_address and update_address in the sibling list.

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

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

It gives a clear directive on sourcing data ('Collect it from the customer; never invent one') and states the signed-in-account prerequisite, including the fallback sign-in flow. It does not, however, say when to prefer update_address or set_default_address over 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?

Annotations already declare this is a non-read, non-destructive, non-idempotent write, and the description adds genuinely new behaviour: the atomic pricing guarantee ('if a job cannot be priced, nothing is saved'), the 30-day price lock, and the account/auth flow. It also discloses region and currency rules (Australia-only, AUD incl GST), which no annotation covers.

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 capability and the 20-line limit are front-loaded, and the atomicity and pricing-lock facts follow in priority order. The trailing Australia/GST and sign-in sentences are justified but make the block longer than it strictly needs to be for a save 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?

An output schema exists so return values need no explanation, and the annotations cover the safety profile. Against that, the description still supplies the auth prerequisite, the geographic restriction and the failure mode, which are exactly the gaps an agent would otherwise hit at call time.

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 80%, so the schema already documents almost every field and the description only restates the shape ('each a product id and configuration'). It does add the 20-job cap and the intent of address_id, fulfilment, reference and notes, but that mostly repeats the schema. Baseline 3 applies.

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

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

Opens with a specific verb and resource ('Saves a new quote') and immediately scopes it: up to 20 job lines, each a product id plus configuration priced by the engine. That is enough to distinguish it from update_quote, duplicate_quote and convert_quote_to_order 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?

Names the downstream follow-ons explicitly (share_quote, email_quote, convert to an order) and states the prerequisite that the customer must be signed in, including what happens when they are not. It does not give an explicit 'use update_quote instead when...' exclusion, so it is strong context rather than a full routing decision.

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: discloses that deletion is deferred behind a confirmation token, that referenced addresses leave the address book but persist on orders/quotes, that the last address cannot be removed, that the newest remaining address becomes default, and that a signed-in account is required with a sign-in prompt otherwise. That is exactly the kind of side-effect and auth context annotations cannot carry.

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

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

Five tight sentences, front-loaded with the two-phase behavior and the return values, then the edge cases. Dense but no filler; only the printdash.io domain reference is slightly redundant.

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

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

Output schema exists and the description still names what comes back (summary + confirmation_token). Combined with the auth requirement, the last-address guard, and the default reassignment rule, an agent has everything needed to invoke this and follow up with confirm.

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 never names address_id or explains its format, only referring to 'one saved address' and 'the only saved address'. The sole parameter's semantics are left entirely to the bare schema, which is a real gap even though the parameter is a simple 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 and resource ('Prepares deleting one saved address') and immediately frames it as a two-phase operation returning a summary and confirmation_token. This is clearly distinguishable from create_address, update_address, and list_addresses 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?

Explains the required follow-up ('Nothing is deleted until confirm is called with it after the customer agrees'), an explicit exclusion (the only saved address cannot be deleted, use create_address first), and the default-address side effect. When-to-use and when-not-to-use are both covered with a named alternative.

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 this destructive and non-idempotent, and the description adds what actually matters beyond them: nothing is destroyed at this step, a confirmation_token is issued, and the destructive action is deferred to confirm. It also discloses the business-rule refusal case and the auth requirement, which annotations cannot express.

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

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

Four short sentences, front-loaded with the action and the token-return contract before the constraint and auth notes. No sentence is redundant with the annotations or the schema.

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

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

Output schema exists, yet the description still names the two return fields the agent must act on (summary, confirmation_token), covers the eligibility restriction and the auth path. Nothing needed to call this correctly or follow up with confirm is missing.

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

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

Schema coverage is 100% and the single parameter already documents that it accepts a quote number or the id from its link. The description adds no further syntax or format detail, so it neither compensates nor detracts – 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?

Specific verb plus resource ("Prepares deleting a saved quote") with the two-step intent spelled out, and it clearly separates itself from confirm (which does the actual delete) and from cancel/duplicate siblings. An agent can tell exactly what this call does and produces 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?

States the when (customer agrees, before calling confirm), the when-not (accepted and ordered quotes cannot be deleted), and the prerequisite (signed-in Printdash account, with the sign-in fallback behavior described). The routing to confirm is explicit rather than inferred.

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 authentication requirement and the fallback behavior (the connection prompts sign-in on printdash.io), that the original is unchanged, and that every line is re-priced at today's rates — a material side effect for a non-readOnly tool with destructiveHint=false. It stops short of spelling out that a second call yields a second independent quote (idempotentHint=false), which is the one behavioral consequence an agent could still get wrong.

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, each doing distinct work: what is created, what is not carried over / what happens to the original, and the auth prerequisite. Front-loaded with the core action with no preamble.

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 copy operation with an output schema (so return shape needs no explanation) and full annotation coverage, the description supplies everything an agent needs: the identity of the new object, the re-pricing consequence, the artwork exclusion, and the sign-in requirement.

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 the single parameter accepts a quote number or the id from its link. The description adds nothing about the identifier beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource (saves a copy of a quote as a new quote) and immediately pins down the scope: new quote number, lines re-priced today, artwork excluded, original untouched. This clearly separates it from create_quote (build new), update_quote (mutate existing), and get_quote (read).

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

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

Clear context for when this applies — copying an existing quote rather than authoring or editing one — plus an explicit exclusion (artwork is not copied). It does not name a sibling alternative or state when *not* to use it (e.g. use create_quote for a fresh job), so it falls short of a 5.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true): it discloses the two-step confirmation gate, that the first call sends nothing, the exact return payload (summary + confirmation_token), and the sign-in prerequisite including what happens when unauthenticated. That is exactly the behavioral context an agent needs before calling a destructive tool.

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

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

Three tight sentences with zero waste: what it does first, what it returns second, the confirmation gate third, and auth last. The most important constraint (nothing is sent until confirm) is front-loaded in the second sentence.

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

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

Output schema exists and the description still names the two key return values, auth requirements are spelled out, and the destructive action is explicitly gated by confirm. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 60% and the description only adds meaning for the recipient generally ('someone, usually the customer's client'). recipient_name and recipient_business are undocumented in both schema and description, and include_branding's default is only in the schema. Marginal value over the schema, so the baseline 3 fits.

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: prepares emailing a saved quote's public link to a recipient. The parenthetical '(usually the customer's client)' and the mention of the public link let an agent distinguish it from share_quote or convert_quote_to_order 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?

Clearly explains the two-step flow: this call only prepares and returns a summary plus confirmation_token, and nothing is sent until confirm is called after the customer agrees. It names the sibling confirm and the condition that selects it. It doesn't contrast with share_quote, which is the closest alternative for distributing a 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 cover read-only/idempotent/non-destructive, and the description adds real behavioral facts beyond them: prices are in AUD, totals include GST, non-Australian addresses are refused outright, and quoting matches checkout pricing. It does not discuss fee thresholds or whether unpublished/oversized jobs degrade to manual quotes, 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?

Three tight sentences, front-loaded with the outcome before the constraint and currency notes. The mid-sentence clause 'because Printdash delivers within Australia only' repeats the preceding restriction and could be trimmed without loss.

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

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

With an output schema present, return values need no explanation, and the description covers the two things an agent actually needs to decide and call: geography limits and currency/GST treatment. Minor gap: it does not state that partially specified jobs are tolerated and reported back, though the schema covers that.

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

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

Schema description coverage is 100%, so all three parameters are already documented, and the description mostly restates them ('given the jobs being ordered', postcode or saved address). The only added nuance is that the fee depends on the order's value, which is already in the schema's jobs description. 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 outcome: eligibility for an Australian postcode or saved address plus the delivery fee and delivered total for a set of jobs. It distinguishes itself in substance from price_job/prepare_checkout by framing the result as 'priced the way checkout prices it', but it never names the sibling it replaces, so an agent must infer the split.

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: Australian postcodes only, anything else is refused, and signed-in callers may pass address_id instead of postcode. It does not explicitly say when to prefer price_job (job pricing without delivery) or where in the checkout flow this belongs, so the alternative selection 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 the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: a signed-in Printdash account is required and, absent one, the connection prompts the customer to sign in on printdash.io. It also disambiguates the discount_percent semantics (already baked into prices returned by the pricing tools), which prevents double-discounting. Minor gap: nothing about what is returned when parts of the account are incomplete.

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 answer ('Who the signed-in customer is'), and the auth prerequisite is placed last as a closing constraint. It is a long single sentence with heavy parenthetical nesting, which costs some scannability, but each clause carries distinct information rather than restating the name.

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 an output schema and full annotation coverage, the description supplies more than required: auth gating, failure behavior, and discount interpretation. Some of the return-field enumeration is redundant with the existing output schema, which is why it is not a 5, but nothing an agent needs to call it correctly is absent.

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

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

The tool takes zero parameters, so the baseline is 4. The description's field enumeration describes return values rather than inputs and adds no parameter meaning beyond the empty schema, but there is nothing to document.

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

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

The description opens with a specific framing ('Who the signed-in customer is') and enumerates exactly what the tool surfaces: name, company, pricing tier, discount, personal vs Team buying, switchable Teams, and missing account fields. This is unmistakably the account-context tool and cannot be confused with siblings like get_order, list_addresses, or get_referral_summary.

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

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

Usage is implied rather than stated: the mention that discount_percent is 'already in every price the pricing tools return' hints this should be read before pricing, and the sign-in prerequisite is stated explicitly. However, no alternatives or when-not conditions are given (e.g. use list_addresses to see missing addresses, set_context to switch Teams), so the agent must infer routing.

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?

Read-only/idempotent safety is already in the annotations, so the description's value is the mode behavior: list vs. product-specific, per-product sizing, and Markdown output format. It never says what happens if a topic is invalid or how large the returned guide is, which keeps it below 5.

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

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

Two sentences, front-loaded with the resource and output format, then the mode rules. The long parenthetical topic list earns its place for discovery but is slightly padded since the schema's topic description already enumerates ids.

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

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

An output schema exists so return values need no explanation, and the description covers output format and both invocation modes. Missing detail on behavior for unknown topics or whether product_id requires a topic keeps it from perfect.

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 all three parameters plus the nested configuration fields are already documented there, including 'Omit for the list.' The description only reinforces the topic/product_id/configuration interplay, adding little beyond structured fields.

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 ('artwork setup guides as Markdown') and enumerates the covered topics, which makes the tool's content immediately graspable. It doesn't name a sibling (e.g. get_artwork_requirements vs. get_artwork_uploader_link) to draw the line, 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?

Explains both invocation modes clearly: 'Without a topic, the list' and 'With a product (and its configuration), what that product's page says on the topic.' That is real when-to-use guidance, though there is no explicit statement of when to use this instead of get_artwork_requirements or check_artwork.

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 carry the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add behavioural colour. 'The same rules the product page's guide card uses' is a useful consistency guarantee, but much of the rest re-enumerates fields rather than explaining behaviour (e.g. what happens when configuration is omitted, whether results vary by market or time).

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 scope ('What a print-ready file must be for a product and configuration') and has no filler prose, but the ten-item field inventory is a long tail that duplicates what the output schema already declares. The trailing fragment is fine, yet as a whole the sentence is denser than it needs to be for the value delivered.

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

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

An output schema exists and the annotations cover safety, so the definition only needs to establish scope and inputs; it does establish scope unambiguously. The remaining gap is purely the missing routing guidance versus check_artwork/get_artwork_guide, not any missing information about what calling the tool does.

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?

At 50% schema description coverage the description needs to compensate, and it partly does: mentioning 'pages or sides', 'the spot plate names a spot finish needs', and 'accepted file types' signals that configuration options such as pages, sides and finishing ids materially change the output. It does not clarify product_id's source or that configuration may be supplied partially/omitted — the schema's nested description carries that 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 precisely what the tool returns: a spec sheet covering finished size, bleed, safe zone, PDF page size, pages/sides, spot plate names, cut rule, resolution, file types and size limit, scoped to a product + configuration. That is far more specific than the title alone. It loses a point because it never names or contrasts with the close siblings get_artwork_guide and check_artwork, so an agent must infer which of the three to call.

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 when-to-use or when-not-to-use guidance, and no mention of check_artwork (validate an existing file) or get_artwork_guide despite both appearing in the sibling list. The only contextual hook is 'the same rules the product page's guide card uses', which describes provenance rather than the condition for calling 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 readOnly/idempotent annotations: it discloses that the page opens already signed in as the customer's connected browser session, that the call requires a signed-in Printdash account, and that an unauthenticated call triggers a sign-in prompt on printdash.io. It also states the state precondition under which the call fails.

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

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

Front-loaded with what the tool returns, then usage, then failure conditions, then auth — a sensible order with no filler sentences. The opening sentence is a verbless fragment, which costs a little immediacy.

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 nested-target tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what is returned, which page per target kind, the auth prerequisite, the refusal condition, and when to prefer it over in-chat upload. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the semantic mapping behind each `kind` value (cart_line → checkout, quote_line → quote page, order_item → order page), which is more than the schema's parenthetical source hints. It adds nothing on `side` or `design`, but those are already fully documented 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?

Names a concrete resource: the printdash.io-hosted uploader page for a specific line, and enumerates which page it is per target kind (checkout, quote page, order page). It does so with a sentence fragment rather than an explicit verb like "returns a URL", and it does not explicitly differentiate from the attach_artwork* / request_artwork_upload siblings, 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 an explicit triggering condition ("Use it when the customer has the file but the chat cannot send it") that directly discriminates against the attach_artwork* siblings, plus an explicit refusal condition ("Refused when the line's artwork can no longer change"). Both the when and the when-not are stated, leaving nothing 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 readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is fully covered. The description adds genuine value by disclosing the auth requirement and the concrete failure behavior (the connection prompts the customer to sign in on printdash.io), which annotations cannot express — but nothing is said about empty-cart behavior or how the checkout link relates to prepare_checkout.

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

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

Two sentences, front-loaded with what the tool returns and followed by the operational precondition. The field enumeration partially duplicates the output schema, which is mild redundancy, but it still reads 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?

With a rich annotation set and an output schema in place, the description only needs to add auth behavior and scope, which it does. The remaining gap — no mention of the empty-cart case or the relationship to prepare_checkout/place_order — is minor for a zero-parameter 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The phrase "current buying context" usefully hints that the target cart is determined by session/context set elsewhere (set_context) rather than by arguments.

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 the resource precisely ("the cart in the current buying context") and enumerates the fields returned, so an agent knows exactly what it gets. The retrieval verb is only implied by the title rather than stated, but the operation is unambiguous and clearly distinct from list_orders or get_quote.

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 call this versus siblings such as prepare_checkout, update_cart_line, or clear_cart — the agent must infer the moment to read the cart. The only contextual signal is the sign-in requirement, which is a precondition rather than usage routing.

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/idempotent annotations, it discloses the return form (PDF attachment), the non-error failure mode when no invoice exists, and a concrete auth behavior — an unauthenticated call triggers a sign-in prompt on printdash.io. These are exactly the operational traits 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?

The primary output is front-loaded in the first clause, followed by the conditional case and the auth note. Three sentences, all earning their place, though the aside about the order page's Download button is the least essential.

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

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

With an output schema present, the description needn't detail the response body, and it still covers preconditions, auth, and the empty-result case. It leaves open what happens for an invalid or unknown order number (error vs. 'no invoice'), a minor remaining gap for a single-parameter lookup.

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 explains that the order parameter accepts an order number or the id from its link. The description adds only "for one order," so it neither compensates for nor extends the schema — 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 description names the exact resource ("The tax invoice for one order as a PDF attached to the result") and its success/failure semantics (invoice exists vs. "no invoice yet"). It also implicitly distinguishes itself from get_order by noting the order page link has a Download invoice button, so an agent knows this tool is the programmatic path to the same artifact.

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 the prerequisite condition clearly: the order must be invoiced (paid, or approved on a Team account), and tells what happens when that isn't met. It does not explicitly route the agent to an alternative (e.g., get_order for order details), but the invoicing precondition is a strong usage signal.

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/idempotent annotations, it discloses the async render-and-retry cycle with a concrete ~20 second cadence, the cached-results behavior per target kind, the flat-preview fallback when no 3D view exists, and the auth requirement plus what happens without a session. That is exactly the context annotations cannot carry.

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

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

The core return value and the polling instruction are front-loaded in the first two sentences. The auth note is placed last, which is correct priority ordering, though the middle sentence is long and carries several ideas in one clause chain.

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

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

For a single-parameter, nested-target tool with a full output schema, the description covers everything the schema cannot: latency/retry, fallback output, caching, and authentication. An agent could invoke this correctly on the first try.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning by explaining why the target kind matters — an order job vs. a cart/quote line take different render paths. It does not elaborate on side or design, but the schema already documents those.

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 resource (the 3D mockup of a line's artwork on the product) and its delivery form (an image), so the agent knows exactly what it gets back. No sibling tool offers mockups, so there is no ambiguity to resolve, and the three target kinds are distinguished from one another.

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 the operational context clearly: call it for an order job or a cart/quote line, and call again in about 20 seconds if the response says it is still rendering. It does not name an alternative tool or an explicit when-not-to-use case, which keeps it just below the top score.

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/no-destruction, so the safety profile is covered; the description adds genuinely new behavior — a signed-in Printdash account is required and the connection prompts sign-in on printdash.io when missing. It also surfaces conditional capabilities (cancellable? invoice available? reorderable items?) that tell the agent what state checks are possible.

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, then auth caveat at the end where it belongs. The long mid-sentence field enumeration is somewhat redundant against the output schema, but it is a single well-formed sentence with no filler.

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

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

Output schema exists, so the field list is extra rather than necessary; the key non-schema information an agent needs — the sign-in requirement and what happens without it — is present. Only missing piece is explicit guidance on where this fits relative to cancel_order/reorder workflows.

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 `order` param is fully documented there, including that an order id from a link is accepted. The description's "by its order number" adds no syntax or format detail beyond that, so baseline 3 applies.

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

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

States a specific verb+resource with scope: "One order by its order number" — immediately distinct from list_orders, which returns many. The enumeration of returned fields confirms this is a single-record fetch, not a search.

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?

"One order by its order number" implies you need a known order number, which implicitly routes agents away from list_orders/search. But it never explicitly says when to use this versus list_orders, or that it should be called before cancel_order/reorder to check eligibility — even though the description mentions cancellability and reorderable items.

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, closed-world, non-destructive, so the safety profile is covered. The description adds value beyond that: it discloses the breadth of the returned payload, flags that default_configuration is a prefilled job payload consumable by price_job, and states the commercial/regional context (Australian printing and delivery, AUD, GST-inclusive).

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 intent is front-loaded in the opening clause, but the tool has an output schema, so the long mid-sentence enumeration of every returned field largely duplicates structured data and crowds out the two genuinely useful signals (call before asking the customer, and the price_job handoff). The Australia/AUD/GST sentence reads as cross-tool boilerplate rather than needing to be here.

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 a single required parameter, full schema coverage, and an output schema covering return values, the agent has what it needs; the description's real contribution is the workflow framing (read first, feed price_job) which it supplies clearly. Only the missing sibling routing for product_id discovery keeps it from being fully self-contained.

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 there is a single required product_id whose provenance is documented in the schema (from list_products or search_products). The description adds nothing about the parameter — no format hints, no error behavior for unknown ids — so this sits at the baseline for a fully-schema-documented 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 is specific about the resource (one Printdash product's complete option form) and enumerates its contents in concrete terms — required flags, option ids/labels, defaults, quantity and custom size limits, page counts, finish stock pricing, image, artwork guides, and default_configuration. It implicitly distinguishes itself from list_products/search_products by describing the per-product option form rather than a listing, though it never names those siblings outright.

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?

"Read this before asking the customer anything" is a clear, actionable usage directive that sequences this call ahead of customer interaction, and "ready for price_job" names the natural downstream tool. It lacks explicit when-not-to-use guidance or a direct pointer to list_products/search_products as the source of product_id (that link lives only in the schema).

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 readOnly/idempotent/non-destructive, so the description's 'Read only' is redundant, but it adds genuine value by disclosing the auth model: a signed-in Printdash account is required and an unauthenticated call triggers a sign-in prompt on printdash.io. That is behavior an agent cannot infer from the schema and would otherwise be surprised by mid-workflow. It stops short of describing error behavior for invalid or missing quote numbers.

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, then the field inventory, then the auth constraint — a sensible ordering with no filler. The mid-sentence field enumeration is dense and largely duplicates what the output schema already declares, which 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 single-record read tool with annotations and an output schema, the essentials are covered, and the auth caveat is the most valuable addition. But the description spends most of its length restating return fields the output schema already owns, while omitting what happens on a bad or unknown quote number — the one failure mode an agent actually needs to plan around.

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

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

Schema coverage is 100% and the single parameter already documents that it accepts a quote number or the quote id from its link. The description's 'by its quote number' actually narrows the schema's stated flexibility rather than extending it, so it adds no semantics beyond the structured field — 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 resource and scope — 'One saved quote by its quote number' — which distinguishes it from the bulk list_quotes sibling by cardinality and key. It then enumerates the contents of the payload (status, lines, subtotal, delivery, total, expiry, share link, convertibility, page link), leaving no ambiguity about what a caller gets back.

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: 'one saved quote by its quote number' signals a single-record fetch that contrasts with list_quotes, and the sign-in requirement is framed as a precondition. However, no alternative is named explicitly (list_quotes, get_quote_request, get_order) and there is no when-not guidance or note about what happens if the quote number is unknown.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so the description's real contribution is the auth behavior: it requires a signed-in Printdash account and the connection triggers a sign-in prompt on printdash.io when absent. That is genuinely useful context an agent cannot get from the structured fields, though error behavior for an unknown request number 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?

Two sentences, no filler. The returned-field inventory comes first and the prerequisite second, so an agent can decide to call before reading the auth caveat.

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

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

With an output schema present the description needn't detail return shape, and it still summarizes the payload while covering the auth prerequisite for a one-parameter read. Only the failure mode for an invalid or unknown request number is left implicit.

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 parameter already documents 'request number (or the request id from its link)'. The description restates 'by its request number' without adding format, resolution, or fallback detail, 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 ('one custom quote request by its request number') and enumerates what it yields: request contents, status, cancellability, and the resulting quote. That single-vs-list framing cleanly separates it from list_quote_requests without needing the sibling's 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 'one ... by its request number' phrasing implies the lookup use case, but no alternative is named (e.g. list_quote_requests for browsing, cancel_quote_request for acting on it) and no when-not condition is given. 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.

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds valuable non-obvious behavior: the auth requirement and the exact outcome (a sign-in prompt on printdash.io) when called anonymously — a detail 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?

Two sentences, no filler. The payload contents come first and the precondition comes second, which is the right order for an agent deciding whether it can call this now.

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

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

An output schema exists, so the description need not document return structure; it instead summarizes the payload and adds the one behavioral fact an agent needs — the sign-in requirement. Nothing material is missing for a zero-parameter 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?

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter discussion, and there are no hidden inputs an agent could get wrong.

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 the specific resource (referral summary) and enumerates exactly what it returns: referral code and link, counts of referred customers and orders, credit balance, and commission. This is a concrete verb+resource statement that leaves no ambiguity, and no sibling tool overlaps with it.

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 the precondition (a signed-in Printdash account) and describes the fallback behavior when that condition is unmet, which is real usage guidance. It does not explicitly route to alternatives, but no sibling offers comparable referral data, so there is little to exclude.

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/closed-world, yet the description still adds non-obvious behavior: a signed-in Printdash account is required, and calling it unauthenticated triggers a customer-facing sign-in flow on printdash.io rather than a plain error. It also discloses ordering (default address first), which 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?

Two short sentences with no filler, and the resource plus ordering are front-loaded ahead of the auth caveat. The first sentence is a grammatical fragment ('...with the ids price_job and estimate_delivery take'), which slightly slows parsing but costs no real space.

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 a full annotation set and an output schema, the description supplies exactly the missing pieces: what the list represents, its ordering, how the returned ids are consumed downstream, and the auth precondition. An agent has everything needed to decide to call it and to handle the signed-out case.

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 there is no parameter semantics to document and the baseline is 4. The description correctly avoids inventing parameter discussion and instead spends its words on context and auth.

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 noun phrase 'The saved delivery addresses in the current buying context' plus the title make it unambiguous that this returns a list of addresses, and the sibling set (create_address, update_address, delete_address, set_default_address) leaves no confusion about which operation this is. It loses a point only because the description itself omits an explicit verb ('List'), relying on the title to carry that.

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 'the ids price_job and estimate_delivery take' implies the workflow position of this tool (call it before pricing/estimating), which is a real usage signal. However, there is no explicit when-to-use statement, no exclusion, and no pointer to a sibling such as create_address when the list is empty — the agent must infer all of that.

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

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

Annotations already cover read-only/idempotent safety, and the description adds real value beyond them: the auth gate (signed-in Printdash account, otherwise the customer is prompted to sign in), that values reflect how the site resolves them, and that artwork may still be changeable. Return shape is left to the output schema, which is appropriate.

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, contents first then the auth precondition, with no filler. The first sentence is a dense run-on listing five outputs, which costs a little readability but every clause carries information.

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

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

Covers what the tool returns at a summary level, the auth requirement, and the fact that results reflect site-side resolution; an output schema exists so per-field return documentation is not required. Only missing piece is explicit sibling disambiguation for a crowded artwork toolset.

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%, including the kind enum and its provenance (line_id from get_cart/get_quote, item_id from get_order), so the baseline is 3. The description's mention of cart line / quote line / order job maps onto kind but adds no syntax or defaults beyond 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 (list) and resource (artwork on a cart line, quote line or order job) and enumerates what the listing contains: per-design front/back file and page, ready count, changeability, uploader link. This clearly separates it from siblings like get_artwork_uploader_link (link only) or check_artwork (validation).

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 resource named (a line's artwork), but there is no explicit when-to-use vs check_artwork, get_artwork_requirements, or get_artwork_uploader_link, which are the obvious overlaps. An agent must infer which sibling to call from names alone.

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?

'Read only' duplicates readOnlyHint, but the description goes beyond annotations by disclosing the authentication requirement and the concrete behavior on failure ('the connection asks the customer to sign in on printdash.io'), which is exactly what an agent needs to handle an unauthenticated call. It also enumerates the returned content, though the output schema already covers that.

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 resource and scope, then the safety profile, then the auth prerequisite — a sensible ordering with little waste. The sentence 'Read only.' contributes nothing beyond readOnlyHint and could be dropped, which keeps it from a 5.

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 tool is simple (one optional param, output schema present), so the description need not explain return values or pagination. It covers the one non-obvious complexity — the sign-in requirement — and leaves the rest to structured fields, with only the sibling distinction 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?

With 100% schema coverage and a single parameter, the schema already documents 'limit' including the default of 10 and the 'newest first' ordering. The description's phrase 'most recent orders' corroborates the ordering but adds no new syntax, bounds or defaults beyond what the schema states.

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 (list recent orders) and scopes it to 'the current buying context', which is meaningful information an agent can't get from the name alone. It stops short of differentiating from the nearest sibling, get_order, so an agent must infer that this is the plural/list counterpart of a single-order fetch.

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

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

Usage is implied rather than stated: 'the most recent orders in the current buying context' hints at a browsing/summary use case, but there is no explicit when-to-use or when-not-to-use guidance. No alternative is named, despite siblings like get_order, list_pending_approvals and list_quotes overlapping in scope.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description goes further: exact sort order (oldest first), owner-scoped result set, and the auth behavior (unauthenticated calls prompt a sign-in on printdash.io). That auth precondition is behavioral context annotations cannot express.

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

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

Front-loaded with the scope ("For a Team owner") and free of filler. The trailing enumeration of return fields partially duplicates the output schema, which is the one bit of redundancy.

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

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

Output schema exists and annotations cover safety, and the description still adds the pieces those cannot carry: sort order, ownership scoping, and the sign-in requirement. Nothing needed to call it correctly is missing.

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

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

The tool takes no parameters, so there is nothing for the schema to document and the 0-param baseline of 4 applies. The description correctly implies no input is needed; only the ownership condition acts as an implicit filter.

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

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

States a specific verb+resource (list held orders awaiting approval) and a precise scope: only Teams the caller owns. It also enumerates the returned fields, so an agent can tell it apart from list_orders 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?

"For a Team owner" plus "an account that owns no Team is told only an owner approves" gives a clear use condition and an explicit non-applicable case. It never names alternatives such as list_orders or approve_order, so routing across siblings is left to inference.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world. Beyond that, the description discloses that from_price is an indicative starting price for the default job only, that prices are AUD and GST-inclusive, and that delivery is Australia-only — useful context an agent would otherwise get wrong.

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

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

Front-loads the resource and returned fields, then the routing hint, then the pricing caveat and geography. Dense but every sentence carries information; the parenthetical price gloss is slightly verbose.

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

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

An output schema exists so return values need not be explained, yet the description still frames what they mean (from_price semantics) plus currency, tax, and delivery scope — everything an agent needs to call this correctly and interpret the result.

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

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

Zero parameters, so the baseline is 4. The description instead characterizes the returned fields and the meaning of from_price, which is more than the empty 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?

Names a specific verb+resource (every product Printdash sells) and enumerates the catalog categories, then states the fields returned (id, description, page, from_price). It distinguishes itself from search_products by positioning as a full-catalog starting point.

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?

"Start here or with search_products" gives an explicit alternative entry point, and "price_job gives the exact price of the customer's job" routes pricing questions elsewhere. It stops short of saying when search is preferred over list (e.g., when the catalog is unknown or large).

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 non-destructive, so the safety profile is covered. The description adds behavior beyond them: newest-first ordering, status rendered as /quotes shows it, inclusion of the resulting quote, and the unauthenticated case where the connection prompts a sign-in on printdash.io.

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

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

Two sentences, no filler, with the resource identity and ordering front-loaded and the auth caveat second. Every clause conveys something the agent would otherwise have to discover at call time.

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

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

An output schema exists, so return shape needs no explanation, and the description still covers ordering, status semantics and the auth failure mode. It is sufficient to call correctly; only the sibling-selection guidance is thin.

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 zero parameters, so the baseline is 4 and no parameter explanation is owed. The phrase 'current buying context' usefully implies the scope is set elsewhere rather than by this call.

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_quote_requests') scoped to 'the customer's custom quote requests in the current buying context', which separates it from the singular get_quote_request and from list_quotes. It never names those siblings, so the differentiation must be inferred from the resource wording alone.

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?

Mentions the 'current buying context' constraint, implicitly tying usage to set_context, and the sign-in prerequisite is stated clearly. There is no explicit guidance on when to choose this over list_quotes or get_quote_request, so the agent must reason about the distinction.

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 openWorld=false, so safety is covered. The description still adds real context beyond them: the result set is scoped to the 'current buying context' and the auth failure path is interactive (the customer is asked to sign in on printdash.io), which changes how an agent should sequence the call. It stops short of describing pagination or empty-list 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 payload is front-loaded in the first clause and every sentence carries information the agent needs. It is slightly padded by the repeated qualifier 'as the Quotes list shows it' used twice for status and total, which could have been stated once.

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 read tool with an output schema, this covers the important unknowns: auth requirement, context scoping, and the fields returned. It would be complete at 5 if it named set_context as the way to change the buying context or said what an empty list means.

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 limit parameter is fully documented there (1-20, default 10, newest first). The description adds nothing about the single parameter, so the schema does all the work and 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 concrete resource (saved quotes) and enumerates exactly what each row carries: status, total including delivery, expiry and link. It is clearly the list counterpart to get_quote, but it never names a sibling or says explicitly how it differs from get_quote or list_quote_requests, leaving that inference to the agent.

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: 'in the current buying context' hints that results depend on a context set elsewhere (set_context), but that dependency is never stated. The one genuine usage prerequisite is spelled out well — a signed-in Printdash account is required and the connection will prompt the customer to sign in. There are no when-not-to-use cases or named alternatives.

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 (read-only, idempotent, closed-world), and the description adds non-obvious behavior beyond them: ambiguous phrases come back with all candidates rather than a best guess, options incompatible with the current selection are surfaced, and unplaceable words are reported. That is exactly the decision-shaping behavior an agent needs and cannot get from the 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?

One dense, front-loaded sentence pair that puts the transformation first and the output inventory second, with zero filler. The parenthetical example list is slightly heavy inside the main clause, but nothing 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?

Covers the full contract an agent needs: input shape (one phrase per option), the mandatory human-in-the-loop behavior on ambiguity, and which downstream tool consumes the resulting configuration. With an output schema present, it doesn't need to enumerate return fields, yet it still summarizes them for routing purposes.

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 67% and the schema already documents that `chosen` filters incompatible options and gives phrase examples for `phrases`. The description restates that relationship ('given what is already chosen', 'options not available with what is chosen') but adds little new syntax or constraint detail, such as the 20-phrase / 120-char limits, which live only in the schema. 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 precise verb+resource: it turns the customer's free-text phrases into option ids for one product, scoped by what is already chosen. This is clearly distinct from siblings like get_product (catalog lookup) and price_job (pricing), and the parenthetical examples of phrases make the input domain concrete.

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: use it to resolve customer wording before pricing, and its output feeds price_job. It also encodes a routing rule for ambiguity ('never a guess: ask the customer'), which tells the agent to stop rather than assume. It stops short of explicitly naming alternatives or stating when not to use it (e.g., when the customer already supplied ids).

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context that the result includes sign-in status and Australian/AUD/GST business constraints, but it does not describe failure modes, error behavior, or response details beyond sign-in status.

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 two compact sentences and front-loads the core purpose in the first sentence. The second sentence is domain context that does not directly help select or invoke ping, so it slightly detracts from strict conciseness, though the overall size is appropriate.

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-parameter connectivity/status tool with full annotations and an output schema, the description supplies enough context to call it correctly: it says what is checked and what sign-in information is reported. Return-value details can be left to the output schema.

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

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

The tool has zero parameters, so there is no parameter semantics to explain. The baseline for a zero-parameter tool is 4, and the schema carries the empty object shape cleanly.

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: it checks Printdash reachability and reports sign-in status. This clearly distinguishes it from the account, order, and cart siblings, which perform concrete operations rather than connectivity/auth checks.

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 intended use is implied: call this to verify connectivity or whether the user is signed in. However, it gives no explicit when-to-use guidance, no when-not-to-use guidance, and no comparison to alternatives such as get_account.

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 substantial context beyond the annotations: idempotency semantics (same key returns same order, never a second), server-side re-pricing and refusal, and payment branching (payment_url for card, none for on-account, held for Team owner). These are non-obvious behaviors an agent must anticipate.

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

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

Dense but front-loaded: purpose first, then idempotency, then failure handling, then payment outcomes, then auth. Every sentence carries operational meaning, though the auth sentence 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 destructive, open-world mutation with an output schema, the description covers permissions, idempotency, failure recovery, and payment outcomes. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100%, so parameters are documented; the description still adds value by explaining that confirmation_token comes from prepare_checkout and that idempotency_key must be a newly generated UUID reused only for retries. Slightly redundant with the schema's own descriptions, hence not a 5.

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 ('Places the order prepare_checkout summarised') and ties it directly to the sibling that precedes it. An agent can distinguish it from prepare_checkout, approve_order, and convert_quote_to_order from the text alone.

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 preconditions ('after the customer has seen that summary and said yes', 'Never call it without the customer's agreement') and a recovery path ('refuses a price that moved... then call prepare_checkout again'). Also disambiguates payment responsibility by order type.

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