vivid-ads-commerce

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

Goes well beyond the annotations: nothing is charged, it returns the customer's existing Shopify checkout link, the already-converted-to-order case, and a detailed auth flow (6-digit code emailed, need_verification status, verificationId, 'shows nothing before that'). This is exactly the extra context the readOnly/idempotent hints 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?

Front-loaded with the core purpose before the verification procedure, and each sentence carries operational weight. It is dense and slightly long, but the length is justified by the non-obvious verification workflow.

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

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

With no output schema, the description still covers return values (payment link, need_verification + verificationId, or order-already-exists) and the full prerequisite chain. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: quote_number AND email together act as identity, and token must come from vivid_identity_verify, with the consequence of omitting it. It stops short of format details for quote_number beyond the example.

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 ('Return the secure payment link for a formal quote') and scopes it to quotes Vivid already emailed, with a concrete example. An agent can distinguish it from sibling order/quote tools 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?

Explains when it applies (an emailed formal quote) and when not (if the quote became an order, it says so instead of issuing a link). It names the alternative tool (vivid_identity_verify) and the exact sequence to follow when a token is missing.

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 real behavioral context beyond annotations: a successful attach is not print-ready and is still team-checked, plus the two-step direct-upload flow and file-size range (50–200MB+). Annotations already cover the safety profile (non-readonly, non-idempotent, non-destructive), so this is valuable supplementary disclosure.

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

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

Front-loads the core action and the 'not print-ready' caveat before the two usage paths. It is somewhat dense but each sentence carries actionable information; only minor tightening would help.

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

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

With no output schema, the description usefully references the returned fileUrl and fileId and explains how to chain into vivid_place_order. It covers the main complexity of the multi-step upload well, leaving only minor gaps about accepted formats/handling edge cases.

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 80%, so the schema already documents most parameters and baseline is 3. The description adds workflow meaning for sourceUrl and requestUpload (and the fileId finalisation step), but contentType and filename are only covered by 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+resource (attach artwork file or link to a signage order) and clearly scopes it to customer-provided files. It does not explicitly differentiate from close siblings like vivid_upload_artwork or vivid_order_artwork, 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 concrete routing: use sourceUrl as the 'easiest' path, and requestUpload:true for large files with no link. It also names vivid_place_order as the downstream consumer, but does not state when NOT to use it or contrast with sibling upload/order-artwork 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?

Annotations already cover readOnly, idempotent, openWorld, and non-destructive, so the bar is lower; the description still adds real behavioral context: it is public (no auth implied), nothing is emailed, and the links come straight from the source page. The instruction 'Give the links exactly as returned' usefully constrains how the agent should relay output.

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

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

Front-loaded with the action and resource, and no sentence is padding — even the final imperative adds handling value. It is somewhat dense with stacked parentheticals, which slightly hurts scannability but not economy.

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 format need not be explained, and the description plus schema together tell the agent what the tool returns, why (artwork setup with bleed/safe area), the source of truth, and the one non-obvious handling rule ('give the links exactly as returned'). Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both `product` and `size` are already well documented in the schema, including the same '850x2000' example and the per-size filter behavior. The description's mention of 'per size' and the product page adds no detail beyond what the schema provides, 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 (get official print-ready artwork template download links) plus the source (the product's vividads.com.au product page) and format (PDF/AI, per size). This clearly separates it from siblings like vivid_artwork, vivid_check_artwork, and vivid_upload_artwork.

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 context of use — helping the customer or their designer set up artwork correctly (bleed, safe area, size) — and notes it is public and read-only with nothing emailed, which rules out an email-delivery expectation. It does not explicitly name an alternative tool or state when not to use it, so it stops 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?

Annotations already cover readOnly/idempotent/non-destructive, but the description adds genuinely new context: results are advisory and never block an order, customer acceptance of the file is always allowed, and every order still gets a free digital proof. This materially shapes how an agent should act on the output.

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

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

Front-loaded with the core action and structured logically, with the advisory constraint given prominence. The closing sentence about the free digital proof is slightly tangential to a preflight checker, keeping it just short of ideal.

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

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

With no output schema, the description compensates well by enumerating exactly what the report contains (size vs ordered size, bleed, RGB/CMYK, font embedding, effective resolution, each with a plain-English fix). An agent knows what it will get back and how to treat it.

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

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

