Commonlands Optics: M12 Lens and C-Mount Lens Finder + Field-of-View Calculator

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

Annotations already indicate safe read-only, idempotent, non-destructive behavior. The description adds valuable context: returns live backend FoV when configured, distortion status, image-circle coverage, live stock via Shopify, and MTF/CRA/BFL fields if present. It also discloses result labeling for custom sensors and the rectilinear reference marker, going well beyond 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 long but well-structured and front-loaded with purpose. It flows from purpose to usage to parameters to edge cases, with each sentence earning its place. While not terse, the verbosity is justified by the tool's complexity and the need to disambiguate from naive calculations and many aliases.

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 (17 params, multiple aliases, output schema present), the description covers the main purpose, when to use it, parameter selection strategies, result caveats, and fallback behavior. It omits error handling or authentication details, but with output schema and annotations, it is sufficiently complete for an agent.

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 adds meaningful grouping and usage semantics: it explains the alias pairs (lens_sku/lensSku, etc.), outlines alternative sensor description methods (pixels+pitch vs. mm dimensions), and clarifies when to use focal length vs. lens SKU. This enriches parameter understanding 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?

The description clearly states the tool calculates Commonlands lens field of view for a lens/sensor pair and returns specific outputs (HFOV, VFOV, DFOV, coverage, distortion status, rectilinear comparison). It also names common request phrasings it handles, distinguishing it from naive math and sibling tools.

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 provides when to use ('Use this tool for FOV, HFOV, VFOV, DFOV...') and when not to ('Do not use naive rectilinear fallback, focal-length-only math...'). It also explains the fallback behavior when only focal length is given, giving clear guidance on 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 already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: it requires a meta["idempotency-key"] UUID for retry safety (explaining how to make a non-idempotent destructive call safely) and states the auth requirement via cart_access_token from create_cart. It stops short of saying what happens to an already-cancelled cart or whether cancellation is reversible.

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

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

Three short sentences, zero filler, with the action and its identifiers front-loaded followed by the retry-safety requirement and the scope exclusion. Every sentence carries distinct information.

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

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

For a three-parameter destructive mutation with no output schema, the description covers identifiers, the idempotency contract, and the domain boundary. Missing only the return shape and the behavior on repeated/already-cancelled calls, which are minor for an agent to proceed.

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

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

Schema description coverage is only 33% (only cart_access_token is documented), so the description must compensate and largely does: it identifies `id` as the cart id, `cart_access_token` as the owner token, and specifies that the otherwise-opaque `meta` object must carry an idempotency-key UUID. The remaining gap is that `meta` is a free-form nested object and only one key is documented.

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 (cancel) and resource (Shopify-owned cart) and scopes it to carts the platform owns, which separates it from the order/refund domain. It does not explicitly name the sibling alternatives (get_cart, update_cart, create_cart), but the verb alone makes the intent 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 closing sentence gives a useful exclusion ("does not cancel an order or refund payment"), which steers agents away from order-cancellation tasks. However, it never says when to reach for cancel_cart versus update_cart or get_cart, nor what precondition (e.g. cart still active) must hold.

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 context beyond annotations (deterministic scoring, explanatory context, not live truth) and does not contradict them. Could mention rate limits or data freshness but upfront.

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: main purpose, usage guideline, caveat. Every sentence adds value and 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?

Missing output description or what 'compare' returns, nor explanation of scoring model. Adequate for a comparative tool but would benefit from output schema or return details.

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 low (33%), and the description does not elaborate on parameters like lensSkus constraints or workingDistanceMm meaning. More detail needed to guide input.

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 compares specific Commonlands M12 and C-mount lens SKUs on the same sensor with the same scoring model, distinguishing it from siblings like calculate_field_of_view.

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 says to use as explanatory context and then call calculate_field_of_view for precision, and warns against estimating FoV from catalog fields, providing clear when-to-use and 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?

Adds real behavior beyond the annotations: the returned cart_access_token must be retained for get_cart/update_cart, sign-in/approval/payment are delegated to Shop, and no order is placed. It does not address retry semantics (annotations declare idempotentHint=false, so repeated calls presumably create duplicate carts) or what a failed creation returns — a minor gap given annotations already carry the safety profile.

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

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

