Logimu

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?

Goes well past the annotations (destructiveHint=true, readOnlyHint=false) by disclosing billing behavior ('failed, not-found and duplicate rows are never billed'), that estimate is free while create/run bill, that runs serialize per marketplace, that an API key is required, and that webhooks are HMAC-SHA256 signed with a one-time secret. This is unusually rich for a mutation 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?

The core purpose and the action list are front-loaded, and given 8 actions and 29 params most sentences earn their place. It is nonetheless a dense single block with heavy parenthetical nesting, making it harder to scan than a bulleted breakdown would be.

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 covers returns (result rows, jsonl_url/csv_url downloads, status line stats, queue position), auth requirements, and cost semantics. An agent has everything needed to choose an action and predict the outcome.

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 90%, so the schema carries most of the burden, but the description adds real meaning: it maps each action= value to its effect, explains source=tracked ('the ASINs this key tracks'), and calls out costs like the 0.05/row history_only case. It does not fully disambiguate every optional param, so it stays just above baseline.

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 with scope: 'run any Logimu endpoint over a whole list in one job' and pins it to the REST /v1/batches API. An agent can immediately distinguish this bulk runner from the single-item siblings (product, search, seller).

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 has more than a handful of ASINs... wants a daily/weekly refresh, or wants a CSV' gives a concrete threshold that implicitly separates it from single-item calls. However, it never names a sibling tool as the alternative for the under-threshold case, so routing is inferred rather than stated.

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 already cover read-only/idempotent safety, but the description adds substantial context beyond them: paid-plan gating, 1 credit per lookup, +0.5 with history, free for unknown seeds, and the daily cap of 2,000 calls. It also discloses the output shape (up to 6 lists, positions 1-10, first/last observed, marketplaces).

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 usage triggers, exclusions, and cost in a logical order; nearly every clause carries distinct information. It is dense and long, but the density is justified by the tool's complexity 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?

For a four-parameter tool with no output schema, the description covers return structure, cost model, limits, and country comparability. 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 coverage is 100%, so the schema already defines the parameters, but the description adds real meaning: history returns every observation since the harvest began, and compare returns each marketplace's primary list plus a position matrix. The comparability caution ('positions are comparable only within one list') is meaningful semantics the schema lacks.

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: it returns Amazon's own autocomplete suggestion lists for a seed term from a continuous harvest. It clearly distinguishes itself from siblings like shopping and search by declaring what it is not (volume figures, product-ranking map).

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' triggers (what buyers type, backend keyword language, product research seeds, country differences) and explicit routing away ('for products pass a term to the shopping tool'). When-not conditions are also given (not volume, not product rankings).

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?

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses the paywall boundary (free lane is cache-only, full history needs a key from $19/mo), exact credit costs (0.5 cache, 1 live, 0.05 history_only), rate limits (1 of 30 daily queries), billing behavior (misses never billed), the side effect of track=true (pins the ASIN into the hot lane), and freshness semantics for content_observed_at. This is unusually rich behavioral disclosure.

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 usage are correctly front-loaded, but the body is an enormous single flowing paragraph bloated with changelog-style version stamps ('Since 2026-09-27', '2026-10-09', '2026-10-14', '2026-09-30') and field-by-field return enumeration that an agent does not need to select or invoke the tool. Many sentences do not earn their place in a selection aid.

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 13-parameter tool with no output schema and a broad marketplace scope, the description is exhaustive: it enumerates return blocks, distinguishes Amazon vs Walmart behavior, states the marketplace enum, covers keyed vs free-lane variants, and explains null semantics (content_observed_at:null, bought_past_month_history null). Nothing needed 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_description_coverage is 100%, so the schema already documents all 13 parameters thoroughly (enums, defaults, USE WHEN notes on gtin/history_only). The description restates much of the same (offer_history, history_only, track, mode, country) without adding much syntax or format detail beyond the schema, so the baseline of 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?

Opens with 'Full dossier for ONE known product: its current snapshot plus its observed history', a precise verb+resource+scope. It explicitly distinguishes itself from siblings: 'This is the ONLY tool that returns history: shopping and search return current values.' An agent can tell immediately what it does and how it differs.

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 of triggering questions and identifier types, names the exact alternatives for the excluded cases ('DON'T USE to discover products from a keyword (use shopping) or to pull a filtered list (use search)'), and adds a routing rule for historical questions. When/when-not/alternatives are all present.

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?

Goes well beyond annotations with latency expectations, Amazon's own quirks (sponsored usually false, is_prime semantics, estimates vs counts, ad-redirector links), marketplace list, API key requirement, and billing rules. This is rich context structured fields cannot carry.

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 and usage well, but the RETURNS/HONESTY blocks are dense run-on sentences that hurt scanability despite every claim being substantive.

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?

Complete for a live-fetch tool: covers when to use, latency, cost, marketplace support, return shape, and Amazon-specific caveats. An agent can call it correctly without further context.

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; description adds genuine meaning by clarifying round-trip refinements, that sponsored exclusion is often a no-op, and that max_page can stop early when Amazon runs out.

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 ('LIVE Amazon search-results (SERP) fetch') and distinguishes from siblings by naming shopping, search, and product as different tools with different jobs.

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 (current ranking order, sponsored placements, fallback when curated tools found nothing) and explicit DON'T USE for three named alternatives with reasons.

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 the safe read-only, idempotent, non-destructive profile, yet the description adds substantial undisclosed behavior: ~100ms latency, no affiliate/sponsored bias, zero-results semantics, the data_source attribution requirement, interpreted_as and match_quality caveats, and a detailed credit/free-lane cost model. Its only shortfall is not covering pagination or result-count edges beyond the limit parameter.

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 correctly with purpose and routing first, then return shape, then query mechanics and cost. However it runs very long and duplicates the literal-keyword/query-style guidance that already appears in the q parameter description, so some sentences do not fully earn their 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?

There is no output schema, so the description carries the full burden of describing returns, and it does: product_id with per-marketplace meaning, product_url, title, price currency, rating, review count, stock, observed_at, brand facets, plus the match_quality/interpreted_as signals and grouping behavior. For a 13-param multi-marketplace tool this is complete enough to call blind.

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, but the description adds real meaning beyond the schema: the literal keyword-matching rule with the accessory trap explanation ('55 inch tv' returns TV stands), the storage-capacity exception, capitalization/language rules per marketplace, and the brand-token collision example. These are operational semantics the schema fields do 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+resource+scope ('Curated product discovery: a shopping keyword in, a ranked and grouped shortlist out') and immediately distinguishes itself from both siblings: product for ASIN-identified lookups, search for filtered datasets rather than recommendations. An agent can route correctly 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 / DON'T USE WHEN blocks naming the exact alternatives ('use product' for a known ASIN, 'use search' for a filtered dataset), plus trigger phrases ('best X', 'find me a Y under $Z'). Handoff rules are spelled out with concrete examples, including the detail=true vs product decision boundary.

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.