Schema description coverage is 100%, so the schema already documents file_url, width_mm, and height_mm. The description's list of reported checks (size vs ordered, bleed, colour, fonts, resolution) describes outputs rather than clarifying the parameters, so it adds no meaning beyond 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 specific verb and resource ('Check whether a customer's artwork PDF is print-ready') and adds scope ('powered by Vivid's own production preflight engine'). It is clearly distinguishable from siblings like vivid_upload_artwork, vivid_artwork, and vivid_proof_status.

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

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

Gives explicit timing ('BEFORE they order') and a strong behavioral directive ('ADVISORY ONLY: it never blocks anything... say so explicitly'). It does not name or route to any alternative sibling, but the when-to-use context is otherwise very clear.

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 write side effect (email sent, record saved), the output boundary ('never returns order details'), and the verification semantics of the order number (marked unverified unless an identity token is supplied). What it omits is retry/failure behavior — the idempotency_key parameter implies safe retries while the description only says to call once, and no case confirmation/number is described.

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

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

Front-loaded with the action and its effect, then the routing clause, then constraints. The long enumerated scenario list is dense but each item earns its place by mapping to a reason value; the prose is somewhat run-on but has no filler sentences.

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 10-parameter open-world mutation with no output schema, the description supplies everything needed: side effects, no-return-value warning, identity-verification semantics, reply-channel requirement, and one-shot invocation guidance.

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

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

With 60% schema coverage, the description compensates by mapping business scenarios to reason values (including the special 'ai_automation' reason) and by explaining email/phone as the reply channel, the token's verification effect, and what the summary must contain. It leaves name, company, and product unaddressed, but those are self-explanatory strings already in the schema.

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

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

States a specific verb+resource ('Open a support case with the Vivid Ads team') and immediately discloses the side effects (emails the team, saves a record). It explicitly carves out its niche against the 26 siblings: 'for anything the other tools cannot do', then enumerates the concrete scenarios it owns.

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 positive triggers (damaged/faulty orders, address changes, proof help, samples, trade accounts, price match), explicit exclusions ('Never use this to take payment or approve a proof'), a cadence rule ('Call it ONCE per issue'), and preconditions ('after collecting a clear summary and the customer's email or phone'). It also routes sub-tasks to siblings: vivid_identity_verify for the token and vivid_upload_artwork for photos.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: the preference for live order-history data with a curated fallback, the degraded 'guidance' mode when no parameter is passed, and the non-pressuring tone constraint. Return format and how many results are guaranteed are not specified.

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

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

Front-loaded with the core action and the two data-source modes, then the exclusion parameter, then the tone note. Slightly repetitive — 'NON-pushy' and 'Never pressure — helpful suggestions only' say the same thing twice — but every other clause carries distinct operational 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?

With zero required parameters and no output schema, the description has to explain the three calling modes and it does so clearly, including the empty-argument path. It stops short of describing what a suggestion result contains beyond 'companions with a reason'.

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 each property is already documented, so the baseline is 3. The description still adds relational meaning the schema does not: that `product` is preferred over `use_case`, that `use_case` is a fallback rather than an independent filter, and that `already_have` is a suppression list.

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 (suggest) and resource (add-on products) with the qualifier 'NON-pushy' and '1–2 genuinely useful companions with a reason', which makes the output shape legible. It does not distinguish itself from the sibling vivid_recommend, which sounds like an overlapping recommendation tool, so an agent cannot fully route between them 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?

Gives explicit conditional usage: pass `product` to use real order-history data, pass `use_case` as the curated fallback, omit both for guidance, and pass `already_have` to suppress items the customer chose. What is missing is a when-not-to-use statement or a comparison to vivid_recommend, the obvious 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 only declare it as a safe read; the description adds the real behavioral model — proof-approval dependency, 3pm Melbourne cut-off, quantity bands (including the 201+ manual case), postcode transit bands, and that it returns a window plus assumptions. It also flags the estimate-vs-guarantee caveat the agent must relay.

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

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

Front-loads the core question, then the timeline mechanics, then the caveat. Dense but every sentence carries decision-relevant information; slightly long but not padded.

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?

Return values are covered by an output schema, so the description rightly focuses on the causal timeline and edge cases. An agent has everything needed to call it and to caveat the result correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds meaning by spelling out the quantity-to-production-day mapping and that postcode determines metro/regional/remote transit bands. Product and artwork_ready semantics are left mostly to 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 ('Estimate WHEN an order would arrive at an Australian postcode') and anchors it in a real customer question. It doesn't name the sibling vivid_delivery_quote, which likely overlaps, so an agent must infer the distinction.

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 triggering context ('can I get it by Friday?') and routes hard deadlines to a phone alternative (1300 721 614). It stops short of an explicit when-not-me vs. vivid_delivery_quote or vivid_price.

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, openWorld), so the description's added value is real: it discloses that results are live checkout rates including GST sourced from carrier and shipping-rules apps, and mandates mentioning free pickup. It stops short of describing latency, failure modes, or what happens with unsupported postcodes, but adds meaningful context beyond the annotations.

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

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

Dense but every sentence carries operational weight — scope, trigger, prerequisite chain, prohibition, and the pickup reminder. Slightly over-emphatic with capitalization and stacked clauses, but front-loaded and free of padding.

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

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

For a read-only pricing tool with an output schema, the description needn't explain return values, and it doesn't. Combined with a nested options object, 7 params, and a sibling estimate tool, the description supplies the prerequisite dependency on vivid_price/product and the anti-estimation rule. Minor gap: no guidance on invalid or unmapped postcodes.

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 71%, so the schema documents most parameters. The description still adds value: it tells the agent postcode is required, suburb 'improves accuracy', and state is derived from postcode if omitted, plus the ordering constraint that size/options/quantity must come from vivid_price. It does not explain the options nested-object contract itself, which the schema partly covers.

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: exact delivery/freight cost to an Australian postcode for a product configuration, and pins it to the same live checkout rates (carrier + shipping-rules apps, incl. GST). This clearly separates it from the sibling vivid_delivery_estimate, which the description explicitly warns against using.

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

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

Gives an explicit trigger ('Use whenever the customer asks what shipping/delivery costs'), a prerequisite chain (resolve product + size/options + quantity first via vivid_product / vivid_price), and a negative instruction ('Never estimate freight yourself'). It also names the free-pickup alternative to surface. Nothing about when-to-use 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 declare the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false). The description adds data-shape context: per-line-item breakdown, order-level rollup, and StarShipit shipping summary where available, plus the state vocabulary. It does not add permission, auth-flow, or rate-limit behavior beyond what annotations and schema already provide.

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

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

