Price comparison across partner retailers. Read-only, 90-day history, disclosed affiliate.
Exact multi-retailer offers for one product from WEM's own catalogue, cheapest first, with a 90-day price-history low. Identity is resolved by barcode or catalogue slug — no text matching — so every offer IS the product, and the lookup spends no retailer API quota. Use this FIRST when you have a barcode (EAN/UPC/GTIN) or a wem3.ai/pl/{slug} URL; fall back to search_products when the product is not in the catalogue yet.
| Name | Required | Description | Default |
|---|---|---|---|
| gtin | No | Product barcode: EAN-13, UPC-A, EAN-8 or GTIN-14. Preferred key. | |
| slug | No | WEM catalogue slug, or a wem3.ai/pl/{slug} URL / host path. Hosts may pass either form. |
| Name | Required | Description |
|---|---|---|
| offers | Yes | Ascending by price. Every row IS the product — resolved by barcode, not by title. |
| source | Yes | |
| product | Yes | |
| currency | No | |
| lowPrice | No | |
| highPrice | No | |
| disclosure | Yes | Affiliate disclosure to relay once per answer. Outbound links are tracked at no extra cost to the buyer. |
| priceHistory | Yes | The 90-day low, for telling a real discount from a repackaged one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral detail beyond those: exact identity matching, no retailer API quota consumption, catalogue-scoped results, and the price-history-low inclusion. This goes well beyond what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and every sentence earns its place: core behavior, key identity/constraint details, and explicit usage direction. It is front-loaded with the most important outcome and wastes no words on restating the title or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an existing output schema and complete parameter schemas, the description covers the essential contextual gaps: exact vs fuzzy matching, quota behavior, sort order, and fallback routing. An agent has enough information to decide when to call this tool and what it will return.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both gtin and slug are already well documented in the input schema. The description reinforces that identity is resolved by barcode or slug and that there is no text matching, but does not add parameter-level detail beyond what the schema provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it returns exact multi-retailer offers for a single product, sorted cheapest first, with a 90-day price-history low. It clearly differentiates from search-based siblings by emphasizing barcode/slug identity resolution and 'no text matching,' so an agent can distinguish it from tools like search_products and semantic_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool FIRST when a barcode or wem3.ai/pl/{slug} URL is available, and to fall back to search_products when the product is not yet in the catalogue. This provides clear when-to-use guidance and names the alternative, leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare 2-5 products side by side. Returns a structured comparison of price, rating, shipping, and key features. Use when the user is deciding between options.
| Name | Required | Description | Default |
|---|---|---|---|
| products | Yes | List of products to compare (2-5 items) |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| comparison | Yes | |
| disclosure | Yes | Affiliate disclosure to relay once per answer. Outbound links are tracked at no extra cost to the buyer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the description does not need to repeat safety traits. It adds value by revealing the output structure (comparison of price, rating, shipping, features) and the 'side by side' presentation. No contradiction with annotations, and it supplements them with expected output details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of exactly two sentences: the first states the function and output, the second gives usage guidance. Every word is purposeful, with no redundancy or filler. It is front-loaded and immediately actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description doesn't need to detail return values. The description covers purpose, usage, and scope, while the annotations cover safety and openness. The tool's low complexity (single parameter) means this is fully complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the sole parameter 'products' is described in the schema itself with 'List of products to compare (2-5 items)'. The description mirrors this constraint but adds no new meaning about parameter composition (e.g., provider/product_id fields). Since the schema does the heavy lifting, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (compare), the target (products), and the scope (2-5, side by side). It also specifies the comparison attributes (price, rating, shipping, key features), which distinguishes it from sibling tools like compare_offers (offer-level comparison) and find_lowest_price (price-only focus).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: 'Use when the user is deciding between options.' This tells the agent when to select this tool, but it does not explicitly mention when not to use it or name alternative tools. It's good context but lacks exclusions or explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the single lowest-priced product matching the stated constraints. Ranks on price, adjusted for the priorities the caller states (rating, shipping) — never on WEM commission. Use when the user wants a recommendation rather than a list. Candidates are filtered to plausible matches for the query first, so a cheap accessory cannot be returned as the cheapest way to buy the product itself; recommendation may be null with a reason when nothing matched confidently, and that must be reported as "no confident match" rather than softened into a suggestion. recommendation.verified marks an offer whose identity WEM has resolved rather than inferred.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to search for | |
| max_price | No | Budget cap (GBP) | |
| priorities | No | What matters most (in order of importance) |
| Name | Required | Description |
|---|---|---|
| score | No | Internal ranking score. Not a price and not a rating — do not quote it. |
| reason | Yes | Why this was picked, or why nothing was. |
| filtered | No | Withheld candidates tallied by reason (e.g. accessories, wrong model). Report this count rather than implying the search was exhaustive. |
| disclosure | No | Affiliate disclosure to relay once per answer. Outbound links are tracked at no extra cost to the buyer. |
| alternatives | No | Up to three runners-up. |
| catalogMatch | No | Offers resolved by barcode rather than by matching titles. When present, prefer these and cite their prices over anything in `products`. |
| recommendation | Yes | The single lowest-priced plausible match, or null when nothing matched confidently. |
| liveSearchSkipped | No | True when a catalogue hit answered the question without spending retailer API quota. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint, the description discloses key behaviors: ranking is never on WEM commission, candidates are pre-filtered for plausibility, null recommendations come with a reason and must be reported honestly, and the `verified` field indicates identity resolution. These add substantial transparency beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: purpose, ranking rule, usage directive, filtering behavior, null handling, and verified flag. It is well-structured and front-loaded, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description covers all essential operational aspects: what it returns, when it may return null, how to interpret `verified`, and key filtering logic. It leaves no critical gaps for an agent to make correct invocation or response handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions already cover all three parameters fully (100% coverage). The description adds a little context (e.g., priorities may include 'rating, shipping' and ranking adjusts to them), but it does not materially change or deepen parameter understanding beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific, unambiguous purpose: 'Find the single lowest-priced product matching the stated constraints.' It distinguishes itself from list-returning siblings by noting 'Use when the user wants a recommendation rather than a list' and clarifies the ranking basis is never WEM commission, making it distinct from other search/compare tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use when the user wants a recommendation rather than a list.' It also provides important usage caveats, such as candidates being filtered to plausible matches to prevent cheap accessories from being returned as the product, and how to handle null recommendations ('must be reported as "no confident match"').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get available product categories and the approximate price range for each. Use to guide the user when their request is vague.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| currency | Yes | |
| providers | Yes | Retailers currently enabled. WEM compares only feeds it is licensed to use. |
| categories | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the 'approximate price range' detail, which is behavioral info beyond annotationsscrib. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states what the tool does, second gives usage guidance. No fluff, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, an output schema exists, and read-only annotations, the description provides the essential purpose and usage context. It mentions price range which adds value. It's complete for a simple listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100% by definition. Baseline is 4, and the description adds no parameter info (not needed).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists product categories with approximate price ranges, using specific verbs ('Get') and resource ('product categories'). It's distinct from siblings that focus on offers, products, prices, or searches, so differentiation is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use to guide the user when their request is vague,' giving a clear context for when to invoke this tool. It doesn't mention alternatives or when not to use, but the usage condition is specific enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details for a specific product by its provider and ID. Use after search results to get more info before recommending.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | Yes | Provider name (e.g. "ebay", "awin") | |
| product_id | Yes | Product ID from search results |
| Name | Required | Description |
|---|---|---|
| id | No | |
| url | Yes | WEM tracked link to the retailer. Send the user here — WEM never takes payment. |
| brand | No | |
| image | No | |
| price | No | Indicative price. The retailer sets the final price at checkout. |
| title | No | |
| badges | No | |
| rating | No | |
| seller | No | |
| inStock | No | |
| currency | No | ISO 4217 code. |
| features | No | |
| provider | No | Retailer slug, e.g. "ebay", "currys". |
| shipping | No | |
| disclosure | Yes | Affiliate disclosure to relay once per answer. Outbound links are tracked at no extra cost to the buyer. |
| description | No | |
| reviewCount | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety expectations. The description adds that it returns full details but does not elaborate on behavior such as error handling or data completeness beyond what annotations imply. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action, and contains no redundant or extraneous information. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with full schema coverage, an output schema, and safety annotations, the description sufficiently contextualizes when and how to use the tool. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with per-parameter descriptions for provider and product_id. The description adds the contextual note that product_id comes from search results, slightly reinforcing usage but not extending the schema's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details for a specific product by provider and ID, using a specific verb and resource. This distinguishes it from siblings like search_products (which searches) and compare_products (which compares).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool after search results to get more info before recommending, providing clear context. It does not explicitly name alternatives to avoid, but the usage flow is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for products across all connected marketplaces (eBay, Amazon, Awin merchants, etc.) using keywords. Returns a list of matching products with prices, images, and affiliate links. Suited to specific keyword searches like "airpods pro" or "nike running shoes". When the query names a product in WEM's own catalogue, a catalogMatch block is also returned: its offers are identity-resolved rather than title-matched, so prefer them and cite its prices over anything in products. Weak matches are withheld and tallied by reason in filtered — report that count rather than implying the search was exhaustive.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (default 10, max 30) | |
| query | Yes | Search keywords | |
| sort_by | No | Sort order for results | |
| category | No | Filter by category (electronics, fashion, beauty, home, sports, collectibles) | |
| max_price | No | Maximum price filter (GBP) | |
| min_price | No | Minimum price filter (GBP) | |
| providers | No | Limit to specific providers (e.g. ["ebay", "awin"]). Omit for all. |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| filtered | No | Withheld candidates tallied by reason (e.g. accessories, wrong model). Report this count rather than implying the search was exhaustive. |
| products | Yes | |
| disclosure | Yes | Affiliate disclosure to relay once per answer. Outbound links are tracked at no extra cost to the buyer. |
| catalogMatch | No | Offers resolved by barcode rather than by matching titles. When present, prefer these and cite their prices over anything in `products`. |
| totalResults | Yes | Count of products returned, after weak matches were withheld. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the return structure including the catalogMatch block and the filtered counts, and explains the identity-resolution logic, which goes beyond the basic annotations to clarify expected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed yet efficient, covering all essential aspects in five concise sentences without redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description sufficiently explains the main return elements (products, catalogMatch, filtered) and their implications, making it complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all parameters, so the description adds little beyond noting that queries should be specific keywords, which only subtly informs parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it searches for products across all connected marketplaces, distinguishing it from specialized siblings like compare_offers or find_lowest_price.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states it is suited to specific keyword searches and provides guidance on handling catalogMatch (prefer it) and filtered results (report count), giving clear when-to-use and interpretation instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for products using natural language descriptions. Uses AI embeddings for semantic understanding — handles vague requests like "comfortable shoes for standing all day" or "gift for a 10 year old who likes science". Falls back to keyword search when vector data is unavailable.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 10, max 20) | |
| category | No | Optional category filter | |
| max_price | No | Maximum price (GBP) | |
| min_price | No | Minimum price (GBP) | |
| description | Yes | Natural language description of what the user is looking for |
| Name | Required | Description |
|---|---|---|
| query | No | |
| filtered | No | Withheld candidates tallied by reason (e.g. accessories, wrong model). Report this count rather than implying the search was exhaustive. |
| products | Yes | |
| semantic | No | True only when the vector path actually ran. |
| disclosure | Yes | Affiliate disclosure to relay once per answer. Outbound links are tracked at no extra cost to the buyer. |
| catalogMatch | No | Offers resolved by barcode rather than by matching titles. When present, prefer these and cite their prices over anything in `products`. |
| totalResults | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open-world hints temp_SR. The description adds value by disclosing the semantic nature of the search, handling of vague requests, and the fallback to keyword search when vector data is unavailable—behavior not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, then examples and fallback behavior. Every phrase adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (semantic search with fallback) and the presence of a complete schema and output schema, the description covers the unique value (semantic understanding), fallback behavior, and usage context. It is sufficient for an agent to decide when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema. The description adds minimal extra parameter semantics beyond clarifying that 'description' is natural language, which is already in the schema; therefore, it meets the baseline but adds little.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Search for products using natural language descriptions') and distinguishes from sibling tools by emphasizing semantic understanding and natural language queries, clearly separating it from keyword-based search_products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the tool handles vague requests, implying use for natural language queries, and mentions fallback to keyword search when vector data is unavailable. While it doesn't explicitly exclude other tools, the examples and fallback note provide strong context on when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a price claim before repeating it. Given a product and a price someone has asserted at a named retailer, returns whether that price is live in WEM's verified catalogue and whether anything cheaper exists. Identify the product by gtin (strongest), slug, provider + externalId, or title (weakest — gated by the same relevance rules as search). Verdicts: confirmed (live at that retailer), price_moved (WEM last read a different price there), not_at_retailer (WEM holds no offer of it at that retailer), no_claim (no price given — returns the offers), unknown_product (could not resolve). unknown_product means the claim could NOT be checked; it never means the claim is false, and must not be reported as one. Every result carries lastConfirmedAt so the answer's freshness is visible. Use this before quoting any price you did not get from WEM.
| Name | Required | Description | Default |
|---|---|---|---|
| gtin | No | Product barcode: EAN-13, UPC-A, EAN-8 or GTIN-14. Strongest identifier. | |
| slug | No | WEM canonical slug, as in wem3.ai/pl/{slug}. | |
| price | No | The price being claimed. Omit to ask only what the verified offers are. | |
| title | No | Product title. Weakest identifier — used only when no id is available. | |
| currency | No | ISO 4217 code for the claimed price. Default GBP. | |
| provider | No | Retailer slug for the listing being checked, e.g. 'currys'. | |
| retailer | No | Retailer the price was claimed at — slug or display name. | |
| externalId | No | The retailer's own product id (ASIN, eBay item number). Use with provider. |
| Name | Required | Description |
|---|---|---|
| offers | Yes | |
| source | Yes | |
| product | No | |
| receipt | Yes | Unsigned citation handle for this answer. Serialises what was already returned. signed is always false. |
| summary | Yes | Written so quoting it verbatim is accurate. Prefer quoting it to paraphrasing the verdict code. |
| verdict | Yes | |
| betterBy | No | Saving from taking `cheapest` over the claimed price. Never negative. |
| cheapest | No | |
| identity | No | How the product was identified — a separate question from whether the price checks out. Never present a `strength` of "inferred" as a verified identity. |
| disclosure | Yes | Affiliate disclosure to relay once per answer. Outbound links are tracked at no extra cost to the buyer. |
| resolvedBy | No | Which identifier resolved the product. |
| claimMatched | No | |
| comparisonSet | No | How wide the comparison behind `cheapest` was. `exhaustive` is always false: WEM does not see every retailer, so `cheapest` is the lowest offer WEM holds, never the lowest that exists. Relay it as such. |
| lastConfirmedAt | No | When WEM last read these offers — the freshness of this answer. |
| toleranceApplied | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, and the description adds substantial behavioral context on top: the exact verdict set, the crucial caveat that unknown_product must never be reported as false, and the presence of lastConfirmedAt for freshness. This goes well beyond the annotations and prevents dangerous misinterpretation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place: purpose, identifier strategy, verdict semantics, the critical unknown_product warning, freshness, and usage guidance. The most actionable instruction ('Check a price claim before repeating it') is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, none required, and high ambiguity risk, the description covers the full invocation context: how to identify the product, what the verdicts mean, how to interpret the weakest identifier, and when to call it. The output schema handles return-value details, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds genuine value by ranking identifier strength (gtin strongest, title weakest), explaining that omitting price returns offers, and clarifying the interplay of provider and externalId. These are semantic distinctions not present in the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('check'), a clear resource ('a price claim'), and the exact decision it produces (whether that price is live and whether anything cheaper exists). This distinguishes it sharply from siblings like find_lowest_price or get_product without needing to open their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this tool before quoting any price not obtained from WEM, which gives a clear trigger for invocation. It also explains identifier precedence and the meaning of each verdict, though it does not explicitly name sibling alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Search 86 US retailers — 260M+ products with real-time pricing, stock, and price history.
Game prices across verified stores, with price history and a buy-now-or-wait verdict.
Search 86 US retailers, 260M+ products with real-time pricing, stock, and price history. Documentation - https://www.lemmebuyit.com/developer Homepage - https://www.lemmebuyit.com
Curated, human-reviewed deal feed for AI agents — live deal search + price watches. No auth.
Add one secure layer between your agents and this server.
Each tool targets a distinct action: searching, semantic searching, retrieving categories or product details, comparing offers, comparing products, finding a single lowest price, and verifying a claim. The only mild ambiguity is between search_products and semantic_search, and between compare_offers and find_lowest_price, but the descriptions provide enough separation for an agent to choose correctly.
Most tools follow a clear verb_noun pattern such as compare_offers, get_product, search_products, and verify_offer. The main deviation is semantic_search, which is adjective_noun rather than verb_noun, making it the one inconsistent name in an otherwise predictable set.
Eight tools is a well-scoped size for a price-comparison server. Each tool covers a meaningful part of the workflow without redundancy or unnecessary breadth.
The toolset covers product discovery, category browsing, detailed product retrieval, multi-offer comparison, side-by-side product comparison, lowest-price recommendation, and price-claim verification. The main gap is the lack of a dedicated price-history tool, even though a 90-day price low is referenced in compare_offers, but this is not a blocking omission for the core comparison workflow.
