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 indicate readOnlyHint=true and destructiveHint=false, and the description adds context: 'Not live product truth; verify purchasable facts with read_shopify_products.' No contradiction. Describes comparison behavior and scoring model.

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?

Description is moderately concise, front-loaded with purpose, and each sentence adds value. Could be slightly shorter, but overall well-structured.

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, so description must convey return value. It says 'Use as explanatory context' and mentions 'deterministic scoring model', but doesn't specify output format or type. Adequate for usage but incomplete on 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 33% (only sensorPartNumber has a description). The description does not elaborate on lensSkus or the optional workingDistanceMm parameter. It implicitly covers the required params but fails to compensate for the low schema 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 compares Commonlands M12 and C-mount lens SKUs on the same sensor with a deterministic scoring model. The verb 'compare' and resource 'lenses' are specific, and it distinguishes from siblings like compute_fov and compute_fov_catalog.

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, then call compute_fov for precision. Also warns not to interpolate FoV from certain fields and directs to compute_fov or compute_fov_catalog for accurate values. Provides clear when-to-use and when-not-to-use guidance.

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

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

Description reveals that the tool uses either a live backend or fixture-backed scaffold data, and explicitly warns against using catalog fields for interpolation. This adds transparency beyond the annotations' read-only hint. It does not contradict 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?

Description is clear and informative but slightly verbose with the rule and multiple instructions. However, every sentence provides useful guidance. It is front-loaded with the core purpose. Slight reduction could improve conciseness, but it's still 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?

Description covers purpose, inputs, outputs hinted, data sources, correct usage, and references to sibling tools. It addresses potential confusion about catalog fields. This is contextually complete for an AI agent to use the tool correctly.

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

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

Schema covers all three parameters with clear descriptions, so description does not need to add much. The description reinforces the purpose but doesn't provide additional parameter semantics. Baseline score of 3 is appropriate.

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

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

Description clearly states it computes FoV for a specific lens-sensor pair, lists outputs (horizontal, vertical, diagonal when available), and explicitly contrasts with compute_fov_catalog for catalog-wide computation. This leaves no ambiguity about the function's scope.

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?

Description explicitly states when to call this tool (for sensor-specific FoV), contrasts with compute_fov_catalog, warns against using catalog fields for interpolation, and directs to read_shopify_products for purchasable facts. This provides clear usage guidelines.

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), the description adds that it uses a live backend, returns sanitized fields only, never raw distortion coefficients, and includes a crucial FoV rule for AI 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?

Front-loaded with purpose, then adds guidelines and behavioral notes. Each sentence serves a purpose, though slightly dense; could be slightly more concise but still 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?

Even without an output schema, the description covers what is returned (HFOV/VFOV/DFOV, coverage/provenance), the FoV rule, and backend behavior, making it complete for an AI agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context about workingDistanceMm being optional and used for scene-size estimates, and explains that output includes per-sensor HFOV/VFOV/DFOV, adding value beyond 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 it computes lens field of view for a catalog on one sensor, specifies the lens types (Commonlands M12 and C-mount), and distinguishes from siblings like compute_fov (for single pair) and compare_lenses.

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 prefer this for 'find lenses for this sensor/target FoV' requests and contrasts with compute_fov for single pairs. Also mentions the authenticated live FoV backend.

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 value beyond annotations by explaining the stateless proxy and that cart state is managed by Shopify. While annotations indicate destructiveHint=true, the description further clarifies 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?

Two concise sentences that front-load the purpose and add behavioral context without waste.

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 (nested objects, mutation, no output schema), the description covers state management but lacks details on return values, idempotency, or success behavior.

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% with only 'meta' described. The description does not add meaning for the 'cart' parameter beyond its schema structure, so baseline 3 applies.

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

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