The description is front-loaded with the core purpose, then compactly lists states and notes the shipping summary. Every sentence carries useful information for an agent, and there is no filler.

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

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

For a read-only status tool with no output schema, the description adequately explains what data is returned and the possible states. The schema covers identity requirements fully, so the only meaningful gap is routing guidance among similar sibling status tools, which is minor given the rich schema and annotations.

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

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

Schema description coverage is 100%, so the schema fully documents token, order_id, order_name, line_item_id, and customer_email. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

The description states a specific resource (authoritative order state) and the output shape (per-line-item breakdown plus order-level rollup), and enumerates all possible states. It is clear what the tool returns, but it does not explicitly distinguish this from siblings like vivid_order_status or vivid_fulfilment_pickup_status.

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

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

There is no when-to-use guidance, no alternatives named, and no prerequisites mentioned. The word 'Authoritative' hints at primacy but does not state when an agent should choose this tool over vivid_order_status or the other fulfilment status 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the description does not need to restate safety. It adds domain semantics (the pickup location and the printed/cut readiness condition) but says nothing about the identity/verification gate or the need_verification response path, which are behavioural traits an agent should 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?

A single 22-word sentence with the readiness condition front-loaded and zero filler. Every clause earns its place.

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

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

For a read-only status tool with no output schema, the description conveys what state is being reported and at which stage. It leaves the return shape and the verification/6-digit-code path to the schema property descriptions, which do cover them, so the definition is largely but not entirely self-sufficient.

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 every property (token, order_id, order_name, line_item_id, customer_email) is documented in-schema, including the token/email verification flow. 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?

The description states a specific check: whether an order or line items is ready for pickup at Derrimut VIC, and pins down what 'ready' means (printed and cut, before dispatch). That is a clear verb+resource with scope, but it never names or contrasts with the adjacent status siblings (vivid_fulfilment_order_status, vivid_fulfilment_production_stage, vivid_fulfilment_shipping), so an agent has to infer which status tool to reach for.

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: 'before dispatch' hints this is the pre-shipping stage answer, but there is no explicit when-to-use, when-not, or alternative named. With four sibling status/fulfilment tools available, the absence of routing guidance is a real gap, though the pickup-specific framing does narrow intent.

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

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

The annotations already cover safety traits (read-only, idempotent, open-world, non-destructive), so the bar for extra disclosure is lower. The description adds valuable behavioral context by defining the returned production stages, needs-action states, and the fact that each item includes press and print timestamp. It does not itself disclose the identity requirement, but that is handled in 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?

The description is front-loaded with the core purpose, then provides stage and needs-action enumerations that are relevant to interpreting the output. The two sentences are dense but not padded; the long lists earn their place by defining domain states. It could be slightly more structured, but it is appropriately concise for the information conveyed.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so by naming the production stages, needs-action states, rollup, press, and print timestamp. Authentication and identity requirements are covered by the schema descriptions, including the conditional token behavior. The main remaining gap is sibling routing, which is not addressed.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including the identity token, order identifiers, line_item_id, and customer_email. The description adds no parameter-level syntax or aliasing beyond what the schema provides, which matches the baseline when schema coverage is complete.

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

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

