Twelfth

Search catalogue

search_catalogue

Read-onlyIdempotent

Search every product in the workspace's readable catalogue by text, supplier or category, optionally only those with an open recommendation. Use it whenever a product, brand, barcode or supplier is named and you need to know whether and where it is stocked. Pass up to 100 exact identifiers in ids (SKU, PLU, supplier or manufacturer SKU) to resolve a list in one call; each comes back matched or in not_found. Overly broad identifier results fail explicitly; use fewer or more specific ids. For figures on the results use twelfth_list_products; to resolve a supplier's exact name first use find_supplier.

Input Schema

Name	Required	Description
`ids`	No	Up to 100 exact identifiers (barcode/SKU, source product id/PLU, supplier SKU, manufacturer SKU or alternate barcode), matched case-insensitively; case-variant duplicates resolve once. Use on its own, without query, supplier_id, supplier_name, category, only_recommended or limit. Overly broad results fail explicitly; use fewer or more specific ids.
`limit`	No	Maximum rows to return (1 to 100), taken after order_by.
`query`	No	Free text: brand, product words, SKU/barcode, source product id/PLU, supplier code or category. Every word must appear somewhere in the row.
`category`	No	Category name to filter by.
`order_by`	No	Rank every match by a measure before the limit: slowest_selling or fastest_selling (units over 4 weeks), most_stock_at_cost, most_cover (days of cover). Omit for recommended first, then name, which ranks nothing.
`supplier_id`	No	A supplier's id as find_supplier returned it: that supplier's products, without pre-owned trade-ins. Prefer it to supplier_name once the supplier is resolved.
`in_stock_only`	No	True = only lines with stock on hand (available stock above zero), filtered server-side over every match. Use it whenever the question says "still have stock" or "holding stock"; never state that condition from rows read without it.
`supplier_name`	No	Supplier name, fragment or acronym; resolved against the real supplier list. Without pre-owned trade-ins.
`units_l4w_below`	No	Only lines that sold FEWER than this many units over the last 4 weeks, counted server-side over every match ("amiibo that haven't sold 8 in 30 days" = 8). Lines with no measured sales are left out.
`only_recommended`	No	True = only SKUs named by an open recommendation.

Output Schema

Name	Required	Description
`rows`	Yes	Matching catalogue products.
`scope`	Yes	What population was searched.
`not_found`	No	With ids: identifiers no product in the caller's remit carries.
`truncated`	Yes	True when more rows matched than were returned.
`evidence_id`	Yes	Handle for these rows within this call's results. Not a citation.
`returned_rows`	Yes	Rows in this response.
`resolved_suppliers`	No	How a supplier_name filter resolved, when one was given.
`source_evidence_ids`	Yes	Workspace evidence IDs backing these rows. Empty when the source carries no evidence records.
`total_matching_rows`	Yes	Rows that matched before any limit.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 23, 2026

addedInput schema / properties / in_stock_only

Added value: +{
+  "description": "True = only lines with stock on hand (available stock above zero), filtered server-side over every match. Use it whenever the question says \"still have stock\" or \"holding stock\"; never state that condition from rows read without it.",
+  "type": "boolean"
+}

Changed6 schema fields changedOct 22, 2026

changedInput schema / properties / ids / description

Previous value: -"Up to 100 exact identifiers (barcode/SKU, source product id/PLU, supplier SKU, manufacturer SKU or alternate barcode), matched case-insensitively; case-variant duplicates resolve once. Use on its own, without query, supplier_name, category, only_recommended or limit. Overly broad results fail explicitly; use fewer or more specific ids."New value: +"Up to 100 exact identifiers (barcode/SKU, source product id/PLU, supplier SKU, manufacturer SKU or alternate barcode), matched case-insensitively; case-variant duplicates resolve once. Use on its own, without query, supplier_id, supplier_name, category, only_recommended or limit. Overly broad results fail explicitly; use fewer or more specific ids."

changedInput schema / properties / limit / description

Previous value: -"Maximum rows to return (1 to 100)."New value: +"Maximum rows to return (1 to 100), taken after order_by."

addedInput schema / properties / order_by

Added value: +{
+  "description": "Rank every match by a measure before the limit: slowest_selling or fastest_selling (units over 4 weeks), most_stock_at_cost, most_cover (days of cover). Omit for recommended first, then name, which ranks nothing.",
+  "enum": [
+    "slowest_selling",
+    "fastest_selling",
+    "most_stock_at_cost",
+    "most_cover"
+  ],
+  "type": "string"
+}

addedInput schema / properties / supplier_id

Added value: +{
+  "description": "A supplier's id as find_supplier returned it: that supplier's products, without pre-owned trade-ins. Prefer it to supplier_name once the supplier is resolved.",
+  "format": "uuid",
+  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+  "type": "string"
+}

changedInput schema / properties / supplier_name / description

Previous value: -"Supplier name, fragment or acronym; resolved against the real supplier list."New value: +"Supplier name, fragment or acronym; resolved against the real supplier list. Without pre-owned trade-ins."

addedInput schema / properties / units_l4w_below

Added value: +{
+  "description": "Only lines that sold FEWER than this many units over the last 4 weeks, counted server-side over every match (\"amiibo that haven't sold 8 in 30 days\" = 8). Lines with no measured sales are left out.",
+  "maximum": 100000,
+  "minimum": 0,
+  "type": "number"
+}

Changed3 schema fields changedOct 19, 2026

changedInput schema / properties / ids / description