The description clearly states the tool creates a Shopify cart for variant line items, specifying the resource and context. It distinguishes from siblings like get_cart and update_cart.

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 vs alternatives (e.g., update_cart). No prerequisites or context for usage.

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 claims the tool retrieves data (read operation), but annotations set destructiveHint=true, indicating potential destructive behavior. This is a major contradiction. The description does not explain the destructive nature as hinted by 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 concise (two sentences) and front-loaded with the core purpose. However, it omits important behavioral details (contradiction with annotations) and parameter descriptions, making it less useful than it could be.

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 presence of a contradictory destructive hint, the missing return value specification, and the undocumented 'meta' parameter, the description is incomplete for effective tool selection and invocation, especially without an output schema.

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

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

The description adds no parameter information beyond the input schema. The 'id' parameter is already described in schema. The 'meta' parameter has no description in schema nor description, leaving ambiguity. With 50% schema coverage, the description should compensate but does not.

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

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

The description clearly states the action ('Retrieve a Shopify-owned cart') and the resource ('by cart id'). It distinguishes from sibling tools like create_cart and update_cart through the verb 'retrieve'.

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 context that agents must retain the cart id or continue_url across sessions, but does not give explicit guidance on when to use this tool versus alternatives like create_cart. No when-not conditions are stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds value by detailing the specific data returned (counts, validation, provenance, readiness, warning), which is 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?

The description is a single, well-structured sentence that front-loads the core action ('Return') and lists the key output components efficiently. Every phrase is necessary and clear.

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 zero parameters, simple read-only semantics (annotated), and no output schema, the description fully explains what the tool returns. No missing context 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?

There are zero parameters, so schema coverage is 100% trivially. The description does not need to add parameter information; the baseline for 0-param tools is 4. No gaps exist.

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 specific verbs ('Return') and identifies the resource ('fixture-backed joined catalog snapshot status') with distinct elements: counts, validation status, source provenance, live connector readiness, and a product-truth warning. This clearly distinguishes it from sibling tools like 'get_catalog' or 'search_catalog'.

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 implies use for retrieving status of a fixed snapshot but does not explicitly state when to use this tool over alternatives (e.g., 'get_catalog' or 'get_product'). No when-not-to-use guidance or exclusionary language is present.

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 and destructiveHint. The description adds behavioral context by stating the data is 'fixture-backed', constraining use of certain fields for FoV, and listing the fields returned. This adds useful detail 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 well-structured, front-loaded with purpose, followed by constraints and alternatives. It is somewhat lengthy but every sentence adds value. A minor reduction for potential trimming but overall concise.

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 the return fields (mount, focal length, etc.). It provides enough context for a read-only lookup tool with one parameter, covering what is returned and constraints on usage.

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?

Input schema has one parameter sku with description. Schema description coverage is 100%, so the description adds little beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns fixture-backed public product and optical metadata for one Commonlands lens SKU, including specific fields like mount, focal length, image circle, etc. It distinguishes itself from sibling tools by explicitly mentioning that it is not sufficient for FoV calculations.

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 tells when to use the tool for lens metadata, and when not to (not enough for sensor-specific FoV). It names the alternative tools compute_fov and compute_fov_catalog for FoV calculations, and read_shopify_products for live product data.

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 and destructiveHint=false, so the safety profile is clear. The description adds that the tool is 'Fixture-backed' and lists the types of data (optical metadata, Shopify handoff fields), but doesn't disclose any behavioral traits beyond what annotations already cover. The warning about insufficient FoV fields is useful context but not behavioral.

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 relatively concise with four sentences, each serving a purpose: first sentence states the tool's function, second warns against misuse, third gives the FoV rule, fourth directs to alternatives. It could be slightly shortened by merging the warning into the rule, but it remains well-structured 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 the tool has no output schema and complex nested parameters, the description should explain the return format and the role of meta and catalog fields. It only mentions the types of fields (optical metadata, handoff) but not their structure or how to use the parameters. Sibling tools like get_lens_details and get_sensor_specs are present but not differentiated beyond the FoV warning. The description is incomplete for a full understanding.

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 2 parameters (meta and catalog) with 0% description coverage in the schema itself. The description does not explain either parameter, their structure, or purpose. It only mentions the fields in the response (optical metadata, handoff fields), but not the request parameters. The description fails to add meaning 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 identifies the tool as a 'UCP Catalog product detail alias' with optical metadata and handoff fields. It specifies the verb (get) and resource (product), and distinguishes from siblings like compute_fov by warning against using its fields for FoV computation. However, the term 'alias' is somewhat vague.

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 when NOT to use this tool (for sensor-specific FoV) and provides clear alternatives: 'call compute_fov for the lens/sensor pair' or 'compute_fov_catalog'. It also gives a rule against interpolating or estimating FoV from the fields. This is excellent usage guidance.

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

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