Five tight sentences, purpose front-loaded, then token retention, then the branching guidance, then the negative guarantee. Every sentence changes what the agent would do; nothing is restated from the title or annotations.

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

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

For a non-idempotent mutation tool with no output schema, the description still discloses the key returned artifacts (cart_access_token, agent_checkout) and the handoff flow. What remains thin is the shape of the required `cart` payload, which an agent must infer from the schema alone.

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 50% — only `meta` is documented in the schema. The description's "live variants and quantities" loosely maps to line_items[].item.id and quantity, but says nothing about the 1–25 item bounds, the quantity 1–999 range, or the opaque `context`/`signals` nested objects. Baseline 3 fits: some value added, but the coverage gap is not compensated.

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 ("Create a Shopify-owned cart") with the precondition ("after buyer confirmation of live variants and quantities") stated up front. It is clearly separable from create_checkout, which the description names as the alternative path.

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 routes the agent: agent-authorized purchase → returned agent_checkout route in the buyer's Shop MCP connection; otherwise → Commonlands create_checkout for a payment link. Sibling alternatives and their selection conditions are both named, plus the negative case ("places no 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?

Adds real behavioral context beyond the annotations: no order is placed, checkout_access_token must be retained, and the buyer must be sent to continue_url for review and payment. It omits one meaningful trait the annotations imply but don't explain to an agent – idempotentHint=false means repeated calls likely create duplicate checkouts, which the description never warns about.

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 dense sentences with the precondition first, the two invocation modes next, and the outcome contract last. No filler, and the most decision-relevant fact (no order placed) is not buried.

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

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

With no output schema, the description does the necessary work of naming the response fields that matter (checkout_access_token, continue_url), so an agent can complete the flow. Minor gaps remain: no warning about non-idempotency or about what happens to the source cart after conversion.

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

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

Schema coverage is 67%, and the description compensates by spelling out the either/or relationship between checkout.cart_id (with cart_access_token) and checkout.line_items, a constraint the schema itself does not encode. It adds little on the nested line_items structure or meta, but those are documented in the schema.

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

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

States a specific verb and resource ('Prepare a Shopify checkout') and immediately scopes it to the post-confirmation moment, which separates it from create_cart/update_cart and from prepare_shopify_purchase_handoff. The final clause ('this does not place an order') pins down the exact operation boundary.

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 triggering condition: only after the buyer confirms exact live variants and quantities, with two documented entry paths (cart conversion vs. direct line_items). It does not explicitly name an alternative sibling or say when NOT to use it, e.g. when the buyer is still browsing or when a checkout already exists.

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, so the description focuses on what they can't say: the agent_checkout field is informational only and does NOT place an order, which prevents a costly misinterpretation. It also advises retaining id, token, and continue_url, though it doesn't describe error behavior for an invalid or expired token.

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

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

Three tight sentences, front-loaded with the action, followed by retention guidance and the critical agent_checkout caveat. No filler, though the third sentence is long enough to be split.

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 names the key return fields (full cart id, owner token, continue_url, agent_checkout) and their purpose. Missing only edge-case behavior such as what happens with an invalid token or a cancelled cart.

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

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

Schema coverage is 67% and the schema itself already says cart_access_token is 'returned by create_cart', so the description largely restates the same provenance. The nested 'meta' parameter remains 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 (Retrieve) and resource (Shopify-owned cart), and explicitly ties it to the create_cart flow, distinguishing it from create_cart/update_cart/cancel_cart siblings. An agent can identify the operation 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?

It establishes the precondition clearly: the cart must have a cart_access_token produced by create_cart. It doesn't spell out when a caller should prefer get_cart vs get_checkout or update_cart, 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 readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: 'fixture-backed' hints at test data, and 'non-authoritative product-truth warning' discloses data reliability. 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?

One sentence that front-loads the verb and packs all return items without fluff. Every word contributes meaning. Perfectly concise for a zero-parameter tool.

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, but the description lists the key return elements. It lacks details on exact structure or field types, but for a status endpoint with no parameters, the coverage is reasonable. Could be slightly more specific about the 'non-authoritative' warning.

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?

