InkFE Print

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

Beyond the annotations, the description reveals that this records agent-reported rather than human-click evidence, that it does not constitute payment consent, that the artwork/configuration is immutable, and that identical repeated approvals are idempotent. It even states the return fields approvalId, evidence, and expiry. This adds substantial behavioral context.

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

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

The description is front-loaded with the most important precondition and every subsequent sentence adds distinct value: evidence semantics, idempotency, change handling, and reuse rules. Despite its length, there is no fluff or 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?

For a write operation with no output schema, the description covers prerequisites, side-effect boundaries, idempotency, change policy, reuse conditions, and return fields. An agent has enough context to invoke it correctly and avoid treating it as payment consent or independent verification.

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

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

Schema description coverage is only 17%, so the description must compensate. It does explain the meaning and conditions for frontReviewed, backReviewed, and artworkApproved, and guestToken is fully documented in the schema. However, designToken and quoteToken receive no semantic explanation in either the schema or the description, leaving their roles partially implicit.

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 clearly states the tool records agent-reported artwork approval and explicitly distinguishes it from independent human-click evidence and payment consent. The verb 'Records' plus the resource 'customer proof approval' make the purpose unambiguous and distinguishable from sibling tools like refresh_design_proof.

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 an explicit precondition: only call after showing both previews, warnings, print options, and receiving explicit customer approval in the AI conversation. It also states when fresh approval is required and when a previous artwork approval can be reused, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations only indicate idempotent, non-read-only, non-destructive behavior, but the description adds substantial context: guest-draft expiry, seven-day token expiry, saveUrl ownership, sign-in/OAuth requirements, retry semantics for a stable requestId, and failure modes. It aligns with and enriches the idempotentHint 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?

The description is dense and front-loaded with the core behavior, and nearly every sentence carries important operational detail. However, it is a very long single paragraph with many embedded user-facing instructions and workflow rules, which makes it harder to scan; bulleted or sectioned formatting would improve structure without losing content.

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 fully compensates by enumerating return values (designToken, designId, previews, expiresAt, warnings), explaining preview URL behavior, listing error codes, and covering authorization, expiry, and downstream workflow steps. An agent has enough context to invoke the tool correctly and handle its results.

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 already covers all five parameters at 100% coverage, so the baseline is 3. The description adds meaningful extra semantics: fields must be non-blank and keyed by attribute, logoUrl is omitted unless the template has imageUrl, and blank/missing values fail with missing_required_fields. It does not add much about guestToken, but the schema already documents that fully.

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 resource: applying field values and a logo to a template, fitting text, rendering previews, and returning a design token. It clearly distinguishes itself from siblings by naming revise_business_card_design and refresh_design_proof as the alternatives for revisions and expired links.

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 explicitly instructs the agent to call list_business_card_templates first, to use revise_business_card_design for revisions, and to refresh expired links instead of creating another design. It also ties this tool into the larger checkout flow by naming approve_design_proof and create_checkout as follow-up steps, making when-to-use unambiguous.

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

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