Adds context beyond annotations: fixture-backed, DynamoDB-sourced, gated datasheet. Warns about limitations for FoV. No contradiction with readOnlyHint and destructiveHint.

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

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

Front-loaded with purpose, but multiple explanatory sentences. Could be slightly more concise, but still 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 simple input schema, no output schema, and read-only annotations, description covers behavioral details and relationships with other tools adequately.

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?

Single parameter 'sku' with 100% schema description coverage. Tool description doesn't add new meaning beyond the schema example.

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

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

Description states specific action: return product-page handoff details for one lens, including optical specs and policy. Clearly distinguishes from siblings like compute_fov 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 advises when not to use (FoV computation) and directs to alternatives (compute_fov, read_shopify_products). Provides clear context for 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 declare readOnlyHint=true and destructiveHint=false. Description adds 'without mutating commerce state' consistent with readOnly. It also warns against misusing FoV fields. 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?

Description is moderately concise but could be shorter. It front-loads the main purpose but adds a lengthy FoV caution that could be more succinct. Not excessively long.

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

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

With no output schema and 5 parameters, description covers what the tool does and how to use it relative to siblings, but lacks parameter details and return value description. Somewhat complete but with 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?

Schema description coverage is 0%, but description does not explain parameters like sku, quantity, agentType, buyerIntent, or sensorPartNumber. The description focuses on overall behavior, missing parameter meanings.

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 'Return safe dual-channel purchase route options' and contrasts with sibling tools like compute_fov. It specifies the resource (purchase routes) and the verb (return), distinguishing it from other 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 'This explains commerce routes only; call compute_fov/compute_fov_catalog for sensor-specific FoV before recommending a lens.' Provides clear when-to-use and when-not-to-use guidance.

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

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

Adds value beyond annotations by describing the read-only live sensor table with fixture fallback and warning about FoV fields being insufficient. Annotations only state readOnlyHint and destructiveHint, so this provides behavioral context.

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

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

Packs necessary information into a few sentences, front-loading the main return types. Slightly verbose but every sentence carries useful guidance, so it earns its place.

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

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

Given one parameter and no output schema, the description is complete: it states what it returns, how it operates, and how it should be used. Covers all essential context 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% and schema already describes partNumber. The description does not add new parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns sensor dimensions, pixel pitch, and resolution for lens field of view, M12 lens, and C-mount lens matching inputs. It distinguishes from siblings like compute_fov by specifying these specs are inputs for 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?

Explicitly instructs to use specs as inputs to compute_fov or compute_fov_catalog and not to hand-calculate FoV. Provides a rule about insufficient fields, giving clear guidance on when and how to use the tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by confirming the tool does not call Shopify or expose secrets, providing additional safety context beyond the annotations.

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

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

A single, well-structured sentence that communicates the tool's purpose, scope, and constraints without any wasted words. Front-loaded with the core action.

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

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

For a zero-parameter, read-only status tool, the description covers the essential inputs and outputs implicitly. However, it does not describe the return format or structure, which would improve completeness. Minor gap.

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

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

With zero parameters and 100% schema coverage (trivially), the baseline is 4. The description does not need to add parameter information, and it does not mislead. No improvement needed.

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 specifies exactly what the tool reports (sanitized Cloudflare Shopify binding presence, approved read scopes, read-only safety flags) and what it avoids (exposing secrets or calling Shopify). This clearly distinguishes it from sibling tools that actually read Shopify data.

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 does not explicitly state when to use this tool versus alternatives like read_shopify_metaobjects or read_shopify_products. Usage is implied for checking config safety, but no when-not or alternative names are provided.

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 and destructiveHint=false. The description adds that it reports compatibility and blockers but doesn't elaborate on specific behaviors or side effects beyond what annotations provide.

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

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