The description states a specific resource and scope: line-item production status, with a rollup. It lists concrete production stages and needs-action states, so an agent knows what the tool reports. However, it does not distinguish this tool from sibling fulfilment or order status tools, leaving sibling selection partly unresolved.

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

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

There is no explicit when-to-use guidance, no exclusions, and no named alternatives among the many sibling status tools. The description implies production-tracking usage through its content, but it does not tell the agent when this tool should be selected over vivid_fulfilment_order_status, vivid_order_status, or vivid_proof_status.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds useful behavioral context by enumerating the shipping_state lifecycle values, but discloses nothing about auth flow, rate limits, or failure modes beyond what annotations and schema already provide.

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

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

Two tight sentences with no filler, front-loading the returned fields before the state enum. It is efficient, though the fragment style lacks an explicit action clause that would orient the agent faster.

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

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

There is no output schema, so the description's enumeration of return fields (carrier, tracking number, tracking URL, ETA, delivered flag, shipping_state) usefully compensates by telling the agent what comes back. For a read-only tool with a rich schema, it is largely complete, missing only sibling routing guidance.

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

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

Schema description coverage is 100% and each parameter (token, order_id, order_name, line_item_id, customer_email) is thoroughly documented in the schema, including the identity requirements. The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

The description names the specific resource (StarShipit shipping) and enumerates the returned data points (carrier, tracking number, tracking URL, ETA, delivered flag, shipping_state), making the retrieval intent clear. It does not differentiate from the many sibling status tools (vivid_fulfilment_order_status, vivid_fulfilment_pickup_status, vivid_fulfilment_production_stage), and it omits an explicit verb, 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?

The description offers no when-to-use guidance, no prerequisites, and no reference to alternative tools even though the sibling list contains several closely related fulfilment-status tools. The only usage-relevant information (token required to see details, email must match) lives entirely in the schema, not the description.

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 (readOnlyHint=false, openWorldHint=true, non-idempotent, non-destructive), and the description adds real behavioral context beyond them: it sends a 6-digit code, returns a verificationId, and must be followed by vivid_identity_verify. It does not mention code expiry, resend behavior, or rate limits, which would round this out.

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 compact sentences that are front-loaded with the purpose and the trigger, then the mechanics, then the next step. No filler, though the parenthetical intent list slightly overlaps with the final trigger 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?

For a 2-parameter tool with no output schema, the description supplies the full operational story: prerequisite, side effect, return value (verificationId), and the downstream call. An agent has everything needed to invoke it and handle 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by mapping real customer intents (past orders, reorder, saved address, email order-status) onto the optional purpose values reorder | order_status | saved_details. The enum values themselves are not enumerated as a parameter contract, so it is useful but not exhaustive.

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 (start email verification) and immediately scopes it to gating private customer data, listing the concrete data categories it protects. It also implicitly differentiates from its sibling vivid_identity_verify by presenting itself as step one of a two-step flow.

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

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

Explicitly states when to use it (customer asks for 'my orders', 'reorder', or 'status by email' and no valid identity token exists) and names the follow-up tool to call. The trigger phrases and the prerequisite condition leave 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 cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true), so the description's job is to add operational context — and it does: codes expire in 10 minutes, attempts are limited, and success returns a short-lived identity token. It stops short of saying what happens on failure (error shape, whether the verificationId is burned after N attempts), which is the one remaining gap for a non-idempotent call.

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 action and its inputs, then the outcome and constraints. Every clause earns its place: nothing is restated from the title and no filler is present.

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

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

For a two-parameter, no-output-schema verification step, the description supplies the prerequisite tool, the credential format, the expiry window, the retry limit, and the downstream token consumers. An agent has everything needed to invoke it correctly in sequence.

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

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

Schema description coverage is 100%, so both parameters already carry their own descriptions in the schema, and the description largely restates them ("pass the verificationId from vivid_identity_start and the 6-digit code"). Baseline 3 applies — the description reinforces provenance but adds no format or validation detail 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?

Names a specific verb and resource ("Complete email verification") and immediately scopes it to the two inputs, the verificationId from vivid_identity_start and the 6-digit code. It also distinguishes itself from siblings by naming the downstream tools it unlocks (vivid_reorder, vivid_order_status), so an agent can place it in the flow without reading 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?