No parameters exist (0 params), so baseline is 4. The description focuses entirely on output semantics, which is appropriate given 100% schema coverage for parameters.

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

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

The description uses a specific verb 'Return' and clearly enumerates the exact data items (counts, validation status, source provenance, live connector readiness, warning). It distinguishes this tool from siblings by highlighting its comprehensive status nature, and no sibling overlaps with this combination.

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 no information about when to use or avoid this tool, nor does it mention any alternatives among the listed siblings (e.g., get_shopify_readonly_config_status, lookup_catalog). Agents must infer usage from the name alone.

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

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

Annotations already cover the safety profile with readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds useful behavioral context by noting that buyer and payment details are withheld and that continue_url is the buyer-facing next step. It does not describe the full summary shape, but the privacy and handoff behavior are clearly disclosed.

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

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

Three short sentences with no filler. The core read behavior is front-loaded, followed by privacy scope and the buyer handoff step, all of which earn their 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 checkout lookup with no output schema, the description gives enough context to invoke it and understand the intended handoff workflow: required id/token, withheld buyer/payment details, and continue_url. The optional meta parameter and the exact summary contents remain unexplained, so it is not fully complete.

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

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

Schema coverage is 67%, and the schema already describes both required parameters: id as a Shopify Checkout gid and checkout_access_token as the owner token from create_checkout. The description reinforces the token provenance but adds no further meaning, and it does not explain the optional meta object.

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 gives a specific verb and resource: read a Shopify checkout handoff summary. It also distinguishes this from create_checkout by tying the required id/token to that sibling and clarifying that this returns a handoff summary rather than creating a checkout.

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

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

It clearly says to use the id and checkout_access_token from create_checkout, and it tells the caller to send the buyer to continue_url for review and payment. It does not explicitly state when not to use it or name alternatives beyond create_checkout, so it falls short of full when/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 mark the tool as readOnly, idempotent, and non-destructive. The description adds critical behavioral context: it returns live backend FoV when configured, cannot derive data from the model, and warns against inventing polynomial coefficients. This goes well beyond the annotations and fully informs the agent of the tool's behavior.

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

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