One sentence description is concise and front-loaded with the action. However, jargon like 'Commonlands engineering differentiators' may be slightly unclear.

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 parameters and no output schema, the description provides adequate high-level detail on the tool's output, but an agent might benefit from more structured return information.

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 coverage is 100%. The description adds no parameter info, which is expected; baseline of 4 applies.

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

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

The description uses a specific verb 'Report' and clearly identifies the resource 'Shopify Storefront/UCP readiness', distinguishing it from sibling tools like 'get_cart' or 'search_catalog'.

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 implies the tool is used for assessing readiness but provides no explicit guidance on when to use it versus alternatives like 'get_shopify_readonly_config_status' or any exclusions.

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 and destructiveHint=false. The description adds that the tool returns not-found messages instead of performing writes, which is consistent with the read-only nature. It also notes the tool is 'fixture-backed', implying precomputed data, but does not elaborate further. No contradictions are present.

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 paragraph that front-loads the primary purpose. Each sentence adds value, but the paragraph is relatively long due to the inclusion of a detailed FoV rule. The information is well-organized, though it could be more concise by moving the FoV details to the compute_fov tool's description.

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 simplicity (lookup), the description covers the core behavior (returns not-found messages) and provides important guidance on FoV computation. However, it lacks details about output format, pagination, or error handling. The schema coverage is 0% and no output schema exists, so the description should compensate more. The FoV rule, while specific, helps avoid misuse but adds completeness.

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 a nested 'catalog' object with an 'ids' array and an optional 'meta' object, with 0% schema coverage. The description mentions identifier types (product, variant, SKU, handle, URL) but does not explicitly map them to the schema fields or explain the structure of the catalog object. The 'meta' parameter is entirely unmentioned, leaving ambiguity. The description adds some semantic value but is insufficient to compensate for the lack of schema 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 states the tool's purpose: a fixture-backed lookup for catalog products by various identifiers, returning not-found messages. It also explicitly distinguishes from sensor-specific field-of-view computation, which is a separate concern. The verb 'lookup' and resource 'UCP catalog products' are specific and aligned with the title.

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 catalog lookups) and when not (for sensor-specific FoV, for which compute_fov or compute_fov_catalog should be called). It includes a warning against interpolation and estimation, and directs the agent to call compute_fov for accurate results. This differentiation is crucial given the 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 declare readOnlyHint=true and destructiveHint=false. Description adds that the tool is not live product truth and advises to verify with read_shopify_products. Also details the ranking criteria (image-circle coverage, FOV fit, tradeoffs). No contradictions with annotations.

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

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

Description is longer but every sentence adds value: purpose, usage, limitations, and caveats. Front-loaded with 'Rank fixture catalog M12 lenses and C-mount lenses for one sensor'. Slightly verbose but not wasteful.

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 5 parameters and no output schema, the description adequately covers purpose, usage, limitations, and behavioral caveats. Does not explain return format, but the focus on ranking and shortlisting makes the output self-explanatory.

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 40% (2 of 5 parameters have descriptions). The description does not elaborate on parameters like workingDistanceMm or desiredHorizontalFovDeg beyond their presence. While the context of lens matching indirectly explains some parameters, direct parameter guidance is lacking.

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 explicitly states it ranks M12 and C-mount lenses for a sensor using image-circle coverage, FOV target fit, and optical tradeoffs. It distinguishes from sibling tools like compute_fov and compute_fov_catalog by positioning itself as a shortlist helper, not for customer-facing 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?

Clearly states when to use (shortlist helper) and when not (for customer-facing FoV, use compute_fov or compute_fov_catalog). Warns against interpolating or estimating FoV from catalog fields. Provides explicit alternative tool names.

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 reinforces the readOnlyHint and destructiveHint annotations by explicitly stating the tool performs no writes (no carts, checkout, orders, inventory mutations, or writes). It adds context about preserving FoV provenance and a behavioral constraint on FoV computation, which goes 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 dense but well-structured, front-loading the core read-only purpose and then providing the FoV rule. Every sentence adds value, though the long list of negations (no carts, checkout, etc.) could be slightly more concise.

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

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