Explicitly states the prerequisite chain (verificationId must come from vivid_identity_start) and the success condition that gates other tools. The expiry and attempt-limit notes tell the agent when the call must happen and when to retry versus restart, which is exactly the routing information needed.

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 read-only, idempotent, non-destructive behavior. The description adds important context beyond that: it requires an identity token, only returns artwork owned by the customer, returns view links, and triggers an email with a 6-digit code when no token is supplied, returning a need_verification status with a verificationId.

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 purpose and usage triggers, then the required auth flow. It is somewhat repetitive, repeating the email/token requirement and the verification consequence, but the repetition is not severe enough to obscure the 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?

Given the tool's complexity—external email side effect, identity verification state machine, and no output schema—the description explains the full flow, return links, and failure status. An agent has enough information to invoke it correctly and handle the verification step.

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

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

Schema coverage is 100%, so the schema already documents email, order, and token. The description reinforces the token/email/order relationship but adds little per-parameter meaning beyond what the schema descriptions already provide. The baseline of 3 is appropriate.

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

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

States a specific verb and resource: show print-ready artwork files from a past order. The scope is narrowed to a verified customer and 'the actual files that went to print', which clearly distinguishes it from sibling artwork tools like vivid_artwork or vivid_check_artwork.

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 names when to use it ('what artwork did I print', before confirming a reorder) and describes the alternative path when no token exists, including calling vivid_identity_verify first. The verification workflow and the condition that nothing is shown before authentication are fully spelled out.

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

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

Beyond the annotations, the description discloses critical behavior: live data sources (Enfocus Switch, StarShipit), finality rules for shipped/delivered orders, the requirement for customer email and a verified identity token, and the fallback flow where a 6-digit code is emailed and need_verification is returned. It also states that no details are shown before verification, which is important operational context.

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

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

The description is front-loaded and most sentences serve the auth/status context. There is slight redundancy around the email requirement appearing twice, but the overall length is justified by the complex verification workflow.

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

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

With no output schema and no required parameters declared, the description compensates well by explaining the possible status categories, the verification fallback response, and the required follow-up call to vivid_identity_verify. An agent has enough information to invoke the tool and handle the common unauthenticated path.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description still adds meaning beyond the schema by stating that the email must match the order, that the token comes from vivid_identity_verify, and that without a token the tool emails a code and returns need_verification.

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

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

The description names a specific verb and resource: checking LIVE order status, including production stage, pickup readiness, or shipping details from named systems. It is clear what the tool does, but it does not explicitly distinguish itself from sibling fulfilment-status tools such as vivid_fulfilment_order_status or vivid_fulfilment_shipping.

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 concrete use cases ('where is my order', 'track order 12345', 'is my order ready') and describes the identity-verification workflow with vivid_identity_verify. However, it does not state when not to use this tool or compare it against sibling 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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false) only give the safety envelope; the description adds real substance — draft-not-final semantics, no card charge, invoice/pay-link payment, and production gated on proof approval. The one gap is that retry/idempotency behaviour is left to the schema's idempotency_key description rather than being reconciled with idempotentHint=false here.

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 single most important distinction (draft vs placed order) and each sentence carries a distinct instruction or warning. It is dense and parenthetical-heavy, but almost nothing is redundant; a small trim of the portal URL aside would tighten it further.

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 15-param, nested, no-output-schema mutation tool, it covers the critical workflow: confirm gating, artwork optionality, payment path, and retry caution. The main missing piece is what the two call modes actually return (review summary vs. created draft), which an agent would benefit from knowing given no output schema exists.

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 47% across 15 params, but the description compensates by mapping the pre-call checklist (product, quantity, configuration, price, customer details, delivery/pickup) onto the fields and by clarifying that confirm gates the write and artwork is optional. It adds meaning beyond the raw schema for the highest-risk params, though a few (name, phone, poNumber, quantity) remain undocumented in both places.

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

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

States a specific verb and resource ('Create a Shopify DRAFT order for Vivid Ads team review') and immediately scopes it against the obvious misread ('NOT a final/placed order, and NEVER charges a card'). This cleanly distinguishes it from siblings like vivid_reorder, vivid_accept_quote, and vivid_request_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?

Explicit call protocol: call without confirm for a Review summary, set confirm:true only after customer confirmation, and do not auto-retry after a timeout without checking whether a draft already exists. It also pre-empts a common failure mode by stating artwork is optional and must not block the order.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description adds meaningful operational traits beyond them: variable latency ('several seconds'), possible manual confirmation, and the rule never to estimate or reuse another configuration's price. It doesn't cover failure modes or what happens on an invalid configuration, so not 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?