The description is somewhat lengthy but front-loads the core purpose and contains no filler sentences. Every sentence earns its place by adding unique guidance or constraints. Could be trimmed slightly but remains effective.

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 lists return fields (FoV, distortion, image-circle coverage, live stock, MTF/CRA/BFL) and explains limitations. It also clarifies what the tool cannot do, making it complete for the agent to understand what to expect.

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 100% coverage with descriptions for all three parameters (sku, lensSku, lens_sku). The description does not add meaning beyond repeating the SKU examples (CIL250), which are already in the schema. Baseline 3 is appropriate since schema carries the burden.

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 it returns the Commonlands distortion model/status for one lens SKU, lists specific data returned (FoV, distortion, MTF, etc.), and differentiates from siblings by telling the agent not to use naive fallback methods. This exceeds the minimum viable detail.

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 explicitly lists when to use the tool (e.g., for FOV, distortion, MTF queries) and when not to use it (e.g., don't invent coefficients or use rectilinear fallback). While it doesn't name sibling tools directly, the 'do not use' instructions serve as clear guidance, making it a strong 4.

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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral context by stating it is fixture-backed and provides optical metadata, and warns against misusing for sensor-specific FoV. No contradictions.

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-loaded with core purpose, each sentence adds value. No redundancy or unnecessary 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?

Good annotations and usage guidance cover safety and selectivity. However, missing parameter descriptions and no output schema mean the agent may lack full context on response format and how to use meta/catalog. Still adequate for a read tool with clear purpose.

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

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

Schema description coverage is 0%, and description does not mention any parameters (meta, catalog). While the schema defines structure, the description adds no meaning beyond the schema. For a tool with required nested parameters, this is a significant 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?

Description specifies it retrieves 'Fixture-backed UCP Catalog product detail alias' with optical metadata and Shopify handoff fields. It distinguishes from calculate_field_of_view and match_lens_to_sensor by explicitly stating it is not for sensor-specific FoV.

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 not to use this tool for FoV estimation and directs to alternatives: 'call calculate_field_of_view for the lens/sensor pair' and 'use calculate_field_of_view or match_lens_to_sensor'. Provides clear context for appropriate use.

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. Description adds 'fixture-backed' (not live) and 'gated datasheet policy' (access restrictions). Warns about FoV limitation, which is useful behavioral context beyond 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?

Very concise: two core sentences plus a one-sentence FoV rule. Every sentence adds value. Front-loaded with main purpose. No fluff.

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 full schema coverage, annotations, and no output schema, the description covers purpose, usage context, and behavioral caveats. Slightly ambiguous what 'handoff details' precisely includes, but overall complete for agent decision-making.

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% with clear description of sku parameter (format and example). Description does not add parameter-specific meaning, which is acceptable since the schema already provides sufficient detail. Baseline 3.

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?

Clearly states the tool returns fixture-backed product-page handoff details for one lens, including specific content (optical specs, gated datasheet policy). Distinguishes from siblings like calculate_field_of_view and read_shopify_products.

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 tells when to use alternatives: calculate_field_of_view for sensor-specific FoV, read_shopify_products for live data. Provides a negative rule ('never estimate sensor-specific FoV') and directs to specific sibling 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=true, idempotentHint=true, and destructiveHint=false. The description adds value by stating 'without mutating commerce state' and mentioning the channels (Commonlands MCP, Shopify-native). No contradictions. It does not discuss rate limits or auth, but overall behavior is well disclosed.

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 concise and front-loaded with the primary purpose. It includes a clear rule about FoV usage. The structure is effective, though the rule about FoV could be moved to a separate section for clarity.

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 has 5 parameters, no output schema, and many siblings, the description lacks details on parameter meanings and return format. It provides good context on FoV differentiation but misses broader commerce workflow context.

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

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

Schema description coverage is 0%, so the description must explain parameters. It does not. 'sku' is implied but not defined; quantity, agentType, buyerIntent, sensorPartNumber are entirely unexplained. The description adds no meaning beyond the schema's parameter names.

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 returns 'safe dual-channel purchase route options' for AI agents and robotics engineers, without mutation. It distinguishes itself from sensor-specific FoV tools (calculate_field_of_view, match_lens_to_sensor) by specifying that those should be used for sensor-specific FoV.

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 guidance on when to use this tool (for purchase route options) and when not to (for sensor-specific FoV, recommending alternative tools). However, it does not clarify when to use this over other commerce-related siblings like create_cart or prepare_shopify_purchase_handoff.

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. Description adds that in production it uses a read-only live sensor table with fixture fallback when unavailable, providing useful context beyond 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 well-structured with the main purpose first. Each sentence adds value, though the last sentence about the FoV rule is instructional rather than descriptive. Still, it is appropriately sized and 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?

Given no output schema, the description adequately explains return values and data sources. It references sibling tools for further computation, making the context complete for an agent to understand the tool's role.

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% for partNumber. The description adds meaning by explaining what the tool returns (dimensions, pixel pitch, resolution) and that it handles specific lens types, partially compensating for the lack of output schema.

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

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

The description clearly states the tool returns sensor dimensions, pixel pitch, and resolution for specific lens types (field of view, M12, C-mount). It distinguishes from siblings by specifying that it provides inputs for calculate_field_of_view or match_lens_to_sensor, not for hand-calculation.

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 (as inputs to calculate_field_of_view or match_lens_to_sensor) and when not to (do not hand-calculate FoV). Provides a clear rule to avoid estimating sensor-specific FoV from catalog fields.

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. The description adds value by noting it does not expose secrets or call Shopify, which are key behavioral traits 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?

The description is a single sentence with no fluff, front-loading the purpose and key constraints. Every part adds value.

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

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

The description explains what is reported but does not describe the return format or structure. Given no output schema, a hint about the response would improve completeness. It is adequate but not fully comprehensive.

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 with 100% coverage, so baseline is 4. The description does not need to add parameter info, and it correctly describes the output without referencing parameters.

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

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

The description clearly states it reports sanitized Cloudflare Shopify binding presence, approved read scopes, and read-only safety flags, without exposing secrets or calling Shopify. This specific verb+resource combination differentiates it from sibling tools like 'read_shopify_products' or 'get_shopify_ucp_readiness'.

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 explains what the tool does but does not explicitly state when to use it versus alternatives. Siblings like 'get_shopify_ucp_readiness' suggest similar contexts, but no guidance on when this tool is preferred or not.

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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool reports readiness, which is consistent. No contradictions, but little extra value beyond 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?

Single sentence with reasonable conciseness. However, it packs in jargon ('Commonlands engineering differentiators') which may reduce clarity.

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

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

No output schema exists, so description should explain return values. It mentions what is reported (compatibility, blockers, differentiators) but lacks detail on structure or format, leaving gaps.

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?

No parameters exist, so schema description coverage is 100%. The description does not need to explain parameters, and baseline is 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?

The description clearly states the tool reports Shopify Storefront MCP and UCP Catalog compatibility, launch blockers, and differentiators. It uses specific terminology but is somewhat jargon-heavy, and it distinguishes itself from siblings like get_shopify_readonly_config_status by focusing on UCP readiness.

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?

No guidance on when to use this tool versus alternatives. The description does not mention prerequisites or conditions for use, leaving the agent to infer.

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 annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds that it is 'fixture-backed' and 'returns not-found messages instead of writes,' which aligns with read-only behavior. It does not contradict annotations and provides useful extra context about the nature of the 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 three sentences and free of unnecessary words. It front-loads the main purpose then adds relevant usage guidance. Could be slightly more structured but is concise and efficient.

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 no output schema, nested parameters, and low schema coverage, the description is incomplete. It covers purpose and usage but lacks explanation of input parameters and output format, leaving gaps for an agent to correctly invoke the tool.

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

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

The description does not explain the parameters (meta, catalog.ids) or their usage. With 0% schema description coverage, the description fails to compensate by clarifying what the parameters are for or how to use them. Only the general identifier types are mentioned, but not linked to the schema's structure.

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 it is a 'Lookup UCP catalog products' tool for identifiers like product, variant, SKU, handle, or URL, and specifies it returns not-found messages. It clearly distinguishes from siblings by mentioning when not to use it (for sensor-specific FoV).

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 provides when to use vs alternatives: 'Lookup records are not enough for sensor-specific FoV; call calculate_field_of_view...' and states a rule to use calculate_field_of_view or match_lens_to_sensor instead. This gives clear guidance for correct tool 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 already indicate readOnly, idempotent, and non-destructive. The description adds valuable context about live backend data (FoV, distortion, stock via Shopify) that the model cannot derive on its own. It also warns against shortcut assumptions, enhancing transparency 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?

The description is highly repetitive, containing near-identical sentences multiple times (e.g., the 'Use this tool for' and 'Do not use' phrases appear twice, and the sensor alias list is duplicated). This verbosity obscures the core message and could be streamlined to a single clear statement.

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 complexity of 18 parameters and multiple aliases, the description covers purpose, usage, parameter alternatives, and even output labelling (CUSTOM-<w>x<h>). It does not explain return values in depth but the absence of an output schema means the description carries more weight; it is sufficiently complete for an agent to invoke 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?

While the schema provides individual parameter descriptions, the description ties them together by explaining alternative ways to specify a custom sensor (pixels × pitch vs. mm dimensions) and mentions the 'CUSTOM-<w>x<h>' output label. This adds meaningful semantic guidance beyond the raw schema, though the schema already covers most fields.

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

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

The description clearly states the tool's purpose: to find and rank Commonlands lenses for a sensor, FOV, working distance, mount, or 'lens for' request. It explicitly lists use cases (FOV, sensor part numbers) and distinguishes from siblings by directing away from naive rectilinear fallback and focal-length-only math when a Commonlands route exists.

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 'Use this tool for...' guidance and 'Do not use...' exclusions, including concrete examples like AR0234, IMX290, IMX477 and workflows such as M12/C-mount matching. This clearly differentiates when this tool should be selected over alternatives like search_catalog or recommend_lenses_for_application.

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 indicate read-only, idempotent, non-destructive. Description adds concrete examples of what it does not do (no carts, checkout, orders, inventory mutations) and preserves FoV provenance, providing additional behavioral context beyond 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?

Two sentences, each carries essential information. Front-loaded with the core action and constraints. No wasted words.

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

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

Lacks parameter details despite moderate complexity. No output schema, but annotations cover behavior. The concept of 'purchase handoff seam' could be clearer, but the description provides sufficient high-level context for selection.

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 has 0% description coverage, and the description does not explain any parameter's meaning or role. It only implicitly references 'selected lens' (sku) but ignores quantity, sensorPartNumber, and selectedVariantId. Fails to add value beyond the raw 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?

Clearly states it builds a read-only purchase handoff seam for a selected lens, with specific exclusions (no carts, orders, writes). Differentiates from sibling tools like create_cart, update_cart, and FoV tools.

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 says when to use: for carrying optical context into purchase handoff. Also provides a firm rule about FoV estimation, directing to specific tools and prohibiting estimation from catalog fields.

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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds useful context: public data only, no exact inventory counts, metafields limited to custom.* display fields, and explicit list of non-performed actions. 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?

Single paragraph of five sentences, front-loaded with key purpose. Every sentence adds information without redundancy. Compact and efficient.

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, but description covers return fields and limitations. Sibling tools are clearly differentiated (fixture vs live). Could mention pagination or limit behavior more explicitly, but schema already provides limit bounds.

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 baseline is 3. Description adds context for includeMetafields (allowlisted public metafields) and implies use of limit for result count. Does not explain sku, query, handle beyond schema, but overall adds some value.

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?

Description clearly states tool reads live purchasable product data from Shopify, listing specific fields (IDs, SKUs, prices, availability, URLs, metafields). Distinguishes from sibling fixture catalog tools as 'scaffold data only'.

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?

Describes appropriate use ('live purchasable product truth') and exclusions (public data only, no exact inventory counts). Mentions what it does not do (create carts, orders, etc.). However, does not explicitly name sibling alternatives like get_product or search_catalog.

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, idempotentHint, destructiveHint=false) are consistent. Description adds context about the ranking nature and a critical FoV rule, but doesn't disclose rate limits or return format.

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 are efficient and front-loaded: first for purpose, second for usage guidance and a key constraint. No wasted words.

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

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