Annotations are all false/negative (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description carries the burden of behavioral disclosure and meets it thoroughly. It discloses the side effect of creating a purchase attempt ('One approval creates one purchase attempt'), the non-idempotent retry semantics, that unknown cart outcomes 'stay on hold', and that Shopify verifies the subtotal before returning a payment link. It also enumerates the full failure surface. No contradiction with 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?

Purpose is front-loaded in the first sentence, and every sentence earns its place: prerequisites, retry semantics, quote-change handling, and failure modes. The main flaw is structural — it is one dense, unbroken paragraph with a very long error-code list appended, making it harder for an agent to scan quickly despite the high information density.

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

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

For a tool with 7 parameters, nested objects, no output schema, and sequencing dependencies on four siblings, this description is remarkably complete. It covers prerequisites, ordering, retry/quote-change behavior, the explicit return fields (quoteId, quotedSubtotal, checkoutUrl, cartId, designAssetId, lineItem) since no output schema exists, and the complete error code surface.

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% with detailed per-parameter descriptions (e.g., buyer.email 'does not prove ownership', selectedOptions keyed by option name). The description adds genuine value by linking parameters to the workflow — which prior call each token originates from (approvalId from approve_design_proof, quoteToken from get_quote, designToken from create_business_card_design) and the confirmUpdatedQuote retry semantics — context the schema alone doesn't provide.

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

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

The opening sentence names a specific verb-resource pair ('turns a design token from create_business_card_design plus the buyer's chosen pack options and email into a Shopify checkout URL') and states the concrete output (checkout URL with print-ready artwork attached to the line item). It clearly distinguishes itself from siblings like approve_design_proof and get_quote by positioning itself as the terminal purchase step.

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 call: 'Call this only after the buyer has approved both design previews and chosen a value for every customer-facing option get_product lists.' It enumerates required prerequisites (approvalId from approve_design_proof, quoteToken from get_quote), and gives precise when-not-to-use guidance (retries keep same approval; uncertain outcomes require recovery, never replacement; expired/changed quotes require fresh quote and renewed confirmation).

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 as readOnly, idempotent, and non-destructive. The description adds valuable behavior: it fails with product_unavailable for unknown/non-public handles, explains that availableForSale=false variants cannot be bought, and explicitly warns that a resolved variant is not artwork approval or a purchase quote. No contradictions with annotations.

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

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

The description is dense but front-loaded with the core purpose and return summary. The final sentence about quantity, artwork, source, and policies is somewhat cryptically worded and arguably could be clearer, but the overall structure is efficient and each part contributes useful context.

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

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

With no output schema, the description carries the full burden of describing the return value, and it does so thoroughly: fields, variant semantics, selection behavior, failure modes, and important caveats. It is complete enough for an agent to call the tool correctly in typical scenarios.

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 adds meaningful semantics beyond the schema: selectedOptions must use the exact name/value pairs from the variant, and supplying selectedOptions triggers resolution with missing/invalid/unavailable guidance. This meaningfully aids 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?

The first sentence names a specific verb ('Describe') and a precise resource ('one public InkFE product by handle'), which is unambiguous. It differentiates itself from sibling tools like search_products and list_business_card_templates by focusing on a single product rather than listing or searching.

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 clearly establishes when to call it: when you have a handle and need a full product description. The parameter guidance in the schema reinforces that handles come from search_products or list_business_card_templates. However, it does not explicitly state when not to use it or name alternatives, 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 (read-only, idempotent, non-destructive), the description discloses the 10-minute quoteToken expiry, unspecified shipping/tax/discounts until checkout, the distinction from a price lock, and the directive to show terms and obtain confirmation before proceeding. These behavioral details are essential and well beyond what annotations convey.

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

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

The description is front-loaded with the core action.educated, then layers returns, limitations, and usage cautions in logical order. Every sentence earns its place; none are filler, and the length is appropriate for the nuances it must communicate.

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 fully explains what is returned (quantity, subtotal/currency, quoteToken, production business-day range) and what is not returned until checkout. It also covers constraints, expiry, and the required confirmation step, making this description self-sufficient 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 67%, with handle and lineQuantity well described. The description reinforces that numeric line quantities are unsupported and that only business-card pack handles are valid, adding some context. However, selectedOptions itself has no description and the description does not clarify what name/value options should be supplied, leaving a material gap.

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

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

The description opens with a precise verb and object: 'Read an exact available variant price for the configured business-card pack.' It clearly distinguishes this quote tool from the related product/get_product and create_checkout siblings by scoping it to business-card packs and quote-only behavior.

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

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

The description gives clear guidance on when this tool is appropriate: it is a read-only quote builder, not a price lock or delivery promise, and numeric quantities and other products are unsupported. It also points to the next step (create_checkout). It stops short of explicitly naming alternative tools for unsupported cases, which keeps it from 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds substantial behavioral context by detailing the returned fields (templateId, orientation, previewUrls, etc.) and explaining their semantics, plus the field-level attributes and workflow requirements. It does not contradict annotations but also doesn't mention error cases or limitations, which are minor for a read-only list 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?

The description is lengthy but well-structured: it opens with purpose, enumerates output fields, explains each field type, and then gives a clear workflow. It is front-loaded and every sentence adds value, though it could be trimmed slightly without losing meaning. The organization compensates for its length.

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 absence of an output schema, the description thoroughly explains the return values and their semantics, including field attributes, input types, requiredness, and sample values. It also ties into the surrounding toolchain (get_product, create_business_card_design, get_quote, create_checkout), making it complete for an agent to use correctly.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description adds no parameter-specific details because there are none, which is appropriate.

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

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

The description explicitly states it lists business card templates and positions it as the entry point for the design workflow ('Start here to design a business card'). It clearly distinguishes itself from siblings by describing its output (template details) and the downstream steps, making its role unambiguous.

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 provides explicit guidance on when to use this tool (as the first step) and how to proceed: checking productHandle with get_product, then calling create_business_card_design, get_quote, and create_checkout. It also notes it takes no arguments, leaving no ambiguity about invocation.

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, so the description only needs to add nuance. It adds meaningful context: 'refresh' does not extend expiry, does not grant approval, and requires the original guest/integration or verified owner. No contradiction with annotations.

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

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

Three sentences front-load the action and then pack in the key exclusions and preconditions. No filler or repetition of schema details.

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

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

For a small read-only, idempotent tool with annotations present, the description covers the operational intent, preconditions, and negative boundaries. It doesn't need to restate return values since none are promised beyond 'both saved images,' and no output schema exists. Minor gap: no explicit mention of what the returned images/links contain, but the essentials are present.

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 describes guestToken fully but leaves designToken undocumented (50% coverage). The tool description does not compensate for designToken's missing semantics; it only references 'the same immutable design' in passing. With half the parameters carrying no description in either schema or description, this is a clear gap.

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

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

The description opens with a specific verb+resource: 'refresh expired front/back proof links and return both saved images.' It explicitly distinguishes itself from approve_design_proof and revise_business_card_design by stating what it never does ('never rerenders, extends design expiry, or grants approval'). Clear scope, no tautology.

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 states the precondition ('Requires the original guest/integration or verified owner') and gives a clear exclusion ('Missing or expired design state requires a new design and review'). It also spells out the boundaries of the operation, so an agent knows not to use it for rerendering or approval. It does not explicitly name sibling tools, but the behavioral exclusions effectively guide selection.

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 are minimal (readOnlyHint=false, idempotentHint=true), and the description adds substantial behavioral context: immutability of the new design, requirement for prior authorization, the fact that prior approval does not carry over, idempotent retry semantics via requestId, return of previews and a new designToken, and the caveat about changed templates. This is exactly the kind of behavioral disclosure that helps an agent avoid misuse.

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

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

The description is compact but information-dense, with no filler. Each sentence delivers a distinct operational requirement: base design, complete fields, requestId semantics, return values, approval non-transfer, and template-change fallback. The most important constraint about creating a new immutable design is front-loaded.

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

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

For a tool with non-obvious behaviors around immutability, idempotency, guest vs. authenticated flows, and approval carry-over, the description plus schema covers all critical aspects. Even without an output schema, it states what the caller gets: previews and a new designToken. No essential usage information is missing for an agent 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 already high (80%), and the description adds valuable parameter semantics beyond the schema: complete field set required, logo passed via logoUrl only when the template has an imageUrl field, new requestId for intentional edits versus same id for retries, and guestToken usage constraints. The designToken parameter is less elaborated, but the description clarifies it as both an input and a newly returned token.

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 operation: 'Create a new immutable design from an authorized prior design, using the same published template revision.' This clearly distinguishes the revision action from creating a fresh design and from merely refreshing a proof. The title and description align without any circular phrasing.

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

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

The description gives concrete usage context: use it for intentional edits to an authorized prior design, and explicitly says not to use it as a partial patch. It also provides an alternative route: 'If the template changed, select its current version and create a new design.' It does not explicitly name sibling create_business_card_design, but the behavioral boundary is 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?

Annotations already mark this as destructive and idempotent, but the description adds valuable context: existing orders are unaffected, artwork is not deleted, and a private token is required. These details go beyond the annotations and clarify the tool's side effects and security boundary, making the behavior transparent for the agent.

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 sentences, front-loads the core action, and each sentence adds meaningful information without redundancy. It is tightly written and efficient, scoring high on conciseness.

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 tool with no output schema, the description covers the essential behavior, limitations, and non-effects. It does not describe the return value, but that is not required when no output schema exists. The description is complete enough for an agent to understand when and how 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?

The input schema has 0% description coverage, so the description must compensate. It refers to the 'supplied guest session' and mentions a 'private token,' which implies guestToken is the private identifier, but it never explicitly defines the parameter. This gives some meaning but leaves the exact nature of guestToken implicit, so it does not fully compensate for the schema's lack of description.

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 clearly states the action (revokes a guest session) and the result (cannot create designs or checkout again). It is distinct from sibling tools like start_guest_session, which creates sessions, and there is no other revoke-like tool, so the purpose is unambiguous.

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

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

The description implicitly indicates when to use this tool (when you need to revoke a guest session) but does not explicitly state when not to use it or mention alternatives. It does provide a constraint ('cannot revoke another session without its private token'), which limits usage, but lacks explicit routing guidance compared to the best examples.

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 provided (readOnlyHint=true, destructiveHint=false) already cover safety. The description adds important context such as 'Prices are not quotes', the distinction between catalog visibility and template support, and the nature of failed detail reads. However, it doesn't detail what happens with zero results or any rate limits, but given annotation coverage the added context is strong.

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

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

The description is compact for the amount of information, but it packs several details into one long sentence at the start. It front-loads the core purpose, but the sentence could be broken up for readability. Still, every sentence adds value, and no fluff exists.

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 moderate complexity (5 params, no output schema), the description covers the key points: return fields, the next step (get_product), and clarifying caveats. The absence of an output schema is compensated by describing the returned data. Slight gaps remain on edge cases like zero results or pagination, but it is robust overall.

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 thoroughly. The description adds a note about the `limit` parameter (returns up to `limit` products) and mentions the optional filters, but does not add much beyond what the schema says. Baseline 3 is appropriate due to high coverage.

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 clearly states the tool's function: searching the public InkFE print catalog by free text. It also explicitly distinguishes itself from siblings like list_business_card_templates and get_product, making its purpose unambiguous.

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 provides explicit when-to-use guidance ('when the buyer wants something other than a business card') and when-not-to-use ('Business cards designed from a template do not need this tool'), explicitly naming the alternative list_business_card_templates. It also mentions using get_product after this, providing clear 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?

The description goes well beyond the sparse annotations by disclosing token validity (seven days), draft retention (30 days), the fact that checkout records are protected, and that starting a session does not place or pay for an order. This gives the agent a clear behavioral model without relying on 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?

The description is longer than average, but almost every sentence carries operational value: eligibility, exclusions, required customer disclosure, token expiration, and downstream recipients. It is front-loaded with the most important condition. A small amount of detail, like the contended 'Checkout or unresolved purchase records are protected' sentence, is slightly less actionable.

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

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

With no output schema, the description correctly explains what the tool returns (a private guestToken) and how it should be used. It also covers the main prerequisites and side effects. Minor gaps remain, such as not describing explicit failure conditions or revocation, but overall the description is sufficient 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?

The input schema has zero parameters, so the baseline is 4. The description appropriately focuses on the tool's return value and downstream usage rather than inventing parameter details. There is no parameter ambiguity to resolve.

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 clearly identifies the tool's function: starting an InkFE guest session, explicitly scoped to anonymous callers when guest access is enabled. It also differentiates the tool from connected sign-in and integration-key flows, and names the downstream tools that should receive the guestToken.

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

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

The description gives explicit when-to-use guidance (anonymous callers, guest access enabled), when-not-to-use guidance (already connected via OAuth or provisioned key), and concrete post-conditions (pass token to create_business_card_design and create_checkout). This is unusually actionable.

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