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 readOnlyHint and idempotentHint are true, and destructiveHint false. The description adds valuable context: it returns live backend data not derivable by the model, distortion status, and notes fallback behavior when only focal length is supplied. 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 well-structured with purpose first, then usage, then return values, then constraints. While slightly verbose in enumerating return details, it front-loads the key purpose and is efficient for the complexity.

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 9 parameters and an output schema present, the description covers all necessary context: input aliases, output types (HFOV, VFOV, etc.), fallback behavior, and when to use. It is complete for the tool's complexity.

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 summarizes accepted parameter groups (lens_sku/lensSku, focal_length_mm/focalLengthMm, etc.) and explains the dual aliases, adding clarity beyond the schema. It helps the agent understand input choices.

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, etc.). It uses a specific verb-resource structure and distinguishes from sibling tools like compare_lenses or get_lens_distortion_profile by focusing on 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 explicitly lists when to use this tool (e.g., for FOV, HFOV, VFOV, DFOV requests) and when not to use it (avoid naive rectilinear fallback when Commonlands route is available). It provides clear context and 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?

Description adds context beyond annotations: states it uses a deterministic scoring model, not live product truth, and advises verifying with read_shopify_products. Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the description complements well without 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 concise with three clear sentences, each adding value: purpose, usage guidance, and limitations. 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?

Description covers purpose, usage, and limitations but lacks information about the output format or return value. Since there is no output schema, the description should indicate what kind of comparison data is returned (e.g., scores, side-by-side specs).

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

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

Schema description coverage is only 33% (only sensorPartNumber described). The description does not elaborate on lensSkus or workingDistanceMm beyond their existence and constraints. Given low coverage, the description should provide more parameter details 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?

Description clearly states it compares M12 and C-mount lenses on the same sensor with a deterministic scoring model. It uses specific verbs (compare) and resource (Commonlands lenses) and distinguishes from sibling tools like calculate_field_of_view and match_lens_to_sensor.

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 (as explanatory context) and when not to (never estimate FoV), and provides alternative tools (calculate_field_of_view, read_shopify_products). Covers both usage and 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 provide no behavioral hints, but the description adds significant context by stating the MCP is a stateless proxy and cart state is stored/mutated by Shopify. This clarifies side effects and remote state management beyond what annotations convey.

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

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

