Skip to main content
Glama

AirShelf Catalog

by ai.airshelf
OverviewDiscussionsAdmin

Research a considered purchase

research_shopping

research_shopping is the full verified-research job; find_products is the quick candidate-list tool. It runs as a background job and returns status "running" with a research ID while the minutes-long research continues; the same research ID returns the run on later polls until completion. Unsafe medical, legal, financial-advice, and professional-service asks return status "refused" before any work is queued. Completed runs return a researched recommendation with per-claim source receipts, or an explicit refusal when evidence is insufficient. Missing decision details return clarification questions before research starts. market biases discovery and marketplace checks toward seller pages serving that country; "available in " means the seller page serves that market, not that stock is guaranteed. Example answer keys include {"budget":"500 USD","market":"US","category":"espresso machine"}.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
needNoBuyer need in natural language. Required when starting a new research run.
marketNoBuyer market as an ISO 3166-1 alpha-2 country code. Biases discovery and marketplace checks toward seller pages serving that country; availability is not a stock guarantee.
answersNoAnswers to clarification questions. Set accept_defaults:true to accept budget and market defaults; it does not waive product type, use case, or must-have requirements.
personaNoResearch persona; b2b produces a quotation/RFQ pack.
research_idNoExisting research run identifier to read instead of starting a new run.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
stageNo
reasonNo
statusYes
dossierNo
outcomeNo
questionsNo
eta_secondsNo
research_idNo
stage_countersNoProgress counters for a running research job. Individual counters may be absent.
elapsed_secondsNo
accepted_defaultsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedOutput schema / properties / stage_counters / description
      Added value: +"Progress counters for a running research job. Individual counters may be absent."
    • addedOutput schema / properties / stage_counters / properties
      Added value: +{
+  "candidates_found": {
+    "description": "Candidates found during discovery.",
+    "type": "number"
+  },
+  "listings_checked": {
+    "description": "Market listing URLs recorded during commercial checks.",
+    "type": "number"
+  },
+  "stage": {
+    "description": "Current pipeline stage identifier, or queued before work starts.",
+    "type": "string"
+  },
+  "verified": {
+    "description": "Candidates examined during verification, not a count of candidates that passed.",
+    "type": "number"
+  }
+}
    • removedOutput schema / properties / stage_counters / propertyNames
      Removed value: -{
-  "type": "string"
-}
  2. Changed1 schema field changed
    • addedOutput schema / properties / accepted_defaults
      Added value: +{
+  "additionalProperties": {
+    "type": "string"
+  },
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}
  3. Changed1 schema field changed
    • changedInput schema / properties / answers / description
      Previous value: -"Answers to clarification questions. Set accept_defaults:true to explicitly waive missing dimensions."New value: +"Answers to clarification questions. Set accept_defaults:true to accept budget and market defaults; it does not waive product type, use case, or must-have requirements."
  4. Changed1 schema field changed
    • changedOutput schema / properties / status / enum
      Previous value: -[
-  "needs_input",
-  "running",
-  "complete",
-  "failed"
-]New value: +[
+  "needs_input",
+  "running",
+  "complete",
+  "failed",
+  "refused"
+]
  5. Changed1 schema field changed
    • addedInput schema / properties / persona
      Added value: +{
+  "description": "Research persona; b2b produces a quotation/RFQ pack.",
+  "enum": [
+    "consumer",
+    "b2b"
+  ],
+  "type": "string"
+}
  6. Changed1 schema field changed
    • removedInput schema / properties / market / pattern
      Removed value: -"^[A-Za-z]{2}$"
  7. Added

TDQS

A4.7/5.0
Behavior5/5

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

The description goes far beyond the annotations by disclosing async execution, polling via research_id, 'running'/'refused' statuses, per-claim source receipts, explicit refusal on insufficient evidence, and clarification-before-research behavior. It also clarifies the market semantics as 'seller page serves that market, not that stock is guaranteed.' This adds substantial behavioral context beyond readOnlyHint, openWorldHint, and destructiveHint.

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?

Every sentence in the description carries signal: purpose contrast, async lifecycle, refusal policy, completion output, clarification flow, market caveat, and example answer keys. It is front-loaded with the tool's purpose and contains no filler or repetition.

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 complex 5-parameter async job, the description covers the full lifecycle: starting research, polling by research ID, receiving a completed recommendation, handling refusals, and getting clarification questions. It also explains nested and market-dependent semantics. Since an output schema exists, not restating the full return shape in prose is acceptable.

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 100%, so the parameters are already well documented. The description adds extra meaning by explaining the market bias and by providing an example answer key for the answers object ({budget, market, category}), which helps an agent structure a nested free-form parameter. It does not redundantly re-explain need or persona.

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?

The description opens by stating a specific verb, resource, and scope: 'research_shopping is the full verified-research job,' and immediately contrasts it with 'find_products is the quick candidate-list tool.' The title 'Research a considered purchase' reinforces the intended use case. An agent can distinguish this tool from siblings without opening other schemas.

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?

The description explicitly positions research_shopping against find_products, signaling that it is the slower, more thorough alternative. It also clarifies when research will not proceed: unsafe domains are 'refused' and missing decision details produce clarification questions. It does not explicitly route the agent among the other siblings like compare_products or request_quote, so some usage context is left implicit.

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

All AirShelf Catalog toolsInspect
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