Given 8 parameters and no output schema, the description provides a workflow but lacks details on output format and prerequisites. It clarifies usage intent well but could be more complete about the ranking output.

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 13%, with only sensorPartNumber described. The description adds general context for parameters (e.g., application, working distance, FoV) but does not explain maxResults, requireInStock, etc. Does not fully compensate for low 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 it 'Rank Commonlands M12 lenses and C-mount lenses for an application note,' using a specific verb and resource. It also distinguishes from sibling tools by naming calculate_field_of_view and match_lens_to_sensor as follow-up tools.

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 says to use as an 'application shortlist helper' then call sibling tools for final FoV, and warns against estimating from catalog fields. However, it doesn't address when to use this versus other siblings like compare_lenses.

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

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

The description adds behavioral context beyond annotations (readOnlyHint, idempotentHint, destructiveHint) by stating it is fixture-backed, uses no live Shopify calls, and does not affect cart behavior. No contradictions.

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 key purpose and constraints, followed by usage guidelines and a specific rule. However, the sentence about FoV is somewhat repetitive and could be streamlined.

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 no output schema, the description does not describe the return format (e.g., product details, pagination). It explains behavior well but lacks details on query semantics or the meaning of 'limit'. The extra fields in 'catalog' (additionalProperties) are unaddressed.

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

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