Two sentences, first sentence clearly states the action and resource, second adds essential architectural context. No unnecessary words, front-loaded with key 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 nested input schema, no output schema, and sibling cart tools, the description covers core purpose and statelessness adequately but lacks details on return values, required parameter semantics, and deeper behavioral traits. It is minimally viable but leaves 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 coverage is 50% (meta parameter described, cart not). The description adds context by mentioning 'variant line items', aligning with line_items property, but does not elaborate on nested objects like context or signals, nor does it compensate fully for missing 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 creates a Shopify-owned cart for variant line items, using the verb 'Create' and specifying the resource as a cart. It distinguishes from sibling tools like get_cart and update_cart by focusing on creation.

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 usage for creating a new cart but does not explicitly state when to use this tool over siblings like get_cart or update_cart, nor does it provide exclusions or prerequisites.

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, and destructiveHint=false. The description adds useful context about cart persistence being managed by Shopify and the need for agents to retain the identifier across sessions, 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 concise with two front-loaded sentences: first states the purpose, second provides usage guidance. 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 the tool is a simple read operation with one required parameter and no output schema, the description covers the essential behavioral constraint (session persistence). It could mention the return value type but is sufficiently complete for its complexity.

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 add meaning beyond the input schema. The required 'id' parameter is mentioned but with no additional details. The optional 'meta' parameter has no description and is not explained. Schema coverage is 50%, but the description fails to compensate.

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 verb 'Retrieve' and resource 'Shopify cart by cart id'. It distinguishes itself from sibling tools like 'create_cart' and 'update_cart' which have different purposes.

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 cart persistence and the need to retain cart id or continue_url across sessions, indicating a key usage constraint. However, it does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context beyond annotations, such as 'fixture-backed' and 'non-authoritative product-truth warning,' which inform the agent about data source and reliability. 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 a single sentence that packs in multiple return items. It is concise but slightly dense; could be broken into a list for clarity. However, it is not verbose and serves its purpose efficiently.

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 lists expected return elements (counts, validation status, provenance, readiness, warning). It provides sufficient context for an agent to understand the tool's output, though terms like 'fixture-backed' might benefit from brief explanation.

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, and schema coverage is 100%. The description does not need to add parameter details. Baseline score of 4 is appropriate as it adds no redundancy.

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 joined catalog counts, validation status, source provenance, live connector readiness, and non-authoritative product-truth warning.' It specifies the exact resources and outputs, distinguishing it from sibling tools like get_cart or get_product which serve different purposes.

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 provide any guidance on when to use this tool versus alternatives, nor does it mention prerequisites or context. It simply states what it returns, leaving the agent to infer usage without explicit direction.

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, so safety is covered. The description adds value by detailing behavioral traits: returns data the model cannot derive, live backend FoV when configured, distortion model/status, image-circle coverage, live stock through Shopify read tools, and MTF/CRA/BFL fields if present. It also warns against invalid inferences. This context is 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 front-loaded with the main purpose in the first sentence. Subsequent sentences provide usage guidelines and behavioral details. While it could be slightly shortened, every sentence contributes necessary information, and it avoids 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 tool has 3 optional parameters, 100% schema coverage, and annotations present, but no output schema. The description explains what the tool returns (distortion model/status, FoV, coverage, stock, optical fields) and constraints (when to use, what not to do). It is fairly complete, though output format details are missing. Given the query nature, this is adequate.

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 the three parameters (sku, lensSku, lens_sku), each with clear descriptions and examples. The description adds little extra semantic meaning beyond the schema, as it only mentions 'one lens SKU' in the first sentence. 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 verb 'Return' and the resource 'distortion model/status for one lens SKU'. It specifies what data is included (source-display-only or backend-calculated) and is distinct from sibling tools like calculate_field_of_view and get_sensor_specs, which address different aspects.

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 scenarios to use this tool (e.g., FOV, HFOV, VFOV, DFOV, field of view, sensor part-number requests) and gives strong negative guidance: 'Do not use naive rectilinear fallback, focal-length-only math, interpolation...' and 'Do not invent polynomial coefficients...' This provides clear when-to and when-not-to instructions.

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, indicating safe read operations. The description adds that the tool is 'Fixture-backed' and specifies the types of metadata included, which provides some behavioral context but does not significantly expand beyond what annotations convey.

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

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

The description is three sentences long, efficient, and front-loaded with the tool's purpose. However, the use of technical jargon ('Fixture-backed', 'Commonlands optical metadata') might obscure meaning for some agents, slightly reducing 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?

With no output schema and no parameter documentation, the description leaves significant gaps. While it mentions return fields (optical metadata, Shopify handoff), it does not enumerate them or describe structure. For a retrieval tool, this is insufficient for confident use.

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 the description does not explain any parameters (meta, catalog). The agent has no guidance on what values to provide for these parameters, making it difficult to use correctly.

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 'UCP Catalog product detail' with specific metadata types. It distinguishes itself from sibling tools like 'calculate_field_of_view' by explicitly stating that it does not provide sensor-specific FoV, making its scope unambiguous.

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

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

The description provides explicit guidance on when not to use this tool: 'never estimate sensor-specific FoV from catalog fields; use calculate_field_of_view or match_lens_to_sensor'. This directly addresses a common misuse scenario and offers clear alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that the data is 'fixture-backed' and includes 'gated datasheet policy,' indicating access control. It also clarifies the source (DynamoDB) and explicitly warns against improper use (FoV rule). 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: first states purpose and contents, second clarifies limitations, third provides rules and alternatives. No unnecessary words, front-loaded with essential 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 no output schema, the description sufficiently explains what the tool returns (product-page handoff details, optical specs, datasheet policy). It also covers the single parameter and addresses common confusion with sibling tools. The context signals (one param, high schema coverage) are fully leveraged.

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 a clear description of 'sku.' The description reinforces the parameter by using it in context ('for one lens') and giving an example ('CIL250'). While the schema already documents the parameter, the description adds meaningful integration, earning a 4 rather than 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?

The description clearly states the tool returns product-page handoff details for one lens, specifying data sources (DynamoDB-sourced optical specs) and constraints (gated datasheet policy). It distinguishes itself from siblings by naming alternatives and clarifying that it is not for sensor-specific FoV or live product 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?