Front-loaded with the core purpose, then prerequisites, then latency, then customer-presentation rules. Every sentence carries an instruction an agent needs, though the customer-communication directives make it slightly long relative to the pure selection guidance.

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 needn't be described, and the definition covers the tricky parts of a nested-`options` pricing call: prerequisite tool, exact-config requirement, latency, and presentation. Error/validation behavior is the only notable gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains that `options` keys must be the FULL configuration drawn from vivid_product's schema, and that `size` alone suffices for simple products. That relationship between the two parameters isn't expressible in the schema itself.

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 ('Calculate the current price') scoped to an 'EXACT product configuration', which distinguishes it from estimate/price-break siblings like vivid_price_breaks and vivid_delivery_quote. It also names the upstream dependency (vivid_product), so an agent can place it correctly in a workflow.

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 context: use vivid_product first, pass full `options` for configurable products or just `size` for simple ones, and warn the customer before a slow call. It does not explicitly state when to prefer this over vivid_price_breaks or vivid_request_quote, so it stops short of full alternative 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?

Annotations already declare a safe read (readOnly, idempotent, non-destructive). The description adds material behavior beyond that: prices are AUD incl. GST, sourced identically to the live price so they can never contradict a quote, and it explicitly discloses the no-breaks case with a guardrail against inventing discounts.

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 purpose and scope, then usage, then source/currency guarantees, then the edge-case guardrail. The inline example prices are illustrative but slightly pad the opening; otherwise 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?

An output schema exists, so return structure need not be explained. The description covers the remaining agent needs — currency, GST, pricing provenance, and the no-breaks fallback — leaving nothing essential for correct invocation missing.

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

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

Schema description coverage is 100%, so the schema already documents product, size (per variant), and quantity. The description reinforces the quantity semantics (highlighting 'the next worthwhile break') and shows the break mapping, but adds only marginal detail over 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?

States a specific verb and resource (volume price breaks for a product + size) with concrete example values. It explicitly distinguishes itself from the sibling vivid_price by noting the prices 'come from the same source as the live price,' so an agent can tell the two apart without opening schemas.

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

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

Gives clear triggering contexts: 'bulk/trade pricing questions, or right after a price when a slightly larger quantity would save the customer money.' This effectively positions it against vivid_price by usage scenario, though it never explicitly names the alternative or states when not to call it.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description's real contribution is the reliability caveat: `turnaround` is live, quantity-aware, 'ready to dispatch in working days after proof approval by 3pm Melbourne time' and 'never quote a flat 24 hours or AEST'. That is actionable behavioral context an agent could otherwise get wrong. The rest of the description enumerates return fields, which the output schema already 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?

Front-loaded with the outcome and its purpose, then the caveat, then examples — a sensible ordering. It is dense and the turnaround parenthesis is long, but nearly every clause adds decision-relevant information with no filler.

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

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

