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?

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses that the MCP is a stateless proxy, Shopify owns the cart state, and the cart_access_token is required for subsequent operations. This adds significant behavioral context not available in the structured 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, each earning its place: purpose, stateless proxy context, and token retention guidance. Front-loaded and free of 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?

Given the nested schema and no output schema, the description addresses the key operational need—returning and retaining the cart_access_token—and explains the stateless behavior. However, it does not describe the full response shape or error conditions, 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?

The description calls line items 'selected variant line items,' which hints that item.id is a variant ID, but does not explain the cart object structure or quantity semantics. Schema coverage is only 50% (meta has a description, cart does not), so the description partially compensates but leaves room for clarification.

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 and resource: 'Create a Shopify-owned cart for selected variant line items through the configured Shopify Cart/Storefront MCP endpoint.' It clearly distinguishes this from sibling tools like get_cart and update_cart by focusing on creation and referencing the token needed by those 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?

The description explicitly explains the sequence: create the cart, retain the returned cart_access_token, and notes that get_cart and update_cart will refuse to work without it. This provides clear when-to-use guidance and references alternatives, mirroring the high-quality example in the calibration.

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, and non-destructive behavior. The description adds valuable context beyond that: the ownership model, token requirement, persistence source, and the need to retain credentials across sessions. This enriches the agent's understanding of the tool's operational requirements.

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-loaded with the core purpose, and every sentence contributes essential information. No filler 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?

The description provides a clear and complete picture for a simple read operation, covering purpose, ownership, persistence, and agent responsibilities. The lack of an output schema is not addressed, and the 'meta' parameter is ignored, creating a minor completeness gap, but overall it is well-scoped.

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 covers 67% of parameters with descriptions. The description reinforces the meaning of cart_access_token by explaining it is returned by create_cart and serves as an owner credential. However, the 'meta' parameter remains undocumented in both schema and description, so the description does not fully compensate for that 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 clearly states the tool retrieves a Shopify-owned cart by ID, using a specific verb and resource. It distinguishes itself from siblings like update_cart and get_product by emphasizing the owner-bound nature and reliance on a cart_access_token.

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 states the owner-bound requirement and the need for the cart_access_token from create_cart, giving clear context on when to use this tool. It also advises agents to retain credentials across sessions, but does not explicitly mention alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint, 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 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 annotations (destructiveHint=true, readOnlyHint=false), the description adds significant behavioral context: owner binding, full-state PUT semantics for UCP, additive vs. quantity-update vs. removal operations for the standard endpoint, and the special case where quantity 0 removes a line. This aligns with the annotations and gives the agent a clear mental model of side effects.

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 and front-loaded: the first sentence states the core purpose and endpoint, the second covers owner restriction, and the third details endpoint-dependent semantics. Every sentence adds value without repetition or 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 complex mutation tool with nested parameters and no output schema, the description covers the essential operational details: owner token requirement, endpoint variations, field mapping, and removal semantics. It does not mention return values or error behavior, which would be useful but is not strictly required given the tool's scope and the presence of annotations.

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

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

Schema description coverage is low (25%), but the description compensates by explaining the roles of line_items, update_items, and remove_line_ids, and their mapping to Shopify operations. It also highlights the quantity-0 removal behavior, which is not fully obvious from the schema alone. However, some nested session/context fields remain undocumented in both places.

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

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

The description clearly identifies the action (update) and resource (Shopify cart), and distinguishes it from sibling tools like create_cart and get_cart by explicitly mentioning owner-bound access and the required cart_access_token. It also specifies the endpoint type and mapping semantics, leaving no ambiguity about what the tool does.

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 important usage guidance: it states the owner-only constraint and prerequisite token from create_cart, and explains the behavioral differences between UCP and standard Storefront endpoints. However, it does not explicitly contrast with alternatives such as get_cart or when to prefer this over recreate/delete workflows, so a small gap remains.

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