Explicitly states when to use (for product-page handoff details) and when not to use (not a substitute for sensor-specific FoV). Provides direct alternatives: calculate_field_of_view, match_lens_to_sensor, and read_shopify_products for live 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?

Adds value beyond annotations by explicitly stating 'safe', 'without mutating commerce state', and 'dual-channel' behavior, consistent with readOnlyHint and idempotentHint, though annotations already cover safety profile.

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

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

Description is short and front-loaded with core purpose, but includes necessary usage guidance; however, could be slightly more concise by omitting redundant phrasing.

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 5 parameters, 0% schema coverage, and no output schema, the description leaves significant gaps: no explanation of parameters, no description of return values, and only vague output ('purchase route options').

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 0% and description provides no explanation or context for any of the 5 parameters (including required 'sku'), failing 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 explicitly states it returns 'safe dual-channel purchase route options' for AI agents and robotics engineers across specific channels, and clearly distinguishes from sibling tools by referencing calculate_field_of_view and match_lens_to_sensor 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?

Provides explicit when-to-use ('explains commerce routes only') and when-not-to-use ('call calculate_field_of_view/match_lens_to_sensor for sensor-specific FoV') along with a clear FoV rule, effectively guiding agent 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?

Adds detail beyond annotations by mentioning the read-only live sensor table with fixture fallback, confirming non-destructive behavior and idempotency, with 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 four sentences, front-loaded with the primary purpose, and each sentence adds value; slightly verbose but efficient overall.

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 simple read-only tool with one parameter and no output schema, the description adequately covers purpose, usage, behavior, and expected return values, leaving no critical 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 has 100% description coverage with example; the description does not add further parameter syntax or format details 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 specific lens types (M12 and C-mount), differentiating it from sibling tools by specifying its output as inputs for calculate_field_of_view or match_lens_to_sensor.

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 the specs as inputs for calculate_field_of_view or match_lens_to_sensor, and warns against hand-calculating FoV, providing clear context 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: the tool returns sanitized information, does not expose secrets, and does not call Shopify, which goes 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?

The description is a single sentence that efficiently conveys the tool's purpose and constraints without any wasted words. It is front-loaded and 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?

Despite having no output schema, the description lists the specific items reported (Cloudflare Shopify binding presence, approved read scopes, read-only safety flags), providing adequate context for a read-only configuration status tool. The description could be slightly more detailed about output format, but it is largely sufficient.

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

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

The tool has zero parameters, so schema coverage is 100% by default. The description does not need to add parameter information, and it does not. A baseline of 4 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 it reports four specific items (sanitized Cloudflare Shopify binding presence, approved read scopes, read-only safety flags) and explicitly notes what it does not do (exposing secrets or calling Shopify). It uses a specific verb 'Report' and distinguishes itself from sibling tools by emphasizing no external API calls.

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 when to use the tool (to get configuration status without calling Shopify or exposing secrets) but lacks explicit when-not-to-use guidance or direct references to alternative sibling tools. It provides context but no exclusions or alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds the specific content of the report (compatibility, blockers, differentiators) but does not disclose any behavioral traits 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?

The description is a single sentence, which is concise. However, it is dense and could be split into clearer points. Front-loading is adequate.

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

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

With no output schema, the description must explain what the tool returns. It lists three categories (compatibility, blockers, differentiators) but does not specify the format or granularity. For a tool with no parameters, it is moderately complete but leaves room for ambiguity about the output's structure.

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, and schema coverage is 100%. The description does not need to add parameter information. Baseline of 4 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 reports on Shopify Storefront MCP and UCP Catalog compatibility, launch blockers, and engineering differentiators. The verb 'Report' is specific, and the resource is well-defined. However, jargon like 'Commonlands engineering differentiators' is not explained, slightly reducing clarity.

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 siblings like 'get_shopify_readonly_config_status'. The description does not mention context, 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 indicate read-only, idempotent, non-destructive behavior. The description adds context about being fixture-backed and returning not-found messages, which supplements 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 relatively concise with two main sentences, but the FoV rule is stated twice, which is repetitive. Still front-loaded with the core purpose.

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 is provided, so the description should describe the return value more completely. It mentions not-found messages but not the success case or behavior with multiple IDs. Lacks full behavioral context for a lookup 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 0%, so the description must compensate. It explains the 'ids' array can contain product, variant, SKU, handle, or URL identifiers, but doesn't cover the 'meta' parameter or additional properties. Partial compensation leaves gaps.

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 performs lookups for product, variant, SKU, handle, or URL identifiers, and distinguishes it from write operations and other tools 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 advises when to use this tool and when to use alternatives (calculate_field_of_view, match_lens_to_sensor), including a specific rule about not estimating sensor-specific FoV.

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 idempotentHint=true, so the agent knows it is safe. The description adds value by detailing specific returned data (live FoV, distortion, stock, MTF/CRA/BFL) that the model cannot derive, enhancing behavioral transparency.

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 verbose, repeating use cases (e.g., mentioning AR0234, IMX290 multiple times). It front-loads the purpose but could be more concise without losing 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?

