Logimu

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds material facts beyond them: the call is free and never billed, an API key is required, and results are reported as daily snapshots with total/used/remaining. It does not discuss caching or freshness beyond the 30-day window, so it stops just 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?

Four compact segments — identity/contents, usage triggers, cost, auth requirement — each front-loaded and earning its place. No filler verbs or restatement of the tool name.

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 returns, and it does so (balance, plan, per-endpoint usage, daily snapshot totals). Combined with cost and auth notes, an agent has everything needed to call it 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?

This tool takes zero parameters, so per the rubric the baseline is 4; there are no arguments whose meaning the description could clarify. The description correctly avoids inventing parameter details.

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 resource (the account) and enumerates exactly what it returns: balance, plan, 30-day usage by endpoint, and product-tracking allowance, plus a REST equivalence (GET /v1/account). No sibling tool covers account-level data, and the naming of the returned fields makes it 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?

The 'USE WHEN' clause gives four concrete trigger questions (credits left, job cost, key usage, tracking room), which is exactly the intent-to-tool mapping an agent needs. It also states the precondition/negative case: 'API key required (keyed lanes); without one, nothing to report.'

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 (destructiveHint=true, readOnlyHint=false), the description discloses cost behavior that annotations cannot: which actions are free, that create/run queue billable rows, that failed/not-found/duplicate rows are never billed, that the estimate is the ceiling, and that runs are serialized per marketplace. It also flags the API-key requirement. It stops short of saying whether action=delete also discards stored results — a real gap for a destructive 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-loaded with the core purpose, and each semicolon-delimited clause carries unique information (action semantics, kinds, billing, cost). It is dense to the point of being a wall of text for a 31-parameter tool, but almost nothing is redundant.

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 31-parameter multi-action tool with no output schema, the description covers action selection, kinds, cost, scheduling semantics, and pagination well enough to call correctly. Remaining gaps are the three undocumented numeric tuning parameters and any indication of the shape of status/results payloads beyond the mentions of rows/credits/queue position and download URLs.

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 baseline is 3; the description still adds value by defining each action's semantics (estimate vs create vs run vs status vs results) and by explaining that endpoint kinds take the endpoint's own query parameters in params. It also pins concrete meaning onto source=tracked with include [history_only] and its 0.05/row cost. It does not cover max_age_days, history_points, or history_sellers, which carry no schema descriptions at all.

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 sentence names a specific verb and resource ('run any Logimu endpoint over a whole list in one job') and immediately scopes it as the batch counterpart to REST /v1/batches. Every action is enumerated with its own one-clause meaning, so an agent can distinguish this from single-item siblings like product or search 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?

The 'USE WHEN' clause gives an explicit trigger threshold ('more than a handful of ASINs, barcodes, search terms, seller ids, brands or seeds'), plus scheduled refresh and CSV output as alternate triggers, which implicitly routes single-item requests to the non-batch siblings. Kind selection is also spelled out per data type, leaving little to inference.

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

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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description is not the sole source of that information. The description does add substantial operational context: filter refusal vs. verified application (filter_check), that empty results are legitimate answers, absence of a total count and deal start time, and the 15-minute cache window. However, it omits some details that would help an agent plan calls, such as whether `pages` pagination interacts with `page` in a specific order beyond 'starting at page', and what 'partial' in pagination means. A 3 reflects solid but not exhaustive 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?

Front-loaded with purpose and scope, then USE WHEN, DON'T USE, RETURNS, HONESTY, LATENCY, MARKETPLACES, COST. Every section serves a distinct invocation concern. Although long, the length is justified by 16 parameters, no output schema, and the need to document side effects and cost. It avoids gratuitous repetition, though the credit rule is stated twice (in COST and in `page_size`).

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 return-value burden. It enumerates the full shape of `deals[]`, `categories[]`, `collections[]`, `facets`, `selected_filters`, `filter_check`, `pagination`, `amazon`, `observed_at` and `cached`. It also discloses the critical honesty constraints (empty list is real, unapplied filter is refused and unbilled, unverified filters are served) that an agent needs to interpret results safely.

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?

