Skip to main content
Glama

Best / most popular product in a category

best_in_category
Read-onlyIdempotent

Answers "what is the best / most popular / most bought X". Returns a one-sentence answer, the #1 and #2, the cheapest product in the top five, the fastest riser, the top 10, the sources the estimate is based on and the page URL. Shares are estimated % of purchases. Optional region, brand ("NARS", "Charlotte Tilbury"), finish ("Matte", "Dewy", "Satin") and budget_usd.

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": "best_in_category"
  }
}

Input Schema

NameRequiredDescriptionDefault
osNo
brandNoOnly this brand, e.g. NARS
monthNoMonth as YYYY-MM. Defaults to the latest month.
regionNoOptional region: a code (US, UK, EU, AU), a market (na, eu, uk, au) or a name like "Australia". Omit for the global ranking.
categoryYesCategory in plain words, e.g. "mascara", "foundation", "lip oil", "setting spray", or an id from list_categories.
budget_usdNoAlso return the most picked product at or under this US price

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

B3.4/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restating. The description earns credit for adding substance the annotations lack: an explicit inventory of what comes back (one-sentence answer, #1 and #2, cheapest in top five, fastest riser, top 10, sources, page URL) and a definition of shares as estimated % of purchases. It does not disclose the estimation methodology or how stale the underlying data may be.

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?

One dense paragraph that is front-loaded with the question it answers, then the return payload, then the filters — a sensible order with little filler. The enumeration of returned fields is long but justified because there is no output schema to carry that information.

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

Completeness3/5

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

With no output schema, the return-value enumeration is the right thing to include and is handled well. Completeness is undermined on the input side: two schema parameters (os, month) are never addressed and one phantom filter (finish) is described, so an agent cannot fully trust the description as a calling contract.

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

Parameters2/5

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

Schema coverage is 83%, so the schema already documents brand, month, region and budget_usd, and the description mostly repeats those examples rather than adding meaning. More seriously, it advertises a "finish" parameter ("Matte", "Dewy", "Satin") that does not exist in the input schema, which invites an invalid call, while the real `os` parameter (empty schema description) and `month` go unmentioned.

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 opens with a concrete question shape ("what is the best / most popular / most bought X") and names the resource (products in a category), which is instantly distinguishable from compare_products or get_product in intent. It stops short of explicitly naming which sibling to use for rankings or trend data, so sibling differentiation is implied rather than stated.

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

Usage Guidelines3/5

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

Usage is implied by the superlative-question framing: an agent knows to call this when the user asks for "the best" or "most popular" item. There is no explicit when-not-to-use guidance and no pointer to get_ranking or trending, so the agent must infer where this tool ends and the ranking/trend tools begin.

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.

Resources