The tool has 4 parameters and no output schema, yet the description does not explain the output structure or return values. It mentions preserving FoV provenance but does not specify what the handoff seam contains. The description is incomplete for an agent to understand what the tool produces.

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 compensate, but it does not explain any of the four parameters (sku, quantity, sensorPartNumber, selectedVariantId). It only mentions 'selected lens' implicitly. Without parameter descriptions, the agent cannot know the meaning or constraints of these inputs.

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 builds a read-only purchase handoff seam for a selected lens without creating carts, checkout, orders, or inventory mutations. It distinguishes from write tools like create_cart. The verb 'prepare' and resource 'purchase handoff' are specific and differentiated from siblings.

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 says when to use this tool (for a read-only handoff) and when not to (do not interpolate sensor FoV; use compute_fov instead). It names alternative tools (compute_fov, compute_fov_catalog) and provides a clear rule for FoV handling.

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 and destructiveHint=false. The description adds further context by specifying that it returns 'redacted field previews only' and operates 'through approved read-only scopes', which clarifies the nature of the output and access restrictions.

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 concisely written in two sentences, with the primary action in the first sentence and a clarifying note in the second. It contains no extraneous 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?

Given the tool's simplicity (three parameters, read-only, no output schema), the description is sufficiently complete. It explains what the tool reads, how to filter, and important notes about redacted data and lack of write capability.

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 covers 67% of parameters with descriptions (type and handle). The description reinforces that filtering is by type and handle, but does not add details about the limit parameter, which only has constraints in the schema. Some additional explanation of limit's role would enhance understanding.

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 specifies the resource (live Shopify Admin metaobjects), the action (read), and the filtering options (by type, optionally by handle). It also distinguishes itself from sibling tools like read_shopify_products by naming a different resource.

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 implies that this tool is for safe, read-only access to metaobjects, stating it uses 'approved read-only scopes' and 'never writes'. However, it does not explicitly compare to sibling tools or provide when-not-to-use scenarios, leaving some ambiguity for an agent.

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 and destructiveHint=false. The description adds value by enumerating specific mutations it avoids (carts, checkouts, orders, etc.), providing richer behavioral context beyond the annotations.

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

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

Two sentences with no redundancy. The first sentence front-loads the primary purpose and output fields; the second adds critical restrictions. Every sentence earns its place.

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

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

Despite lacking an output schema, the description covers the return fields (IDs, SKUs, prices, etc.) and contrasts live vs. scaffold data. It does not mention pagination or list response format, but overall it is fairly complete for a read-only tool.

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

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

Schema description coverage is moderate (60%), but the description does not explain any input parameters. It mentions return fields but offers no guidance on how to use parameters like 'limit' or 'includeMetafields', leaving the agent to rely solely on 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 is for live product truth, listing specific fields (IDs, SKUs, prices, etc.) and explicitly distinguishes it from fixture catalog tools. It uses a specific verb and resource, differentiating from siblings like 'get_product' or 'read_shopify_metaobjects'.

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 clear context for when to use the tool (live product truth) and explicitly lists what it does not do (carts, orders, writes), helping avoid misuse. However, it does not directly compare against specific sibling tools or give when-not scenarios.

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

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

Annotations declare readOnlyHint=true, but the description adds valuable context: it warns that catalog fields like 'EFL, image circle, max FoV/FOV@image-circle, and distortion display fields are insufficient to compute field of view on a specific sensor', which is a behavioral constraint beyond the read-only nature. 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?

The description is a single, well-structured paragraph that front-loads the main purpose, then gives usage advice and a critical warning. Every sentence adds value with no fluff. Could be slightly more terse, but overall 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 8 parameters (low schema coverage), no output schema, and no nested objects, the description explains the tool's role in the workflow and gives an important FoV rule, but it does not specify the output format or describe several key parameters. It is adequate but not thorough.

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 13% (only sensorPartNumber has a description). The description does not compensate: it mentions 'application note' and 'required lens field of view' which loosely relate to application and desiredHorizontalFovDeg, but it does not explain parameters like mount, maxResults, requireInStock, preferLowDistortion, or workingDistanceMm. Most parameters remain unclear from the description alone.

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 'Rank fixture catalog M12 lenses and C-mount lenses for an application note', which is a specific verb+resource. It distinguishes from siblings by explicitly directing to call compute_fov or compute_fov_catalog for final sensor FoV computation.

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

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