With 100% schema description coverage, baseline is 3. The description adds meaning beyond the schema: it explains that `deal_types` values are 'stable deal collections', that `category_id` values come from `categories[]` of a prior answer, that `collection` ids vary by marketplace, and that `page_size=120` maximizes deals per credit. These are practical semantics that help an agent choose values correctly, though some overlap with schema text.

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 ('LIVE Amazon Today's Deals ... the deals page of one marketplace') and immediately enumerates the filter surface (department, deal collection, discount, price, Prime, rating, brand). An agent can distinguish this from `offers`, `product`, `serp`, `shopping` and `bestsellers` without opening anything else.

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 concrete user intents (today's deals, lightning deals in a department, coupons, deals ending today), and the DON'T USE block names four sibling tools and the exact scenario that routes to each. Both the positive and negative routing conditions are 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: a weekly dated sample rather than live data, minute-to-minute variance of a few products, JavaScript-loaded sponsored units counted as slots only, geographic/locale scope, paid-plan requirement, 1 credit (+0.5 with history), and the derived daily cap.

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?

Content is front-loaded and nearly every clause carries information — scope, cadence, exclusions, cost. The structure is weakened by a very long run-on sentence with heavy parenthetical nesting, which makes the return-payload list harder to scan than it needs to 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 carries the full burden of describing return values and does so in detail (page contents, page_summary breakdowns, change tracking, history mode). It also covers coverage caveats for the nine newer marketplaces and the cost/cap model, leaving nothing an agent needs before calling.

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 keyword (case-insensitive, with example), country (11 marketplaces with per-market reading cadence), and history (weekly observations plus rank series, +0.5 credit). The description largely restates these, adding only the aggregate 'all 11 marketplaces' framing and the cost implication, 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?

States a specific verb and resource — page 1 of Amazon search for a keyword as last observed — and enumerates exactly what is returned (organic order with product facts, buy box, sponsored units, Overall Pick, result count, page_summary, entrants/leavers). It explicitly distinguishes itself from serp, keywords, and product_keywords, so an agent can route correctly 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?

Provides an explicit 'USE WHEN' trigger (which products/brands/sellers hold page 1, who advertises, how the page changed) and explicit exclusions with named alternatives: serp for a live page, keywords for Amazon suggestions, product_keywords for a product's ranking terms. It also states volume figures are not available and that unobserved keywords are free (keyword_not_found).

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, and the description adds substantial context beyond them: paid-plan gating, credit cost per lookup and history surcharge, free unknown seed, and the derived daily cap. It also discloses a key analysis constraint ('positions are comparable only within one list'), which is not in any structured field.

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 output shape, and each sentence carries information (mode behavior, use cases, exclusions, pricing). It is a single dense paragraph that runs long, but no sentence is 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 fully specifies the return shape for both modes, plus cost model, rate limit, and interpretation caveat. An agent has everything needed to call it correctly and to set user 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 genuine semantics: history=true means every observation of each list (entering, leaving, moving position), and compare returns a primary list plus a position matrix per marketplace. It stops short of explaining the country-vs-compare precedence, which the schema itself covers.

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's OWN autocomplete suggestion lists for a seed term') with the exact output shape (up to 6 lists, position 1-10, first/last observed, marketplaces, related vocabulary). Explicitly distinguishes itself from siblings by naming keyword_rankings and product_keywords as the tools for adjacent questions.

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?

Provides an explicit 'USE WHEN' clause (buyer language, backend keywords, product research seeds, per-country differences) and 'NOT' exclusions (not volume figures, not a product-ranking map) with the correct alternative named for each exclusion.

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 a safe read (readOnlyHint, idempotentHint, non-destructive), and the description goes further with cost (0 credits), plan gating (paid plans only), and the 30-day retention of stopped trackings. Those are non-obvious operational facts an agent cannot get from structured fields.

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 verb and scope, and every clause carries information (returned fields, triggers, retention, cost, plan restriction). It is a single dense run-on block with capitalized emphasis rather than cleanly separated sections, which slightly hurts scanability.

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 6 optional parameters, no output schema, and a dual-mode events_for parameter, the description supplies the return shape, the retention window, the cost, and the follow-up delete path. An agent has everything needed to call it correctly and to 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%, including the mode-switching events_for parameter and both enums, so the schema carries parameter meaning. The description adds no filter syntax or usage nuance beyond listing returned fields, which is the expected baseline-3 case.

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?

Specific verb (LIST) plus resource (the products this API key tracks), and it names the paired sibling track_product so the agent can distinguish creation from enumeration. It also enumerates the returned fields, which matters because there is no output 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' triggers cover the main intents: what is tracked, whether a tracking is live, remaining allowance, and stopping one (with the DELETE /v1/track/{id} handoff). It lacks an explicit 'use X instead when...' routing against other list-ish siblings, so it falls short of 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 cover read-only/idempotent/non-destructive, and the description adds what they cannot: paid-plan gating, 1 credit per page of 25 rows, empty pages free, a 2,000-call daily cap on the derived family, and that all 11 Amazon marketplaces are covered. This is exactly the kind of cost/quota context that prevents surprise failures.

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?

Every sentence carries information and the key constraint (kinds) is front-loaded, but the whole definition is one dense run-on paragraph mixing kind enumeration, usage, cost and marketplace coverage. A short bulleted split would scan faster at this length.

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, 5-mode discovery tool with no output schema, the agent gets modes, ranking semantics, pagination size, marketplace scope, cost model and next-step tools. 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?

Goes well beyond the schema by mapping ranking fields to each kind (e.g. top_brands by buy-box days / sellers / control_score / asins / revenue / amazon_share, top_sellers by brands / buybox_days / asins / revenue) and by explaining window, direction, parent_id and category_id in context. It stops short of giving the literal accepted `sort` string values per kind, leaving the agent to translate prose field names into enum-like values.

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) and then enumerates all five kinds with exactly what each ranks. It is unambiguously distinct from the lookup-oriented siblings (brand, seller, category) which it explicitly contrasts against.

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 when-to-use rule ('USE WHEN the user wants to DISCOVER brands, sellers or categories rather than look one up'), lists concrete triggers (sourcing leads, brands under seller pressure, biggest resellers, hot categories), and names the follow-up tools for drilling in.

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 (readOnly, openWorld, idempotent, non-destructive), the description discloses that no product page is fetched, up to 10 offers pages are walked, latency is typically 4-12 seconds, an API key is required, and billing rules are stated precisely. It also explains the honesty guarantee around no_sellers and complete=false partial results, which is exactly the kind of behavioral context an agent needs.

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 front-loaded with purpose, then USE WHEN/DON'T USE, then returns and operational caveats. It is long and dense, but most of the length is justified by the absence of an output schema and the need to explain completeness, latency, markets and billing.

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 five parameters and no output schema, the description is complete: it enumerates the return fields, explains partial results and no-offer honesty, lists supported marketplaces, states latency, and covers billing and API-key requirements. Nothing critical is left for the agent to infer.

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%, and the schema already documents asin, gtin, zip, country and include_used in detail. The description reinforces a few points such as gtin_resolution and the ZIP session behavior, but it does not add substantial meaning beyond the already-rich schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it returns the live Amazon offers page for one product, every seller offering it right now, read from the 'All offers' view at request time. It explicitly distinguishes this from product, brand, seller, shopping and serp tools, so an agent can select it 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?