With 50% schema description coverage, the description does not elaborate on the 'meta' or 'catalog' parameters, missing an opportunity to clarify their usage. The description only implies 'broad discovery' relates to query, but provides no additional semantic value beyond the schema's basic descriptions.

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 as a 'Fixture-backed UCP Catalog search alias for Shopify-native product discovery', specifying the verb (search) and resource (UCP catalog). It distinguishes from siblings by noting it is for broad discovery and not for sensor/FoV tasks.

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—'only for broad discovery'—and when not to—'when a sensor or target FoV is involved'—providing alternative tools (match_lens_to_sensor, calculate_field_of_view). This is exemplary 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 declare readOnlyHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: returns live backend FoV, distortion model, image-circle coverage, live stock, MTF/CRA/BFL. No contradictions.

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 well-structured and front-loaded with the primary purpose. However, it is somewhat verbose, repeating sensor part numbers and including warnings that could be condensed. Still, every sentence adds value.

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 has no output schema, the description fully explains input capabilities, return data, and alternative tools. It covers all necessary context 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 50% (only 'query' described). The description adds meaning beyond schema: lists searchable terms (SKU, mount, lens type, etc.) and exclusions (sensor names). However, 'limit' parameter is not elaborated in 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 it searches the Commonlands lens catalog by specific fields (SKU, mount, lens type, etc.) and distinguishes from match_lens_to_sensor for sensor part numbers. The verb 'search' and resource 'Commonlands lens catalog' are specific.

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 specifies when to use this tool vs alternatives: sensor names → match_lens_to_sensor, FoV calculations → calculate_field_of_view, live stock → read_shopify_products. Also warns against naive math. Provides clear when/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?

