Skip to main content
Glama

Browse a category shelf

browse_category
Read-only

Return a category's consolidated, ranked shelf: one row per product, with duplicate seller listings already collapsed. Each row carries price, price_band, buy_url and buy_seller (the retailer behind the link), image_url, star ratings, and the category's required and top-weighted spec values. card_specs gives the specs every product card shows, in display order. type_filter lists the category's product types (robot, stick, handheld ...) with how many matching rows each holds; a filter {dimension, equals: value} on its dimension narrows to one. Filters are hard: a row missing the attribute is excluded. Preferences are soft: rows that measure well on them rank higher and none are excluded (for example Rated Noise, prefer low, or a pet-hair rating, prefer high). Sort by value (default), quality, or price_asc. A filter on the Price dimension applies min/max to the live offer price in cents. Responses that carry buy_url links also carry a disclosure field: the commission disclosure for those links.

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": {
      "category": "<category>"
    },
    "name": "browse_category"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNo
limitNo
cursorNo
filtersNo
categoryYes
preferencesNoSoft preferences: rows that measure well on a dimension rank higher, and none are excluded. Each row reports preference_boost.
user_signatureNoOptional opaque, stable, pseudonymous user id: the shopper's own rate-limit quota and click attribution. Format: 'sv1-' + the first 24 hex characters of SHA-256('swervie/v1|' + normalized identifier), or 'sv1r-' + a UUID. A raw email or phone number is hashed server-side before anything is stored.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / user_signature / description
      Previous value: -"Optional opaque, stable, pseudonymous user id that personalizes ranking. Format: 'sv1-' + the first 24 hex characters of SHA-256('swervie/v1|' + normalized identifier), or 'sv1r-' + a UUID. A raw email or phone number is hashed server-side before anything is stored."New value: +"Optional opaque, stable, pseudonymous user id: the shopper's own rate-limit quota and click attribution. Format: 'sv1-' + the first 24 hex characters of SHA-256('swervie/v1|' + normalized identifier), or 'sv1r-' + a UUID. A raw email or phone number is hashed server-side before anything is stored."
  2. First observed

TDQS

A4.2/5.0
Behavior5/5

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

Beyond the readOnly and openWorld annotations, it discloses duplicate collapse, row fields, hard-filter exclusion behavior, soft-preference ranking behavior, price filter units in cents, and commission disclosure when buy_url links are present. These are meaningful behavioral details an agent would not get from annotations alone.

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?

The description is front-loaded with the core purpose and then adds filtering, preference, sort, and disclosure semantics without obvious filler. It is dense and somewhat run-on in places, mixing output metadata such as card_specs and type_filter with input behavior, but every part is relevant.

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

Completeness4/5

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

With no output schema, the description supplies useful return-field detail: row price, price_band, buy_url, buy_seller, image_url, ratings, specs, card_specs, type_filter, and disclosure. It still does not explain pagination behavior or the top-level response shape around cursor and limit, leaving a modest completeness gap for a complex tool.

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 description coverage is only 29%, so the description must carry parameter meaning, and it does for the complex inputs: filters are hard and exclude missing attributes, preferences are soft and never exclude, Price min/max uses live offer price in cents, and sort supports value, quality, and price_asc. It does not explain limit, cursor, or any_of in comparable detail, so it is strong but not complete.

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

Purpose4/5

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

The description uses a specific verb and resource: 'Return a category's consolidated, ranked shelf' with 'one row per product' and duplicate seller listings collapsed. That is clear and specific, but it does not explicitly differentiate this shelf browse from siblings such as search_products or get_products.

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 gives clear context for browsing a category shelf and explains how to use filters, preferences, and sort. It does not explicitly name when to choose this over sibling tools or state exclusions, so it falls short of full alternative routing.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.