Skip to main content
Glama
Sign In

Logimu

by com.logimu
OverviewDiscussionsAdmin

serp

Read-onlyIdempotent

LIVE Amazon search-results (SERP) fetch: a real browser navigates Amazon's search page RIGHT NOW and returns the parsed organic result grid plus everything around it. USE WHEN the user wants what Amazon's search page shows THIS MINUTE for a query — current ranking order, who is on page 1, sponsored/ad placements, related searches, refinement filters — or when the curated tools found nothing and the user wants Amazon itself checked. DON'T USE for ordinary product discovery (shopping is <100ms and curated), for filtered datasets (search), or for one known ASIN (product). RETURNS search_results (position, asin, title, link, image, rating, ratings_total, price, list_price, unit_price (Amazon's per-unit price, where the card prints one, never the price), recent_sales badge, sponsored, is_prime), search_information (Amazon's OWN result-count estimate — 'over 20,000' is an estimate, not a count), pagination, related_searches, refinements (round-trip: pass a refinements[*].value back in), ad_blocks / video_blocks (sponsored placements; their links are Amazon ad-redirectors, NOT clean product URLs) and brand_stores (organic store headers only — legitimately empty on sponsored-heavy pages). HONESTY: results per page is Amazon's choice (16-48, varies); sponsored is usually false because Amazon puts paid placements in separate carousels; is_prime false means 'no icon rendered', not 'not Prime'; recent_sales is the verbatim badge string in the page's own language; spelling_correction reports Amazon's autocorrect, it cannot disable it. LATENCY is SECONDS — typically ~8-13s, up to ~90s when the retry ladder runs; tell the user it is a live fetch. Every call is live: there is no cached SERP and no mode parameter. MARKETPLACES us, uk, de, ca, au, fr, it, es, jp, mx, br, walmart (live walmart.com search: 2 credits per results page, at most 3 pages a call, location names the store it was priced for; category_id and refinements are Amazon-only). COST API key required (the free no-signup lane cannot run live fetches). 1 credit per page ACTUALLY fetched — max_page=3 can stop at 2 when Amazon runs out; blocked fetches (502) and empty result sets are never billed. ZIP (2026-10-29, country=us only): pass zip (a US 5-digit ZIP) to search as a shopper at that ZIP sees it - a plain search at a city ZIP lists the local stores' items (Whole Foods, Amazon Fresh, local partners) beside shipped ones; store=wholefoods|fresh runs Amazon's own storefront search for that store's assortment at the ZIP. USE WHEN the user asks what a recipient at a ZIP can buy (groceries, same-day items), which store carries a query locally, or delivery fees / windows / minimums per item. The answer adds location (the result page's confirmed 'Deliver to'), store, empty_reason (null with results; no_results_at_zip or store_nothing_for_query_at_zip - the latter cannot tell a store that skips the ZIP from one with no match for the query), observed_at and request_metadata.zip_session (new | reused: a session at a ZIP is kept a few minutes per account, so a follow-up search or an offers zip= check on the same ZIP is fast). Per result: store (from the card's own store link, never guessed), delivery (Amazon's line as printed), delivery_terms {fee, window, free_over, membership, pickup, fastest, non_member} - the terms Amazon shows a signed-out shopper, Prime included; a field the line does not state is null, and NEVER report free delivery from a missing fee - and stock {state: in_stock|low_stock|out_of_stock|null, left} (null = the card shows no price and no stock line, availability unknown: check it with offers zip=). Results and their order are Amazon's own; this is discovery, not a stock check: confirm an item with offers zip= before the user buys. At most 3 pages a call. LATENCY typically 5-10 s for the first search at a ZIP, up to about a minute when Amazon challenges new sessions; about 1-2 s for a follow-up on the same ZIP. BILLING at a ZIP: 1 credit per page fetched, a VERIFIED empty page included (Amazon's own no-results text on a page that confirmed the ZIP, empty_reason set) - the one exception to 'empty never bills'; a block, a checkpoint page, an unconfirmed ZIP or no answer is a failure, never an empty answer, never billed; a ZIP Amazon rejects is guidance, never billed.

Input Schema