The description discloses critical behavioral traits beyond the annotations: the two-phase send-on-confirm design, fixed recipient, and the guarantee that it does not write order/customer data. This goes well beyond the bare-annotations safety profile and prevents accidental sends.

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 structured and front-loaded, with each sentence serving a distinct purpose: purpose, process, constraints, content guidance, and delivery outcome. No wasted words despite covering a multi-step tool.

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 no output schema and 10 parameters, the description covers purpose, the preview vs. send distinction, what to include, the fixed recipient, non-effects on orders/charges/data, and how the buyer is contacted. This is unusually complete for a complex 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?

All 10 parameters already have schema descriptions, so the baseline is 3. The description adds value by instructing agents to populate part numbers, sensor, quantity, and application when known, and explains the confirm flag's role in the preview/send sequence beyond its schema default, meriting a 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?

The description opens with 'Forward a buyer request-for-quote or engineering question to the Commonlands engineering team,' using the specific verb 'forward' and naming the exact resource and destination. This clearly distinguishes it from sibling tools like create_cart or get_catalog_snapshot_status, which handle commerce or catalog queries.

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 states the two-step preview/confirm workflow ('the first call returns a preview and sends nothing... call again with confirm: true to send'), provides when advice ('Include part numbers, sensor, quantity, and application when known'), and clarifies exclusions ('never creates an order, charges a card, or writes Shopify/customer data'), implicitly steering agents away from commerce 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?

Beyond the destructiveHint=true annotation, the description explains the actual destruction semantics: omitted lines are removed and [] empties the cart entirely. It also states the auth requirement (id + cart_access_token) and explicitly denies side effects ("does not place an order").

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 tight sentences with the replace-and-destroy semantics front-loaded, followed by the operational recipe and a crucial negative constraint. No sentence is 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 destructive nested-object mutation with no output schema, the description covers semantics, ordering, and the return-side caveat (no order placed). It stops short of describing what the response contains or how conflicts/errors are surfaced.

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 only 25% schema coverage, the description does real work: it explains that cart.line_items must contain every retained item, that item.id is a ProductVariant GID (the schema only says string), and that line id is optional. It omits any mention of the meta or cart.context parameters, which remain undocumented.

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

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

"Replace the complete Shopify cart after buyer confirmation" names a specific verb (replace) and resource (cart) and disambiguates from create_cart/get_cart/cancel_cart by emphasizing full replacement. The closing clause "This does not place an order" further distinguishes it from create_checkout.

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

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

It prescribes a concrete workflow (read the cart first, then send every line item to retain) and a precondition (buyer confirmation). It does not name an alternative tool for merging single items, leaving the agent to infer that no such sibling exists.

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