logimu-shopping-mcp

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, lowering the bar. The description adds genuinely useful non-annotation context: cost is free/never billed, it requires an API key, and without a key 'nothing to report.' It does mention the data is a daily snapshot, which is helpful, but doesn't clarify freshness/timing or the response shape.

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?

Three dense sentences, front-loaded with the resource and scoping, then usage triggers, then cost/auth constraints. Every sentence earns its place, though the parenthetical 'snapshots a day: total, used, remaining' is slightly cramped.

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 zero-param read-only tool with full annotation coverage, the description covers purpose, triggers, cost, and auth requirement. No output schema exists, so it could say more about return shape, but the enumeration of plan/usage/tracking fields largely compensates.

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?

Zero parameters, so the baseline is 4. Description adds accurate framing that the tool acts on the calling key rather than a passed identifier, which is the key semantic point for a parameterless tool.

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?

Names a specific resource (the calling key's balance, plan, usage, and tracking allowance) and enumerates exactly what data it exposes, ending with an equivalence to REST GET /v1/account. This clearly distinguishes it from siblings like track_product or list_tracked, which are write/list operations.

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 USE WHEN clause gives four explicit trigger conditions (credits left, job cost projection, usage history, tracking room), and COST free plus API key required establishes constraints. No alternative tool is named, but none of the siblings clearly overlaps this read-only account resource.

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

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

Annotations already declare destructive=true and not-idempotent, and the description adds substantial context beyond them: per-row billing, that failed/not-found/duplicate rows are never billed, serialized runs per marketplace, API-key requirement, HMAC-signed webhooks, and estimate-as-ceiling behavior. It stops short of describing run lifecycle failure modes or queue semantics in depth, but the coverage is well above the annotation baseline.

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?

Front-loads purpose, then the USE WHEN trigger, then action semantics, then cost/auth — a sensible order. It is very dense and partly repetitive ('estimate ... (free)' restated in the COST sentence) and would benefit from tighter phrasing, but almost every clause carries information.

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 29-parameter tool with no output schema, the description covers actions, kinds, cost/billing rules, auth requirements, and scheduling behavior. Nothing essential for correct invocation is missing, and the download-URL return hint compensates for the absent output schema.

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 90%, so the schema already documents most parameters and a baseline of 3 would apply. The description goes further by mapping action strings to concrete behaviors, explaining kind routing, and adding cost/tier notes (e.g. 'typically with include [history_only] at 0.05 a row') that the schema does not carry.

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?

Opens with a specific verb and resource: 'run any Logimu endpoint over a whole list in one job', and ties itself to the REST /v1/batches API. The explicit USE WHEN clause (more than a handful of ASINs, refresh, CSV) separates it cleanly from the single-item siblings like product and 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?

Enumerates every action with its precise effect (estimate/create/run/status/results/list/schedule/delete) and states when to reach for this tool over the single-item siblings ('more than a handful', 'daily/weekly refresh', 'wants a CSV'). The billing model and free-vs-billable distinction further guide the selection decision.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, and the description still adds substantial operational context: seconds-scale latency (~15-35s fresh, ms when cached), cache TTLs (30 min category, 24 h root), credit pricing including free root and unbilled failure modes, API-key requirement, and honesty caveats about language, null prices and null node_ids. This is exactly the beyond-annotations content the dimension rewards.

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?

Front-loaded with purpose, then USE/DON'T USE, RETURNS, HONESTY, LATENCY, MARKETPLACES, COST — every block is load-bearing for a live, billed, cached fetcher. It is long, and the RETURNS enumeration could be trimmed slightly, but there is no filler and no 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?

No output schema exists, so the description carries the full return-shape burden and does so thoroughly (both page_type variants, field-by-field, plus observed_at/cached). Combined with latency, billing and marketplace coverage, an agent has everything needed to call it correctly and set expectations.

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% so the baseline is 3, but the description adds real semantics beyond the schema: the marketplace is derived from the URL host, the url/country pair must agree, and — most importantly — the tree-walking contract that subsequent calls should reuse URLs returned by a previous answer. It stops short of adding format syntax the schema lacks, so a 4 rather than a 5.

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?

States a specific verb+resource ('LIVE Amazon Best Sellers list for one category') with the exact payload (top 100 in rank order, breadcrumb name, subcategories) and the dual-mode behavior (category URL vs. root URL returns top-level categories). An agent can distinguish it from serp, product and shopping 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.

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

Explicit USE WHEN conditions (what sells best in a category right now, top-100 list, browsing best-seller categories) and explicit DON'T USE with named alternatives: keyword search -> serp, curated shortlist -> shopping, one ASIN -> product, rank history -> product with bsr_history. This is as close to a routing table as a description gets.

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

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

Beyond the annotations' read-only/idempotent safety profile, the description discloses paid-plan requirements, per-option credit costs, the data horizon caveat ('observed since' is not brand age), 404 behavior for unobserved brands, and marketplace scope. These are exactly the operational details an agent needs before invoking the tool.

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?

Despite being dense, the description is front-loaded: it defines the dossier, then states when to use it, then options, then scope, then honesty caveats, then cost. Every section earns its place for a tool with seven parameters, multiple optional expansions, usage-dependent costs, and no output 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?

With no output schema, the description carries the burden of explaining what is returned and does so thoroughly, including field families, optional expansions, pagination, marketplace coverage, data freshness caveats, and cost model. No material gap remains for correct invocation.

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 would be 3, but the description adds material meaning: sellers=true returns 25 per page and supports page=N; network=true returns a one-hop seller map with up to 50 weighted edges; history=true returns up to 24 calendar months with specific fields; and each option carries its own credit cost.

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 names a specific resource ('Amazon BRAND dossier') and enumerates its contents in detail, making clear this is brand-level buy-box intelligence rather than a generic product or seller lookup. It also distinguishes the data source ('Logimu's own buy-box observations, derived intelligence, not estimates'), which separates it from sibling tools that may surface estimates or different entities.

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 gives an explicit 'USE WHEN' list covering who sells a brand, how contested or Amazon-dominated it is, seller trends, and vetting for wholesale/arbitrage/brand protection. It does not name sibling alternatives or state when not to use this tool, so it stops short of the highest tier.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds substantial value beyond them: the credit cost model (1 credit, +0.5 with history, 0 for unknown id), which operations are free, the 11-marketplace scope, and the paid-plan requirement. This is exactly the kind of behavioral context annotations can't express.

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?

Long but dense and front-loaded: what it returns, then USE WHEN, then input modes, then cost. Nearly every clause carries information, though the enumeration of return fields is on the verbose side and could be tightened.

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?

There is no output schema, so the description must carry return semantics - and it does, listing the full set of profile fields, the sub-category/brand behavior for root vs non-root categories, and what history=true appends. Nothing an agent needs to call this correctly 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 coverage is 100% so per-parameter docs are already present, but the description adds cross-parameter semantics the schema alone doesn't convey: the OR relationship between category_id/node_id, q, and list=true, and that q returns candidates first (free) so the caller can pick an id. That mutual-exclusivity and sequencing is genuine added 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?

States a specific verb+resource ('Amazon CATEGORY landscape') and enumerates exactly what the profile contains: size, pricing/rating averages, Amazon retail share, FBA penetration, private-label share, HHI concentration, churn, demand signals, benchmarks, sub-categories and top brands. An agent can immediately tell this is a category-level analytics tool, distinct from product/brand/seller siblings.

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?

Explicit 'USE WHEN' clause names the triggers (how competitive / Amazon-dominated / FBA-heavy, how big, which brands lead, sizing a private-label or wholesale entry). It also documents the three invocation modes and when to choose each, plus the free vs paid conditions.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), but the description goes well beyond structured fields: it discloses that an empty list is a real answer, that an unapplied filter is refused as an error rather than billed, that unverified filters are served with a caveat, that there is no total count and no deal start time, and that list_price is Amazon's labeled reference price. It also states latency (10-30s per page, cache within 15 min) and per-page credit billing, including which outcomes are never billed.

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?

Front-loaded with the resource and the USE/DON'T USE routing, then organized into clear labeled sections (RETURNS, HONESTY, LATENCY, MARKETPLACES, COST) that make it skimmable despite its length. It is long and duplicates a little structured data (the marketplace list mirrors the country enum, page_size credit note restates the schema), but the RETURNS block is genuinely needed given no output schema exists.

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 16-parameter live-scraping tool with no output schema, the description supplies the full return shape (deals[], categories[], collections[], facets, selected_filters, filter_check, pagination, amazon, observed_at, cached), the honesty caveats, latency, marketplaces, and cost model. An agent has everything needed to call it correctly and interpret the result.

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, and the description mostly echoes the filter set already documented in the schema. It does add cross-call flow meaning the schema lacks: category_id, brand, and collection values are meant to be passed back from categories[]/facets.brands/collections[] of a previous answer, which clarifies how the chained filter call is meant to be constructed.

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?

States a specific verb and resource (read Amazon's live Today's Deals page for one marketplace) and names exactly which siblings it is not for (product/offer_history, offers, serp, shopping, bestsellers). An agent can separate this from every other sibling without opening a schema.

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?

Explicit USE WHEN block enumerates the triggering intents (what's on sale now, lightning deals in a department, deals above a discount/under a price, coupons, ending today) and an explicit DON'T USE block routes to the correct alternatives for price history, sellers, keyword search, and bestsellers. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds substantial context beyond them: paid-plan gating, 1 credit (+0.5 with history), the 2,000-call daily cap, the dated weekly-sample nature versus live results, and the free keyword_not_found behavior for out-of-set terms.

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?

It is front-loaded with the core purpose and the USE WHEN / NOT / COST routing appears in a sensible order. The cost/freshness detail is dense but every clause carries routing or behavioral information; the single unbroken paragraph is the only real structural weakness.

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 no-output-schema tool with a rich payload, the description enumerates what is returned (organic order, buy box, sponsored units, page_summary, entrants/leavers, history series), the cost model, the data-freshness caveat and the sibling alternatives. An agent has everything needed to call it 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%, so the baseline is 3, but the description adds real meaning: it explains that history=true returns every weekly observation plus rank series and carries a cost implication, and confirms country is US-only against the amazon.com map. The keyword parameter's semantics are left entirely to the schema example.

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 precise verb+resource: the observed page-1 organic order for a keyword, with product facts, buy box, sponsored units, Overall Pick, result count and page_summary. It is unmistakably distinguishable from siblings like serp, keywords and product_keywords, which it names directly.

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?

Explicit routing is provided: 'USE WHEN the user asks which products, brands or sellers hold page 1...' plus exclusions for volume figures, live pages, autocomplete suggestions and product-keyword mapping, each with the correct alternative tool (serp, keywords, product_keywords). Nothing is left to inference.

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

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

Annotations already cover read-only, non-destructive, idempotent behavior, but the description goes well beyond them: credit cost (1 per lookup, +0.5 with history), free unknown seeds, the derived daily cap, paid-plan gating, 11-marketplace since-Aug-2026 harvest scope, and the caveat that positions are only comparable within one list. It omits any note on pagination or rate-limit error behavior, keeping it short of a 5.

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 resource and output shape are front-loaded, and the dense packaging of scope, routing, and cost is mostly earned. It is long and concatenated into single sentences, which slightly taxes scanning, but there is little filler.

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 output schema, the description still fully characterizes the return payload (per-list positions, observation timestamps, marketplaces, related vocabulary), the compare matrix mode, the history mode, and the cost/limit model. An agent has everything needed to call it correctly and set expectations.

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%, so the baseline is 3, but the description adds real semantics beyond the schema: it explains what compare actually returns (the seed's primary list per marketplace plus a position matrix) and what history adds (every observation of each list as terms enter, leave, or move), which the terse schema descriptions do not convey.

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 opening states a specific verb+resource: Amazon autocomplete suggestion lists for a seed term, with precise output shape (one list per crawled prefix/department, position 1-10, first/last observed, marketplaces). It explicitly distinguishes itself from siblings keyword_rankings and product_keywords, so an agent can select it without opening any schema.

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 'USE WHEN' clause enumerates concrete triggers (what buyers type, backend keyword language, product-research seeds, country differences) and the 'NOT' clause names two exclusions with the correct alternative tool for each. This is explicit when/when-not/alternatives routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds non-obvious behavior: stopped trackings remain listed for 30 days, the operation costs 0 credits, and it is gated to paid plans only. Since there is no output schema, spelling out the returned fields (hot-lane pickup, lane last/next read, allowance totals) further enriches the behavioral picture.

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 uses clear caps-prefixed sections (USE WHEN, COST) and front-loads the core purpose, and every sentence carries information. The opening sentence is long and packs many return fields into one clause, which slightly hurts scannability.

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 read-only listing tool the description covers purpose, usage triggers, retention, cost, plan gating, and even the shape of returned data, so no output schema is needed. Everything an agent needs to select and call the tool correctly is present.

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 limit, offset, status, country, and events_for are all documented in the schema itself. The description adds no extra syntax or semantics for these parameters beyond what the schema provides, so the baseline 3 applies.

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 opens with a specific verb+resource ('LIST the products this API key tracks') and immediately distinguishes itself from the sibling track_product by framing it as the resource that track_product populates. It also enumerates the returned fields, so the agent knows exactly what the tool surfaces.

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 'USE WHEN' clause gives concrete triggers (what is being tracked, whether a tracking is live, allowance remaining) and routes the stop-one case to the sibling action (id goes to DELETE /v1/track/{id}), which is explicit when-to-use guidance and an alternative path.

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

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

Goes well beyond the annotations (which only cover read-only/idempotent safety): it discloses the paid-plan requirement, the exact cost model (1 credit per 25-row page, empty page free), and the daily per-key cap of 2,000 calls on the derived family. These are precisely the operational facts an agent needs before invoking.

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?

Long but front-loaded: the kind inventory leads, then usage guidance, then cost. The parenthetical ranking details are dense but each earns its place given the five-way kind switch. Minor density cost keeps it off a 5.

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 complex 8-parameter, 5-kind discovery tool with no output schema, the description covers purpose, per-kind semantics, usage routing, and full cost/limit context. An agent can select and invoke it correctly without further information.

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 75% and the description meaningfully extends it — it explains what each kind ranks by, which sort fields apply per kind, and the distinct behaviors of category_id (narrow top_brands) versus parent_id (children of top_categories). It adds value, though the sort field mapping is left as 'see description' rather than fully itemized.

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?

States a specific verb+resource ('Ranked LISTS from Logimu's observations, 25 per page') and enumerates all five kind values with what each ranks, so the agent knows exactly what data comes back. It clearly distinguishes itself from the sibling look-up tools (brand/seller/category), which retrieve a known entity rather than rank a set.

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?

'USE WHEN the user wants to DISCOVER brands, sellers or categories rather than look one up' gives an explicit when-to-use, with concrete scenarios (sourcing leads, brands under seller pressure, biggest resellers). It then routes the agent onward with 'Then drill in with the brand / seller / category tools,' naming alternatives and the follow-up path.

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

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

Annotations already cover readOnly/openWorld/idempotent/destructive, and the description goes well beyond them: latency in seconds, billing rules (0.5 credit, never billed on no-offers/failed fetch), API key requirement, supported marketplaces, and an HONESTY clause explaining that no_sellers is confirmed by a second independent fetch while failures surface as errors. This is rich behavioral context an agent could not get from 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?

Dense but well-structured with labeled sections (USE WHEN / DON'T USE / RETURNS / HONESTY / LATENCY / MARKETPLACES / COST) and front-loaded purpose. It is long, and some RETURNS field enumeration borders on restating schema-level detail, but nearly every sentence carries actionable information.

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 live-fetch tool with no output schema, the description fully documents the return shape (asin, price, buybox_seller, current_sellers fields, fulfillment, seller_ratings, gtin_resolution), plus cost, latency and failure semantics. An agent has everything needed to call it 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%, so the baseline is 3, but the description adds real meaning beyond the schema: zip is scoped to page 1 and country=us, gtin resolution order and barcode_verified semantics, and per-parameter billing nuances (include_used not billed extra, unresolved barcode never billed). Slightly redundant with the schema in places, hence not a 5.

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?

States a precise verb and resource ('LIVE Amazon offers page for one product: every seller offering it right now'), including scope (up to 10 pages, no product page fetched). It explicitly distinguishes itself from siblings product, shopping, serp, brand and seller, so an agent can route without opening any schema.

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?

Explicit USE WHEN list ('who sells a product right now', 'cheapest new or used offer', 'buy-box winner as of this minute') and an explicit DON'T USE list naming the sibling tools to use instead (product, shopping, serp, brand, seller). Nothing is left to inference.

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

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

Annotations only declare read/idempotent/open-world, so the description adds substantial behavioral context the annotations cannot: credit costs per lane (free 1/30 daily cache-only, 0.5 keyed, 1 live, 2 Walmart live, 0.05 for history_only), that misses and partial scrapes are never billed, that mode=live errors for keyless callers and must not be offered, that track=true pins the ASIN into the hot lane as a side effect, and freshness/null semantics (content_observed_at:null means not yet crawled, never 'no description'). The opt-in track=true side effect sits in mild tension with readOnlyHint=true, but the default invocation is a pure read and the side effect is disclosed explicitly rather than hidden, so this is not a contradiction of 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?

Purpose and routing are correctly front-loaded, but the body is an enormous single-paragraph monolith of deeply nested parentheses carrying changelog stamps ('since 2026-09-27', '2026-10-09', '2026-10-14') and field-by-field return documentation. Much of that granularity helps selection only marginally and crowds out the decision-relevant sentences; it is dense rather than redundant, but it is not appropriately sized.

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?

There is no output schema, so the description carries the full return-value burden across 12 marketplaces, three modes and multiple cost lanes — and it discharges that burden exhaustively (freshness stamps, locked blocks, null semantics, seller feedback, per-seller fulfillment fields). An agent has everything it needs to call this correctly and to interpret the answer.

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 already 100%, so the baseline is 3; the description earns above that by adding cross-parameter semantics the schema cannot express — how mode interacts with max_age_days, that history_only refuses mode=live, that bsr_history/offer_history are keyed-only but not extra-billed, and that offer_history changes the shape of per-seller rows.

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?

Opens with a precise verb+resource+scope: 'Full dossier for ONE known product: its current snapshot plus its observed history.' It immediately distinguishes itself from siblings by naming the differentiator ('This is the ONLY tool that returns history: shopping and search return current values').

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?

Contains an explicit USE WHEN clause enumerating triggers (specific ASIN / Walmart item ID / product link / product_id from shopping or search, and the exact user questions that map here) and a DON'T USE clause routing discovery to shopping and filtered lists to search. Also covers marketplace selection, cost-lane gating and mode selection.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), yet the description goes well beyond them: head-terms/page-1 coverage limits, weekly dated samples rather than live data, the free `asin_not_found` outcome, per-25-keyword credit pricing, the +0.5 history surcharge, paid-plan gating, and the derived daily cap. This is exactly the operational context an agent needs before calling a paid, sampled data tool.

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?

Front-loads the core purpose and then layers comparison, history, coverage caveats and cost in a single dense paragraph where each clause carries information. No sentence is wasted, but the density of parenthetical asides makes it slightly harder to scan than an ideally structured definition.

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 an 8-parameter, paid, sampled data tool with no output schema, the description still covers the return shape (per-keyword rows with badge/date and comparison columns), coverage limits, edge cases (asin_not_found) and cost. Nothing an agent needs to call it correctly 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 coverage is already 100%, so the baseline would be 3, but the description adds real semantic meaning: passing `asins` turns the call into a competitor comparison that adds organic rank, asins_on_page and gap per row, `gaps=true` filters to that gap set, `history=true` returns the first product's rank across observations, and `limit` is tied to credit burn. This is considerably more than the schema restates.

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?

Opens with a specific verb+resource ("REVERSE ASIN on Amazon US") and precisely defines the returned set: observed keywords whose latest page 1 shows the product, organic or sponsored, with rank, result count, badge and date. The scope statements ("head search terms and page 1 only", "NOT volume figures") separate it from a volume-oriented `keywords` tool and from a rank-tracking `keyword_rankings` tool.

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?

Gives an explicit USE WHEN clause covering three scenarios (which keywords a product ranks for, where competitors appear and the product does not, and rank movement over time), plus useful exclusions (not volume, not live). It does not name a specific sibling tool to prefer instead, which is the only thing separating it from a 5.

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

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 substantial behavioral context: return fields (product_id, product_url, etc.), ordering semantics, coverage limits ('not the entire Amazon catalog'), cost structure ('free lane 1 of 30 daily queries', '1 credit per 25 rows'), and a dated seller-feedback note about an extra seller_ratings array. 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 long but deliberately structured with labeled sections (COVERAGE, COST, SELLER FEEDBACK) and front-loaded purpose and usage. Every sentence adds value—even the seller-feedback note clarifies an evolving response shape. It is dense but appropriate for a tool with 20 parameters; a slightly shorter version might be possible, but nothing is fluff.

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 20-parameter tool with no output schema, the description is remarkably complete: it lists return fields, covers anchor semantics, marketplace selection, cost/limits, coverage scope, and even the optional seller_ratings array. An agent has everything needed to call it correctly, including the caution about empty result sets not being billed.

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%, so baseline is 3, but the description goes well beyond the schema: it explains that q is literal not semantic, category can act as anchor or refinement, seller_count_max is 'the core sourcing filter' for low competition, and rating_max is for weak-review incumbents. This adds decision-relevant meaning to parameters that the schema alone does not convey.

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 ('query') and a specific resource ('tracked-product warehouse'), and explicitly differentiates from siblings: 'DON'T USE for "best X" buying advice (use shopping, which ranks and groups), or for a single known product (use product).' It also gives concrete example queries, making the tool's purpose unmistakable.

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 provides explicit USE WHEN and DON'T USE conditions, names the alternative tools (shopping and product), and specifies an anchor requirement ('Requires an anchor: pass q, brand, or category'). This leaves no ambiguity about when to invoke this tool versus its siblings.

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

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

Annotations already mark this read-only/idempotent, and the description still adds substantial non-structured context: HTTP status semantics (404 = no page or never observed, 502 = collection failure to retry), the fact that an empty storefront does not confirm existence, caching/refresh cadence (~14 days), and a full per-operation credit model. Nothing here is derivable from 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?

Long, but front-loaded with purpose, USE WHEN, RETURNS, and modes before the cost block. Most sentences carry unique operational information; a few (mode/products_mode behavior) restate what the schema enums already say, which keeps it from a 5.

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?

No output schema exists, so the description carries the full return burden and does so explicitly: seller fields, feedback_summary periods, rating_histogram, recent_feedback contents and privacy limits, business block behavior per marketplace, and the products/history add-ons. An agent has everything needed to call and interpret results.

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 93%, so the schema already documents most parameters. The description still adds cross-parameter meaning the schema cannot: how mode=auto bills 'what was served', the live fetch timing (5-20s, up to ~30s), the cache page size of 25, and the +0.5/+1 surcharges for history/brands/network.

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?

Opens with a specific verb+resource: 'Amazon SELLER profile by seller id, optionally with the products the seller sells.' It also distinguishes itself from the sibling product tool by noting the seller id appears 'on any offer the product tool returns,' so an agent can route without opening either schema.

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?

Explicit 'USE WHEN the user asks about a third-party seller / merchant / storefront (who they are, how they are rated, what they sell)' plus a concrete LOOKUP rule (seller_id or name). Costs and modes are also tied to concrete situations.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds substantial context beyond them: ~8-13s typical latency up to ~90s with retries, live-only with no caching or mode parameter, API-key requirement, and per-page credit billing with the rule that blocked (502) and empty fetches are never billed. It also discloses result-field caveats (sponsored usually false, is_prime false means no icon, estimates vs counts).

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?

Front-loads the core purpose and is organized with clear USE/DON'T USE/RETURNS/HONESTY/LATENCY/COST headers, and nearly every sentence carries operational information. It is dense and lengthy, but the length is justified by the behavioral, cost and return-shape disclosures rather than padding.

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?

There is no output schema, so the description carries the return burden and does so fully by enumerating search_results field-by-field plus search_information, pagination, related_searches, refinements, ad_blocks/video_blocks and brand_stores, including their caveats. For a 9-parameter, live-fetch tool this is complete enough to invoke and interpret 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%, yet the description still adds meaning the schema lacks: walmart caps at 3 pages per call at 2 credits per page, category_id and refinements are Amazon-only, refinements round-trips a prior response's refinements[*].value, and number_of_results truncates the returned list. This is genuinely additive rather than a restatement.

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?

States a specific verb+resource ('LIVE Amazon search-results (SERP) fetch') and immediately distinguishes the tool from siblings by naming shopping, search and product as alternatives for other jobs. An agent can tell it apart from the curated tools without opening a schema.

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?

Contains explicit USE WHEN conditions (current ranking order, page-1 occupants, sponsored placements, refinements, or when curated tools found nothing) and explicit DON'T USE conditions naming the exact sibling for each alternative job (shopping, search, product). Nothing is left to inference.

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

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

Annotations already declare this is a non-destructive read-only tool, but the description adds substantial behavior beyond that: ranking uses observed marketplace signals with no affiliate bias, zero results are genuine non-matches, data_source is always returned, revealed-preference signals should be weighted for popularity questions, and interpreted_as/match_quality caveats may appear. It also discloses the free/keyed credit model, detail expansion contents, and that detail is ignored on the free lane.

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 definition is front-loaded with USE/DON'T USE/RETURNS and never buries the core routing logic. It is extremely dense and very long, but for a 13-parameter open-world discovery tool most of the content earns its place; the main cost is readability, not wasted material.

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?

There is no output schema, so the description carries the return-shape burden, and it does so thoroughly: grouped shortlist structure, product fields, product_id meaning per marketplace, data_source attribution, honesty signals, and detail=true expansion contents. For a complex, multi-marketplace, 13-parameter tool, an agent has enough to invoke it correctly and interpret the response.

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%, so the baseline would be 3, but the description goes well beyond structured fields by explaining literal keyword mechanics, why extra query terms narrow results, how to handle sizes/colors versus storage capacity, how to construct model strings, how marketplace language affects query phrasing, and why brand belongs in the brand parameter rather than q. It also clarifies the practical cost difference between basic and detail=true responses and what detail attaches.

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 and resource: curated product discovery that turns a keyword into a ranked, grouped shortlist. It explicitly distinguishes itself from the sibling tools product and search, including the exact conditions that should route the agent elsewhere. An agent can identify what this tool is and is not without opening any schema.

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 gives explicit USE WHEN triggers such as 'best X', 'find me a Y under $Z', and 'what should I buy', and explicit DON'T USE conditions for ASIN-identified items and filtered datasets. It names the alternatives (product, search), includes worked examples, and even specifies the handoff when price-history analysis follows a shopping result.

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

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

Annotations only declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false; the description adds cost (0 credits), plan allowance tiers and exhaustion behavior with upgrade link, granted_interval fallback, ~10 minute pending window, stop semantics and the 30-day stopped row retention, paid-plans-only gating, and supported marketplaces. Nothing here contradicts the idempotent/destructive 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?

Front-loaded with the core verb and organized under clear capitalized signposts (USE WHEN, DON'T USE, COST, RETURNS, BULK, STOCK STATES), so an agent can scan to the needed block. It is however very long, and the interval cost table, ttl_days lapse behavior, notify_if semantics and bulk rules are largely restated from the input schema rather than adding new information.

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?

No output schema exists, and the description compensates with an explicit RETURNS field list (id, asin, status, interval, granted_interval, snapshots_per_day, expires_at, in_lane, pending, allowance, etc.) plus the stock-state vocabulary. Combined with cost, plan gating, marketplace scope and alert semantics, an agent has everything needed to call this 12-parameter, multi-mode tool 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 description coverage is 100%, so the baseline is 3 and the schema already carries per-parameter detail. The description still adds cross-parameter meaning the schema does not: the allowance cost model tied to interval (Solo 2,500/day = 416 products at 4h), the interaction of action=stop with id/asin+country/ids/asins, and action=sync's dry_run-first workflow.

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?

States a specific verb and resource ('TRACK a product: pin an Amazon ASIN into our hot lane') plus the resulting mechanism (all-offers page re-read on an interval, snapshots landing in the product's history). It explicitly distinguishes itself from siblings by naming 'product' and 'offers' as the read tools it is not, and 'list_tracked' as the id source.

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?

Gives an explicit USE WHEN list (repricing, MAP/buy-box monitoring, competitor listings, launches, deals) and an explicit DON'T USE ('to read data (product, offers): tracking only schedules the reads'). It also names the alternative cadence ('more often than our normal cadence') and the idempotent re-post behavior.

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