It provides explicit USE WHEN conditions: who sells a product right now, every current offer, cheapest new/used offer, buy-box winner, or a fresh seller list before buying, sourcing or repricing. It also gives explicit DON'T USE guidance pointing to product, shopping, serp, brand and seller for adjacent needs.

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 readOnlyHint/idempotent annotations: it discloses credit costs per mode (0.5 cache, 1 live, 2 Walmart live, 0.05 history_only), "misses and partial scrapes are never billed," typical Walmart live latency of 8-15s, paid-plan auth requirements, and the null-vs-empty semantics of content_observed_at. The main deduction is that these critical operational facts are buried mid-paragraph rather than surfaced, so an agent may miss them. Minor tension worth noting but not a contradiction: track=true creates a 30-day lane pin, a side effect the readOnlyHint annotation does not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One enormous run-on paragraph mixing purpose, return-field inventory, and changelog entries dated 2026-09-18 through 2026-11-05. The dated "since ..." clauses and exhaustive field enumerations (buybox_condition_detail, bsr_leaf_category, percent_by_stars...) are documentation noise that buries the front-loaded usage rules. Purpose and routing are front-loaded, which saves it from a 1.

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 14 parameters, no output schema, and a very large return payload, the description does supply return-value semantics that would otherwise be unknown, including freshness stamps, null meanings, and marketplace attribution. It is complete in coverage, though its bulk and disorganization make it harder to use than a structured breakdown would be.

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; the description still adds value by tying parameters to outcomes, e.g. mode=live meaning a paid on-demand scrape with 2 credits on Walmart, history_only returning only history series for 0.05 credit, and track=true duplicating the track_product tool behavior. It explains interactions between parameters (read with track, history_points with offer_history) that the schema alone only implies.

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 sentence gives a specific verb and resource with scope: "Full dossier for ONE known product: its current snapshot plus its observed history." It then explicitly separates itself from siblings by stating "This is the ONLY tool that returns history: shopping and search return current values." An agent can identify the tool's role and its unique value without reading 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?

Provides explicit when-to-use triggers ("user has a specific ASIN, Walmart item ID, product link, or a product_id... and asks about price history... 'is this a good buy'") and explicit when-not-to-use rules ("DON'T USE to discover products from a keyword (use shopping) or to pull a filtered list (use search)"), naming the alternatives. Input prerequisites (ASIN vs. Walmart item ID vs. gtin) and cost/auth conditions are also 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 read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond that: weekly sampling cadence, page-1-only coverage, the free asin_not_found outcome, credit pricing (1 per 25 keywords per ASIN, +0.5 with history), and the daily cap. Missing is any statement about pagination limits or the shape/ordering of the returned totals, though ordering is partly described.

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 definition and then layered with USE WHEN, coverage caveats, and COST, so an agent can stop reading early. The single dense paragraph is long and parenthetical-heavy, which slows scanning, but nearly every clause carries decision-relevant 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 an 8-parameter, no-output-schema tool this is unusually complete: it covers scope limits, cost accounting, paid-plan gating, a free failure case, ordering, and the comparison/history modifiers. An agent has everything needed to decide whether to call it and what the results mean.

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; the description earns more by explaining the comparison semantics behind asins ("the product first", competitor organic rank, asins_on_page, gap) and the exact effect of gaps=true and history=true. The country coverage caveat (us/uk weekly vs. nine markets filling in) also adds meaning the enum 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?

"REVERSE ASIN on Amazon (11 marketplaces, country): every observed keyword ... whose latest page 1 shows the product" gives a specific verb-equivalent, resource, and scope. It distinguishes itself from sibling keyword tools by defining the reverse-lookup direction and by noting the organic-vs-sponsored distinction and result ordering.

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" block names three concrete user intents (which keywords a product ranks for, where competitors appear and it does not, how a position moved), and the "NOT volume figures and NOT live" exclusions plus the "COST: paid plan required" prerequisite prevent the main misuses. Alternative routing is implicit via the cost/coverage framing rather than named siblings, but the when/when-not coverage is explicit.

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 establish read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond that: paid-plan requirement, credit cost per 25 rows, no billing for empty results, marketplace coverage limits, anchor requirement, and the separate seller_ratings array. These details materially help an agent decide whether and how to invoke 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?

The description is dense but justified for a 20-parameter tool, and it front-loads purpose, use cases, and exclusions. The seller-feedback changelog note and repeated cost/coverage details add some length, but overall the structure is clear and mostly earns its space.

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 search tool with no output schema, the description explains the returned row shape, product_id meaning, seller_ratings behavior, marketplace coverage, billing rules, and anchor requirement. An agent has enough context to invoke it correctly without needing undocumented assumptions.

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%, and the schema itself documents all 20 parameters in detail, including anyOf anchor constraints, enums, defaults, and ranges. The description reinforces the anchor rule and gives example filter combinations, but adds little parameter meaning beyond the schema, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: 'Filtered query over the tracked-product warehouse (24M+ Amazon and Walmart products).' It clearly distinguishes the tool from siblings by naming shopping for buying advice and product for a single known product.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It explicitly states when to use the tool with concrete example queries and when not to use it, naming the better alternatives: shopping for 'best X' advice and product for a single known item. It also states the anchor requirement and points to product for full item history.

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?

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

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded and structured with USE WHEN, DON'T USE, RETURNS, HONESTY, LATENCY, COST, and ZIP sections, so an agent can navigate it. However, it is very long and repeats some latency and billing details, which keeps it from being maximally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

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

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

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

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

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

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

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

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

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

Annotations only cover read-only/idempotent/non-destructive safety, and the description adds genuinely new behavior: ~100ms latency, no affiliate or sponsored bias in ranking, zero-results semantics ('phrasing rejected, not absence'), interpreted_as and match_quality caveats the agent must relay, data_source attribution, and the full credit/billing model. It also enumerates what detail=true attaches, which is not derivable from the schema.

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 — purpose, use/don't-use, and returns come first — but the body runs very long, with ALL-CAPS section headers packed into a single block and irrelevant versioning parentheticals ('2026-09-28', 'from 2026-11-05') that clutter the detail=true enumeration. The language/query-style material is useful but could be tightened considerably without losing signal.

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, no-output-schema discovery tool with many sibling alternatives, this covers everything an agent needs: routing, query construction rules per marketplace/language, cost implications, result-grouping behavior, and how to handle empty or low-confidence responses. 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema for q (literal keyword matching, every term narrows, omit sizes/colours, storage capacity exception, use the maker's own model string, query in marketplace language) and for detail (cost delta, what it attaches). These are non-obvious usage semantics that the property descriptions only partially encode.

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+output framing ('a shopping keyword in, a ranked and grouped shortlist out') and immediately distinguishes itself from the two nearest siblings by name (product for ASIN-identified items, search for filtered datasets). The response contents (grouping, product_id, price, rating, facets) are spelled out so an agent knows exactly what it gets back.

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 are quoted as user phrasings ('best X', 'find me a Y under $Z'), and DON'T USE clauses name the alternative tool plus the condition that selects it. It also handles the follow-up routing case ('analyse the first one' -> product with that row's product_id) and the detail=true vs product() split for historical analysis.

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 and idempotentHint=true; the description adds the real behavioral profile: a plan-based snapshot allowance rather than credits, granted_interval fallback when only a coarser interval fits, pending ~10 minutes in the lane, plan-lapse retention of 7 days then pause, stop semantics (allowance released, row listed 30 days as stopped), sync making the active set equal to a list, and per-day email caps. Nothing contradicts 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?

Front-loaded with the verb and the mechanism, and nearly every sentence carries operational detail. It is very dense and somewhat sprawling (STSATE abbreviations, dated changelog markers, marketplace list repeated from the schema), so it reads longer than strictly necessary.

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, nested, enum-heavy, no-output-schema mutation tool, the description covers cost, plan limits, return fields, bulk/sync, stop semantics, stock-state definitions and supported marketplaces. Nothing an agent needs to invoke 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 100% and the schema descriptions are already extremely detailed (read's 2-snapshot cost, interval-to-snapshot mapping, notify_if semantics), so the description can only add framing. It does add useful cross-parameter meaning — read interacts with interval and with idempotent re-track resetting read to offers — but much of the parameter exposition overlaps the schema rather than extending it.

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?

A specific verb (TRACK) plus resource (Amazon ASIN in the hot lane) and the mechanism (re-read all-offers page at an interval, history into buybox_price_points_hot). It explicitly contrasts with the sibling `product` tool for reading data, so an agent can distinguish scheduling from fetching.

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 list (repricing, MAP/buy-box monitoring, launch, deal, book rank) and a DON'T USE clause pointing at product/offers for reads. Also says re-posting the same ASIN renews it, which resolves an ambiguity an agent would otherwise hit.

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