For a tool without output schema, the description explains what it returns (live FoV, distortion, stock, etc.). It covers most input scenarios but could be more explicit about parameter relationships and result ranking.

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 40%, meaning many parameters lack descriptions in the schema. The tool description mentions sensor, FOV, working distance, and mount but does not map them to parameters or explain their formats/usage beyond the schema, failing to compensate for the 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 the tool finds and ranks Commonlands lenses for a sensor, FOV, working distance, mount, or 'lens for' request. It lists specific use cases (AR0234, IMX290, etc.) and explicitly distinguishes from siblings by warning against naive rectilinear fallback.

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, listing FOV types, sensor part numbers, and workflows. It also tells what not to do (avoid focal-length-only math) and suggests follow-up with read_shopify_products.

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 explicitly states read-only nature and no mutations, matching annotations. It adds context about preserving FoV provenance and a specific FoV rule, going 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?

Three concise sentences, each adding value: purpose and constraints, preservation of FoV context, and a critical rule. 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?

While the description covers purpose and a behavioral rule, it lacks explanation of return values (no output schema) and parameter semantics, making it incomplete for an agent to fully understand 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 0%, and the description does not explain any of the 4 parameters (sku, quantity, sensorPartNumber, selectedVariantId), leaving the agent to infer usage from the schema 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 builds a read-only Shopify purchase handoff seam for a selected lens, distinguishing it from siblings like create_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?

The description indicates the tool is read-only and not for creating carts/orders, providing implicit guidance. It also references related tools for FoV computation, but lacks explicit when-not-to-use alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. Description adds specific behavioral details: returns only 'Public data', 'no exact inventory counts', and metafields limited to 'custom.* display 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 concise with about 4 sentences covering purpose, scope, limitations. No redundant information, though could be slightly more 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 the tool is read-only with good annotations and no output schema, the description provides enough context about what is returned (IDs, SKUs, prices) and what is omitted (exact inventory). Could be improved by detailing return structure for complex fields, but adequate.

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 high (80%) with most parameters having descriptions. The description does not add parameter-level information beyond the schema, but the baseline is 3 given the 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 'Use this for live purchasable product truth' and lists specific data (IDs, SKUs, prices). It distinguishes from sibling 'Fixture catalog tools' which are scaffold data. Verb 'read' and resource 'Shopify products' are unambiguous.

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

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

Explicitly states when to use (live product data) and when not to (fixture catalog tools). Also lists what it does not do ('does not create carts, checkouts, orders...') providing clear usage boundaries.

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 non-destructive. The description adds value by warning about the FoV estimation rule and advising follow-up tools. 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 a single paragraph but contains redundant phrases and could be more concise. It front-loads the main action but includes unnecessary repetition of the lens types.

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 8 parameters (1 required) and no output schema, the description fails to clarify what inputs are necessary and what the output ranking looks like. The FoV rule is helpful, but overall missing parameter and output 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 only 13%, and the description only vaguely references 'application' and 'required lens field of view'. Critical parameters like mount, maxResults, requireInStock, workingDistanceMm, preferLowDistortion, and desiredHorizontalFovDeg are not explained.

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 ranks Commonlands M12 and C-mount lenses for specific applications like embedded robotics or machine vision, and distinguishes it from siblings like match_lens_to_sensor and calculate_field_of_view by positioning it as an initial shortlist helper.

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 (as an application shortlist helper) and when to use alternatives (for final per-sensor FoV, use match_lens_to_sensor or calculate_field_of_view). Also includes a specific rule against 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context: it's fixture-backed (no live calls) and no cart behavior, enhancing transparency 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 concise with three sentences, front-loading purpose and including a clear rule. Efficient, though the FoV rule could be slightly more integrated.

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?