NameRequiredDescriptionDefault
qYesThe search query, exactly as a shopper would type it into Amazon's search box. Query in the marketplace's own language.
zipNoOptional (2026-10-29): a US 5-digit ZIP - the search as a shopper at that ZIP sees it, with the local stores' items, each result's store, delivery_terms and stock, and the page's confirmed location. country=us only; at most 3 pages a call. A verified empty answer (empty_reason set) is billed 1 credit. ZIP+4 is cut to 5 digits.
pageNoStart page (1-10).
storeNoOptional, with zip only: Amazon's own storefront search for that store's assortment at the ZIP (Whole Foods Market or Amazon Fresh). A local partner such as Lucky is reached through refinements with its p_n_alm_brand_id value. Cannot be combined with category_id.
countryNoAmazon marketplace to search, or walmart (a live walmart.com search).us
sort_byNoAmazon's own sort orders; default is Amazon's Featured.
max_pageNoAuto-paginate page..max_page and concatenate (positions stay continuous across pages). Max 10 pages per request; billed per page actually fetched.
category_idNoAmazon browse-node id to scope the search (becomes &node=).
refinementsNoAmazon rh= refinement value. Round-trips: feed back any refinements[*].value from a previous serp response.
exclude_sponsoredNoDrop inline sponsored results. Often a no-op — Amazon usually keeps paid placements in separate carousels outside the organic grid.
number_of_resultsNoTruncate the returned result list.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / store
      Added value: +{
+  "description": "Optional, with zip only: Amazon's own storefront search for that store's assortment at the ZIP (Whole Foods Market or Amazon Fresh). A local partner such as Lucky is reached through refinements with its p_n_alm_brand_id value. Cannot be combined with category_id.",
+  "enum": [
+    "wholefoods",
+    "fresh"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / zip
      Added value: +{
+  "description": "Optional (2026-10-29): a US 5-digit ZIP - the search as a shopper at that ZIP sees it, with the local stores' items, each result's store, delivery_terms and stock, and the page's confirmed location. country=us only; at most 3 pages a call. A verified empty answer (empty_reason set) is billed 1 credit. ZIP+4 is cut to 5 digits.",
+  "type": "string"
+}
  2. Changed2 schema fields changed
    • changedInput schema / properties / country / description
      Previous value: -"Amazon marketplace to search. No Walmart — live SERP is Amazon-only."New value: +"Amazon marketplace to search, or walmart (a live walmart.com search)."
    • changedInput schema / properties / country / enum
      Previous value: -[
-  "us",
-  "uk",
-  "de",
-  "ca",
-  "au",
-  "fr",
-  "it",
-  "es",
-  "jp",
-  "mx",
-  "br"
-]New value: +[
+  "us",
+  "uk",
+  "de",
+  "ca",
+  "au",
+  "fr",
+  "it",
+  "es",
+  "jp",
+  "mx",
+  "br",
+  "walmart"
+]
  3. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Although annotations already mark it read-only, open-world, idempotent, and non-destructive, the description contributes substantial behavioral context: live latency, credit billing rules, marketplace coverage, empty-result billing exceptions, sponsored-placement caveats, and ZIP-session behavior. These details go well beyond what annotations and schema disclose.

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 and structured with USE WHEN, DON'T USE, RETURNS, HONESTY, LATENCY, COST, and ZIP sections, so an agent can navigate it. However, it is very long and repeats some latency and billing details, which keeps it from being maximally concise.

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?

Given the tool's complexity, 11 parameters, and lack of an output schema, the description is complete: it describes returned fields, caveats, billing, latency, marketplaces, and ZIP-specific behavior in enough detail to call the tool correctly. Nothing essential is missing for an agent deciding whether and how to use it.

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

Parameters5/5

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

Schema coverage is already 100%, but the description adds meaningful semantics for parameters: refinements round-trip, store combined with zip, zip behavior and billing, exclude_sponsored often being a no-op, max_page billing and page continuity, and Amazon-only category/refinements constraints. This is well beyond baseline since the schema already documents all parameters.

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 states a specific verb and resource: live Amazon SERP fetch returning the parsed organic result grid. It explicitly distinguishes this tool from curated discovery via shopping, filtered datasets via search, and known-ASIN lookup via product, so an agent can identify it without opening the 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?

It gives explicit USE WHEN and DON'T USE guidance, naming sibling tools (shopping, search, product) and the conditions under which each is preferable. It also adds a detailed ZIP-specific use case with when-to-use criteria for local availability, store assortment, and delivery terms.

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

All Logimu 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