The description provides explicit when-to-use guidance: 'Use as an application shortlist helper, then call compute_fov_catalog or compute_fov for final per-sensor HFOV/VFOV/DFOV.' It also warns against using catalog fields for FoV estimation, effectively telling when not to use this tool or its output for FoV calculations.

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 and destructiveHint=false. The description adds context: it is 'fixture-backed', 'no live Shopify calls or cart behavior', and warns against estimating FoV from catalog fields. This goes 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 front-loaded with the purpose and nature. While it is somewhat verbose, especially the FoV rule, every sentence adds value. It could be slightly more concise, but it is well-structured.

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

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

The tool has nested objects, no output schema, and incomplete parameter descriptions. The description covers purpose, usage, and behavioral notes, but it does not hint at what the search returns or explain 'fixture-backed'. This leaves some gaps for an agent to fully understand invocation behavior.

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

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

Schema description coverage is 50% (only 'meta' has a description). The description does not explain the 'query' or 'limit' parameters. While parameter names are somewhat self-explanatory, the description fails to add meaning beyond what the schema provides, especially since the schema lacks full 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 explicitly states 'Fixture-backed UCP Catalog search alias for Shopify-native product discovery', providing a specific verb (search) and resource (UCP catalog). It also distinguishes from sibling tools like compute_fov_catalog and compute_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 clearly states when to use this tool ('only for broad discovery') and when not to use it ('when a sensor or target FoV is involved, call compute_fov_catalog or compute_fov instead'). It also provides an explicit alternative and a rule about FoV 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?

The description adds critical behavioral context: catalog is a 'snapshot' (not live), warns against using catalog fields for FoV computation, and emphasizes calling compute_fov for accurate results. Annotations already indicate read-only non-destructive, so no contradiction.

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, front-loaded with purpose, followed by usage guidelines and a specific rule. Every sentence adds value; no 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?

Given the simple tool (2 params, no output schema), the description covers search scope, usage boundaries, alternatives, and a critical behavioral rule, making it 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 50%; the description adds semantic value for the query parameter (lists searchable fields) but does not mention the limit parameter, which has only schema constraints. Compensates partially but not fully.

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

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

The description clearly states the tool searches a lens catalog by specific fields (SKU, title, mount, etc.) and distinguishes it from sibling tools like compute_fov 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 says 'Use this only for broad discovery' and directs to compute_fov/compute_fov_catalog for FoV-related queries, and to read_shopify_products for live product data.

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 reveals that updates can be destructive (e.g., removing lines via quantity 0 or remove_line_ids) and that semantics differ by endpoint. This adds context beyond the annotations (destructiveHint: true), though it does not detail all side effects or required permissions.

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 relatively concise for the complexity, covering multiple endpoint behaviors and field mappings in a single paragraph. It front-loads the main action, but could be better structured with bullet points or separate paragraphs 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's complexity (nested objects, 3 parameters, no output schema), the description provides essential information about how to structure input fields for different operations. However, it does not describe the return value or error conditions, leaving some 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?

With 0% schema description coverage, the description compensates by explaining the purpose of line_items, update_items, and remove_line_ids, including special behavior like quantity 0 removing a line. However, it omits detail on the 'context' and 'signals' parameters, relying on their types.

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 'Update a Shopify-owned cart' with specific verbs and resource. It distinguishes between different endpoint behaviors (UCP vs standard) and describes how input fields map to Shopify operations, setting it apart from sibling tools like create_cart and get_cart.

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 the mapping of line_items, update_items, and remove_line_ids to corresponding Shopify operations, guiding the agent on how to use each field. It also clarifies endpoint-specific behaviors. However, it does not explicitly state when not to use this tool or compare with alternatives like create_cart.

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