With annotations and an output schema present, the description only needs to explain purpose, sequencing, and pitfalls, all of which it covers. Minor gap: it does not say what happens when the product name is unrecognized or ambiguous (fuzzy match vs. error), which matters for openWorldHint lookups.

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 `product` parameter, so the baseline is 3. The description earns above that by instantiating valid product names and mapping each to its option shape ('Flags have Size/Printed Sides/Flag Base; corflute has Size (or custom W×H)/Eyelets/Cutting'), which helps the agent format and sanity-check the input rather than just repeat 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 ('Get a product's FULL real option schema'), explicitly scopes it ('all dimensions, not just size'), and gives the downstream reason ('before pricing/ordering'), which separates it from vivid_price and vivid_price_breaks. The concrete product/option examples (flags, corflute, table throws) make the resource unmistakable.

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 'so you can configure it correctly before pricing/ordering' gives clear sequencing context: call this first, then price/order. It does not, however, name an alternative sibling or state exclusions (e.g., when to use vivid_price_breaks or vivid_search instead if the product name is unknown), so it stops short of explicit when-not guidance.

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

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

Annotations already say readOnly/idempotent/non-destructive, but the description adds substantial behavioral context beyond them: identity must match or nothing returns, an emailed 6-digit code triggers need_verification with a verificationId, the agent must call vivid_identity_verify and retry with the token, and production only begins after customer approval. This is exactly the kind of workflow disclosure 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?

Front-loaded with the state enumeration and caller phrasings before the mechanics. Slightly redundant — 'Requires the order number AND the email' is restated as 'CODE REQUIRED: needs the customer's email' — but every sentence carries actionable information, so the length is earned.

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

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

No output schema exists, yet the description names the returned artifacts an agent must act on (agent_hint, need_verification, verificationId) and the production-start condition. Combined with the fully documented input schema, nothing needed to invoke or follow up 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, but the description adds real meaning: it explains that email is used for identity matching (not just a lookup key) and that token gates whether the approve/reject link is returned. It also clarifies the two-required-parameter contract via the verification workflow.

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 ('Check a customer's DIGITAL PROOF status') and enumerates the possible states (emailed, awaiting approval, being revised, approved/production underway). An agent can distinguish it from vivid_order_status or vivid_fulfilment_production_stage 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?

Gives concrete caller phrasings ('where's my proof', 'did you send my proof') that map directly to the tool, states the prerequisites (order number AND matching email), and routes to the sibling vivid_identity_verify inside a step-by-step flow. When-to-use 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds a genuine behavioral trait beyond that: omitting either parameter returns the next question to ask the customer, revealing a conversational fallback mode. It does not describe return payload shape, but an output schema exists.

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, zero waste: purpose and product scope first, then the calling/omission rule. Front-loaded and every clause earns its place.

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

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

With an output schema handling return values and annotations covering safety and idempotency, the description needs only to state purpose, inputs and the fallback behavior, all of which it does. Nothing required 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 100% and both parameters carry example values, so the schema does the heavy lifting. The description only restates that goal and business are the inputs and adds the omission behavior, contributing nothing about format or accepted values beyond 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?

States a specific verb ('Recommend') plus resource ('Vivid Ads signage'), scoped by goal + business type. It names concrete product families (pull-up banners, A-frames, corflute, fabric banners, flags, media walls), which distinguishes it from generic siblings like vivid_product or vivid_cross_sell without opening their schemas.

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

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

Gives explicit calling guidance ('Call with goal and business; omit either to get the next question to ask the customer'), which tells the agent how and when to invoke it. It stops short of naming alternatives (e.g. vivid_cross_sell or vivid_price) or stating when NOT to use it, so it is clear context rather than full 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?

Annotations only give generic safety hints (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds critical behavior far beyond those: verified identity required, only APPROVED artwork is reused, a fresh proof is ALWAYS re-issued, re-pricing uses CURRENT pricing, it never charges a card, and the exact need_verification/verificationId return flow. This is exactly the behavioral detail a mutating tool needs.

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

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

It is long but front-loaded: purpose and verification requirement come first, then artwork rules, then pricing, then the code-required flow. Nearly every sentence carries operational weight (artwork constraints, pricing, no-charge). Slightly dense with caps emphasis, but not padded.

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 10-parameter, multi-step, proof-gated tool with no output schema, the description covers the full lifecycle: prerequisite verification, the two actions, artwork validation, re-pricing, draft creation, and the exact fallback return (need_verification + verificationId). An agent has everything needed to call it and handle the response.

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

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

Schema coverage is already 90%, so the baseline is 3. The description adds meaning beyond the schema by explaining the token prerequisite flow, the artwork-reuse default vs. supplying new artwork, quantity override, and the confirm-to-place semantics, tying parameters to the overall verification workflow.

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 ('Reorder a customer's previous signage job') and clarifies the output ('creates a proof-gated draft order'), which distinguishes it from vivid_place_order and vivid_accept_quote. An agent can immediately tell what the tool does and what it produces.

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 defines the two modes ('action:list' vs 'action:reorder'), states the prerequisite (identity verification via emailed one-time code), and names the alternative tool to route through (vivid_identity_verify). The 'when-not' is also implicit but clear: it shows nothing before verification.

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 by disclosing the two terminal statuses ('quoted' / 'received'), the content of the outgoing quotation (line items, GST, total, quote number, 14-day validity, accept-online link), and the hard constraint that no payment is taken. The main gap is retry behavior: with idempotentHint=false and no mention of idempotency_key in the description, an agent is not warned that a re-call without the key sends a second email.

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 action, then the branch logic, then the pre-submission checklist, then the safety constraint. Every clause carries distinct information — the parenthetical enumeration of quotation contents is the only dense stretch, and it usefully sets agent expectations. No filler or restatement of the name/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?

For a 13-parameter, open-world mutation tool with no output schema, the description supplies the essentials: the two outcomes, the trigger condition for each, the required confirmations, and the no-payment guarantee. It is not fully complete because the reseller/discount recording path and the idempotency/duplicate-email behavior are never surfaced in prose.

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 54%, so the description must carry weight, and it does: its confirmation checklist (product, quantity, size/options, name, email) covers exactly the fields the schema leaves undescribed, while the remaining parameters (design, message, options, artworkUrl, discountCode, idempotency_key) already carry schema text. It adds no syntax, format, or shape guidance of its own, capping this at 4.

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 ('Email the customer a formal QUOTATION') and immediately delimits scope with two named outcomes ('quoted' for priceable configurations vs 'received' for custom products) plus 'Never takes payment'. That last clause cleanly separates it from order-oriented siblings such as vivid_place_order and vivid_accept_quote, so an agent can place it in the flow 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 an explicit routing condition: if the exact configuration can be priced and an email is supplied, the tool instantly quotes; for custom/unpriceable products it degrades to a logged request. It also sets a precondition ('Confirm product, quantity, size/options, name, and email before submitting'). It stops short of naming the sibling to use instead when the customer actually wants to buy now.

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/openWorld annotations by disclosing that results are grounded in Shopify collections, that `sameRange:true` products come from the top match's curated collection, and that a from-price is indicative only. It also documents pagination signals (total, has_more, next_offset).

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

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

Front-loaded with the core action and then layered with the highest-value caveats (sameRange, indicative pricing, pagination). It is dense and long, but nearly every clause carries operational weight; only the parenthetical customer-quote example is slightly expendable.

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 explanation is not needed, yet the description still flags the key fields to act on (sameRange, collection, total, has_more, next_offset). Combined with sibling routing and the pricing caveat, it is complete for a search tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the query field's use-case framing is exemplified, and offset is tied to next_offset from the previous page rather than being a bare integer. Limit's max behaviour is left to 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 ('Search the Vivid Ads catalogue') and narrows scope to product name, category, or intended use with concrete examples. It also names overlapping siblings (vivid_product, vivid_price) so an agent can distinguish this tool without reading their schemas.

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

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

Explicit routing rules: use vivid_product for options and vivid_price for exact configuration after a from-price. It also states a mandatory interaction policy ('ALWAYS mention these to the customer') and explains when to pass offset. Both when-to-use and how-to-continue are covered.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: answers are grounded in the team's real support history + verified policy, and the tool degrades gracefully by returning escalate:true on no match. It doesn't mention grounding failures or confidence/rate behavior, keeping it below 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?

Front-loaded with purpose, then return behavior, then usage examples — a sensible priority order with no filler sentences. The long enumerated topic list is the bulkiest part but each entry maps to a real query class an agent might route here, so it earns most of its 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 single-parameter, read-only Q&A tool with an output schema present (so return shape needs no explanation), the description covers purpose, scope, fallback/escalation behavior, and triggering examples. Nothing an agent needs in order 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?

Only one parameter with 100% schema description coverage ('the customer's support question, in their own words'). Per the baseline rule, the schema already carries the parameter meaning and the description adds nothing about phrasing, length, or formatting constraints. A 3 is correct.

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+resource ('Answer a customer's support / FAQ question') with explicit scope: an enumerated list of covered topics (turnaround, proofs, artwork specs, pricing, delivery, cancellations, reorders, guarantee). This lets an agent distinguish it from narrower siblings like vivid_order_status, vivid_proof_status, or vivid_contact_team 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?

Gives four concrete trigger questions ('how long does it take?', 'what file format do you need?', etc.) and states the handoff condition when nothing matches (escalate:true). It lacks explicit when-not-to-use guidance, and a phrase like 'how long does it take?' plausibly overlaps with vivid_delivery_estimate / vivid_fulfilment_production_stage, with no stated boundary.

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

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

Annotations only declare readOnly=false, destructive=false, idempotent=false, openWorld=true; the description adds substantial context beyond them: it does NOT verify print-readiness, uploading needs no verification but attaching does, and an unverified upload is 'held unattached' with the reply saying so. That consequence-level disclosure is exactly what structured fields 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?

Front-loads what the tool does and returns before the caveats, and every sentence carries information (formats, verification stance, token gate). Capitalized emphasis is slightly noisy and the paragraph is dense, but there is no filler.

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

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

Even without an output schema, the description states the return shape (stable link plus metadata) and the security-gated attachment behavior. Format acceptance, storage destination, and the verification caveat are all covered, leaving nothing essential for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description reinforces the semantics that matter: the token gates attaching to an order and recording the email, and unauthenticated uploads are stored unclaimed. This ties token/orderId to a behavioral outcome the schema only implies.

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 ('Upload a customer's artwork FILE through the agent'), names the return value ('stable shareable link plus metadata'), and enumerates accepted formats. This clearly separates it from siblings like vivid_check_artwork or vivid_order_artwork by emphasizing raw file ingestion rather than verification or order attachment.

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

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

Gives an explicit trigger ('Use when a customer wants to send their print file via chat') and clarifies the attach-vs-hold condition, naming vivid_identity_verify as the prerequisite for attaching. It stops short of routing the agent to alternatives for print-readiness (vivid_check_artwork) beyond noting the team checks that.

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