Previous value: -"Up to 100 exact identifiers (barcode/SKU, source product id/PLU or supplier SKU), matched case-insensitively; case-variant duplicates resolve once. Use on its own, without query, supplier_name, category, only_recommended or limit. Overly broad results fail explicitly; use fewer or more specific ids."New value: +"Up to 100 exact identifiers (barcode/SKU, source product id/PLU, supplier SKU, manufacturer SKU or alternate barcode), matched case-insensitively; case-variant duplicates resolve once. Use on its own, without query, supplier_name, category, only_recommended or limit. Overly broad results fail explicitly; use fewer or more specific ids."

addedOutput schema / properties / rows / items / properties / manufacturer_sku

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "With ids: the manufacturer's part code, when the warehouse carries one."
+}

changedOutput schema / properties / rows / items / properties / matched_on / enum

Previous value: -[
-  "sku",
-  "source_product_id",
-  "supplier_sku"
-]New value: +[
+  "sku",
+  "source_product_id",
+  "supplier_sku",
+  "manufacturer_sku",
+  "alternate_barcode"
+]

Changed2 schema fields changedOct 19, 2026

changedInput schema / properties / ids / description

Previous value: -"Up to 100 exact identifiers (barcode/SKU, source product id/PLU or supplier SKU), matched case-insensitively. Use instead of query, not with it."New value: +"Up to 100 exact identifiers (barcode/SKU, source product id/PLU or supplier SKU), matched case-insensitively; case-variant duplicates resolve once. Use on its own, without query, supplier_name, category, only_recommended or limit. Overly broad results fail explicitly; use fewer or more specific ids."

changedOutput schema / properties / rows / items / properties / out_of_range_since / description

Previous value: -"When the product left the active range (ISO), or null while in range."New value: +"When sync first observed the product outside the active range (ISO), or null while in range; not a last-sale or exact exit date."

Changed7 schema fields changedOct 19, 2026

addedInput schema / properties / ids

Added value: +{
+  "description": "Up to 100 exact identifiers (barcode/SKU, source product id/PLU or supplier SKU), matched case-insensitively. Use instead of query, not with it.",
+  "items": {
+    "maxLength": 64,
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 100,
+  "minItems": 1,
+  "type": "array"
+}

addedOutput schema / properties / not_found

Added value: +{
+  "description": "With ids: identifiers no product in the caller's remit carries.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / rows / items / properties / id

Added value: +{
+  "description": "With ids: the identifier this row answers.",
+  "type": "string"
+}

addedOutput schema / properties / rows / items / properties / matched_on

Added value: +{
+  "description": "With ids: the column the identifier matched.",
+  "enum": [
+    "sku",
+    "source_product_id",
+    "supplier_sku"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / rows / items / properties / out_of_range_since

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "When the product left the active range (ISO), or null while in range."
+}

addedOutput schema / properties / rows / items / properties / source_product_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The source system's own product id (e.g. Retail Express id / PLU)."
+}

addedOutput schema / properties / rows / items / properties / supplier_sku

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The supplier's part number."
+}

Changed1 schema field changedOct 13, 2026

changedInput schema / properties / query / description

Previous value: -"Free text: brand, product words, SKU/barcode or category. Every word must appear somewhere in the row."New value: +"Free text: brand, product words, SKU/barcode, source product id/PLU, supplier code or category. Every word must appear somewhere in the row."

Changed2 schema fields changedOct 4, 2026

changedInput schema / properties / limit / description

Previous value: -"Maximum rows to return (1–100)."New value: +"Maximum rows to return (1 to 100)."

changedOutput schema / properties / rows / items / required

Previous value: -[
-  "sku",
-  "product",
-  "category",
-  "supplier",
-  "remit",
-  "recommended",
-  "recommendation_kind"
-]New value: +[
+  "sku",
+  "product",
+  "category",
+  "supplier",
+  "recommended",
+  "recommendation_kind"
+]

First observedOct 4, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is in edge behavior: ids each come back matched or in not_found, overly broad identifier sets fail explicitly, and ids must be used alone rather than combined with other filters. It does not say how many rows a broad query returns by default or anything about the response envelope, though an output schema exists.

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

Conciseness5/5

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

Four sentences, each load-bearing: scope, trigger, bulk-resolve mode, and sibling routing. The primary purpose is front-loaded and the density never becomes noise because each clause carries a distinct operational constraint.

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 10-parameter search tool with full schema coverage, an output schema, and complete annotations, the description supplies exactly what the structured fields cannot: selection guidance, the ids-alone constraint, and the explicit-failure behavior. Nothing an agent needs to invoke it correctly is missing.

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 3 is the floor, but the description genuinely adds semantics on top: the identifiers list is capped at 100 and resolves per-item with a not_found bucket, and the failure mode for overly broad identifier sets is called out. It does not re-explain query, supplier_id, or order_by, correctly leaving those to the schema.

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 (search) plus the resource and its exact scope (every product in the workspace's readable catalogue), then enumerates the filter axes: text, supplier, category, open recommendation. It names the sibling it is not (twelfth_list_products for figures, find_supplier for name resolution), so it is distinguishable without opening a schema.

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

Usage Guidelines5/5

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

Gives an explicit trigger: "Use it whenever a product, brand, barcode or supplier is named and you need to know whether and where it is stocked." It also routes to alternatives with conditions — twelfth_list_products for figures, find_supplier first when resolving an exact supplier name — and explains the bulk-resolve mode versus the broad-mode failure.

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

All Twelfth tools Inspect

Try in Browser

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Search catalogue

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources