AirShelf Catalog

Compare products

compare_products

Read-only

Compare 2-10 catalog products side-by-side on their datasheet specs. Slugs come from search_catalog and are case-insensitive and dash-tolerant ("e-STUDIO 331AC", "toshiba-e-studio-331ac" and "e-studio331ac" all resolve to the same product).

Returns one item per product with canonical_name and spec_absence_note (spec fields absent from that product's golden record, AirShelf's verified product record). Branch on each item's commercial_data.actionable before using price or stock; stale observations are withheld from action fields. An item's commercial_disclosure is present when its maker is a seller AirShelf serves through its own agent endpoints. A slug that does not resolve comes back as not_found with a did_you_mean suggestion. The provenance option adds the source page and source type already stored with each fact.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "slugs": "<slugs>"
    },
    "name": "compare_products"
  }
}

Input Schema

Name	Required	Description	Default
`slugs`	Yes	Catalog slugs to compare
`provenance`	No	Include the stored source page and source type for each fact

Output Schema

Name	Required	Description	Default
`count`	No
`items`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedAug 5, 2026

changedInput schema / properties / provenance / description

Previous value: -"Include the source page for each fact plus a signed-attestation URL"New value: +"Include the stored source page and source type for each fact"

addedInput schema / properties / slugs / items / minLength
```
Added value: +1
```

Changed1 schema field changedAug 4, 2026

changedInput schema / properties / provenance / description

Previous value: -"Include per-claim source provenance + signed-attestation URL + jwks_url"New value: +"Include the source page for each fact plus a signed-attestation URL"

Changed1 schema field changedJul 6, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "count": {
+      "type": "number"
+    },
+    "items": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "canonical_name": {
+            "type": "string"
+          },
+          "manufacturer": {
+            "type": "string"
+          },
+          "modelName": {
+            "type": "string"
+          },
+          "price": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "slug": {
+            "type": "string"
+          },
+          "spec_absence_note": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "required": [
+          "slug"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "items"
+  ],
+  "type": "object"
+}

Changed1 schema field changedJun 23, 2026

addedInput schema / properties / provenance

Added value: +{
+  "description": "Include per-claim source provenance + signed-attestation URL + jwks_url",
+  "type": "boolean"
+}

First observedJun 17, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Far exceeds the annotations: it discloses the per-product return shape (canonical_name, spec_absence_note), the actionable/stale-observation gating on commercial_data, what commercial_disclosure signals about the seller relationship, and the not_found/did_you_mean failure mode. Nothing here contradicts readOnlyHint=true, destructiveHint=false — it is a pure read.

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

Conciseness4/5

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

Front-loaded with the core comparison behavior and cardinality, then progressively de-risks with slug formatting and response branching. It is dense but each sentence carries information; the final provenance sentence is the one piece that largely repeats the schema and could be trimmed.

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

Completeness5/5

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

For a two-parameter, read-only comparison tool with an output schema, this covers everything an agent needs: valid inputs, failure handling, and how to interpret the commercially sensitive fields before acting on them. The spec_absence_note and golden-record framing also pre-empt misreading absent specs as zeros.

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

Parameters4/5

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 earns above that by explaining slug normalization and tolerance with concrete examples that the schema's 'Catalog slugs to compare' does not convey. The provenance option is only restated from the schema, so it adds no new meaning there.

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

Purpose5/5

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

States a specific verb and resource — compare 2-10 catalog products side-by-side on datasheet specs — with an explicit cardinality bound. It is clearly distinguishable from siblings like get_product and search_catalog, which fetch rather than compare across multiple items.

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

Usage Guidelines4/5

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

It tells the agent where slugs come from (search_catalog) and how to format them (case-insensitive, dash-tolerant, with three worked variants), which is the practical prerequisite for calling the tool. It does not explicitly say when to prefer get_product or explain_product instead when only one product is of interest, so it falls short of full when/when-not guidance.

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

All AirShelf Catalog tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?