Adequately explains purpose and usage context but lacks details on return values or pagination behavior. With no output schema, the description should mention what the response contains. Parameter semantics gap further reduces 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?

Schema description coverage is low (50%) with only 'meta' having a description. The description does not mention any parameters, failing to add meaning beyond the schema. It should explain the 'catalog' parameter and its 'query' and 'limit' 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 performs a search in the UCP catalog for broad product discovery, distinguishing it from sibling tools like match_lens_to_sensor and calculate_field_of_view. It uses a specific verb ('search') and resource ('UCP 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 states when to use ('broad discovery') and when not to use (when sensor or FoV involved), naming alternative tools. The FoV rule provides clear guidance to avoid misuse.

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 crucial behavioral context: returns live backend FoV, distortion model/status, image-circle coverage, etc. Also clarifies it discovers candidates from catalog/live data but does not replace specific tools. 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 relatively long but well-structured: starts with core functionality, then exclusions, then return types, then caveats. Every sentence adds value, though some repetition could be trimmed. Overall, it's informative without being excessive.

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 only 2 parameters, no output schema, and moderate schema coverage, the description is highly complete. It explains what data it returns, when to use alternative tools, and what not to do. Addresses potential misuse comprehensively.

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 2 parameters with 50% description coverage. The description adds meaning beyond the schema by listing exact searchable fields (SKU, mount, lens type, etc.) and explicitly noting that sensor part numbers are not searchable. This provides rich context for the `query` parameter.

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 SKU, mount, lens type, etc., and explicitly distinguishes from sibling `match_lens_to_sensor` for sensor part numbers. It also lists specific searchable terms like FOV, HFOV, VFOV, providing a precise purpose.

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?

Provides explicit when-to-use (e.g., 'Use this tool for FOV, HFOV, VFOV...') and when-not-to-use (e.g., 'For sensor part numbers... use match_lens_to_sensor instead'). Also warns against naive math and lists what it does not replace (calculate_field_of_view, read_shopify_products). Excellent 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 are minimal (readOnlyHint=false, destructiveHint=false). The description adds critical context: only sends an inquiry, no side effects like order creation or data writing, and a fixed recipient. This compensates well for the lack of annotation detail.

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

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

Four sentences, front-loaded with purpose. Every sentence is informative with no redundancy. Efficient 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?

Despite no output schema, the tool is simple. The description covers the entire workflow: sending an inquiry, what inputs to provide, and the outcome (email reply). No gaps for the 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% with descriptions for all 9 parameters. The description adds value by explicitly encouraging inclusion of part numbers, sensor, quantity, and application for a better quote, which is not in the schema.

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

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

The description clearly states the tool forwards an RFQ or question to the Commonlands team. It distinguishes from siblings by explicitly stating it does not create orders, charge cards, or write Shopify data. The verb and resource 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?

The description advises when to use (after buyer provides question and email) and what not to do (no order/card/data). It implies this is for inquiries only, differentiating from purchasing tools. Could explicitly name alternative tools for ordering.

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?

Discloses destructive behavior (annotations confirm destructiveHint=true) and adds endpoint-specific semantics (PUT vs. incremental) and special behavior (quantity 0 removes line). 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?

Three concise sentences: purpose, endpoint variation, field mapping. No fluff, each 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?

Describes primary behavior but omits return value, error handling, prerequisites (cart existence), and the 'meta' parameter. Adequate but with clear gaps for a complex nested input.

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?

Despite 0% schema description coverage, the tool description explains how each parameter maps to actual Shopify actions (add, update, remove) and the special case of quantity 0, adding significant meaning beyond the schema's property 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 it updates a Shopify cart and explains the mapping of fields for adding, updating, and removing items. It distinguishes from sibling tools like create_cart by implying cart already 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?

Provides usage context for different field groups (line_items for add, update_items for quantity change, remove_line_ids for removal) and endpoint variations (UCP vs Storefront). Lacks explicit 'when not to use' but context is clear.

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