Nova Amazon MCP Server

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

Annotations only declare readOnlyHint=false, so the description carries the full burden and does: the TWO-STEP preview/commit contract, the confirmationToken returned by the preview, the requirement to show the preview to the user before writing, and the auth constraint ("a workspace API token cannot write", OAuth required). It also discloses what the preview resolves (account, marketplaces, ASINs against the catalog) and that mistyped ASINs surface there.

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 granularity, then the two-step flow, then the type vocabulary — a sensible order for a dense tool. It is long, and the sentence enumerating `type` values duplicates the schema enum descriptions nearly verbatim, which is the one passage that does not earn 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?

No output schema exists, and the description compensates by describing what the preview returns (resolved account/marketplaces/ASINs plus a confirmationToken) and what the commit call requires. For a mutating, two-phase tool with auth constraints, an agent has everything needed to call it correctly and 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?

Schema coverage is 100%, so baseline is 3; the description adds genuine semantics the schema does not, namely the grouping rule for the `events` array (one call, multiple entries, max 50) and the purpose of the two-step commit/confirmationToken pair. The per-`type` vocabulary is largely a restatement of the enum descriptions in the schema, which keeps it from 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 and resource ("Log one or several EVENTS on Nova") and immediately grounds it with a concrete metaphor ("dated notes drawn on the charts so a later movement can be explained") plus four real-world examples. An agent can distinguish this from list_events or explain_movement 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 routing: "Check list_events first when the seller may already have logged it" names the sibling and the condition. It also prescribes the trigger ("the seller tells you what they did") and the granularity rule (same change across many ASINs = one event; different day/type/description = separate entries), which is exactly the decision an agent would otherwise get wrong.

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=true, so the description carries the real informational load — and it does, spelling out the exact definitional facets returned and the two conditional facets (1P `basis`, S&S `readingNote` including period reading and finality of a day). It does not cover behavior on an unknown or ambiguous key, which is the remaining gap.

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?

A single sentence, front-loaded with the verb and resource, followed by a parenthetical that lists return facets — every clause earns its place and nothing is repeated from the schema or annotations.

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 must convey the return shape, and it does so precisely for a two-parameter read tool whose inputs are fully specified in schema. Only the failure/ambiguity path for `key` is left unaddressed.

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 both parameters are thoroughly documented in the schema, including that `key` comes from list_metrics and that `reason` must be English and is user-visible. The description adds no parameter meaning beyond that, 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 gives a specific verb+resource ("Get the full definition of a single metric") and enumerates what that definition contains: meaning, unit, valid grains, 1P `basis`, and Subscribe & Save `readingNote`. It is clearly distinguishable from list_metrics by the word "single," though it never names the sibling explicitly.

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?

Usage is only implied — an agent infers it should call this when it needs to understand what a metric means or how it reads. There is no explicit when-to-use, no exclusion, and no reference to list_metrics as the source of keys (that routing only lives in the schema's `key` description).

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?

The description adds substantial behavioral context beyond the readOnlyHint annotation: it explains the returned signal structure, currency handling and notice relaying, channel-specific metric basis, null-vs-zero behavior for unserved metrics, and the response fields channel and channelNote. There is no contradiction with the read-only annotation. This is unusually transparent for a read-only analytical 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 front-loaded with purpose and return behavior, then structured into currency and channel sections. However, it is very long and repeats a great deal of parameter-schema detail, with dense vendor/channel exposition that could be tighter. The complexity justifies some length, but the description is not 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, nine parameters, read-only annotation, and no output schema, the description is complete enough for an agent to call it correctly. It explains what is returned, how currency and channel affect results, what null metrics mean, and how channel notes should be interpreted. No critical invocation or interpretation detail appears to be missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds useful operational meaning, especially around currency pinning, channel selection, and why 3P and 1P figures must not be manually combined. It largely reinforces schema text but adds enough policy-level guidance to exceed 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?

The description states a specific verb and resource: pulling a causal signal bundle for one SKU across a period vs a baseline in order to explain why sales moved. It also lists the signal families included and what is returned. It does not explicitly name sibling tools such as find_movers or query_metrics, so sibling differentiation is implicit rather than sharp.

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

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

The description makes the analytical use case clear: use it to reason about why a SKU's sales moved by comparing a period with a baseline. It also gives conditional channel guidance, including when to pass channels=['VENDOR'] and when to request All channels. However, it never explicitly compares this tool with sibling alternatives such as find_movers or query_metrics, and it gives no when-not-to-use-this-tool guidance.

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?

readOnlyHint=true already covers the safety profile, yet the description still discloses return-side behavior that annotations cannot: notRanked and subscribeAndSaveNotice on Amazon S&S ranking, currencyBasis and a currencyNotice that must be relayed, channelNote and unservedMetrics coming back null rather than 0, and vendorTopLineNetReceived switching what units/sales/netSales mean. This is exactly the kind of operational context the schema does not 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?

The purpose sentence is correctly front-loaded and the emoji section headers help navigation, but the body runs to many hundreds of words, with the entire 3P/1P P&L taxonomy, net-received-vs-invoiced mechanics and vendor shelf metrics expanded in full inside a find-the-biggest-movers tool. Much of that is shared domain background rather than this call's contract, so the actionable core is buried and each sentence does not earn its place.

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

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

With 14 parameters, five of them required, and no output schema, the description carries the full burden and does: it explains the ranking semantics, the period/baseline requirements, the currency resolution, what the response fields mean when channels are mixed, and what happens with unserved metrics. Nothing an agent needs in order to call this correctly or interpret the result 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?

Coverage is 93%, so the schema already documents most parameters; the description still adds semantics the schema does not, notably the interaction rules for tags (one drawer ORs, different drawers AND), the reason costCategories should be used instead of manual subtraction, and the profit recipes (["variable","product","account"] for profit without one-offs). limit and reason get no mention in the description, but the schema handles them.

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 concrete verb+resource+scope: rank entities (SKUs by default) by how far a metric moved between a period and a baseline, with direction="down" for losers. An agent knows exactly what it gets. It never names the sibling it is adjacent to (explain_movement), so the differentiation from that tool is left to inference.

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 concrete selection rules for the non-obvious parameters: pass costCategories instead of subtracting lines yourself, pass channels=['VENDOR'] only when the user asks about 1P, ask for All channels rather than adding 3P and 1P yourself, pass currency to pin a code. That is real conditional guidance with an explicit anti-pattern ("NEVER add 3P and 1P figures yourself"). What is missing is guidance on when this tool rather than explain_movement or query_metrics is the right call.

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=true, but the description adds substantial context beyond that: currentCogs null meaning, missingOnly filtering, that total is returned with pagination, and that Vendor Central (1P) rows carry a `channel` field distinguishing SELLER vs VENDOR. This is exactly the extra behavioral detail the annotation can't 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?

Front-loaded with the return shape and scope, then the usage workflow, then pagination and the channel caveat. Dense but well-ordered; the parenthetical detail is efficient. A touch long but every clause carries information.

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

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

No output schema exists, so the description must describe return values — and it does thoroughly (row granularity, currentCogs null, total, channel per row, missingOnly filtering). Given 6 params at 67% coverage, an agent has what it needs to call and interpret the result 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 67%, and the description adds value on top: it explains limit/offset pagination returns total, clarifies missingOnly semantics, and mentions the `channel` field appearing on each row. It doesn't elaborate on region or accounts, but those are well documented in the schema, so the incremental gain is solid but not exhaustive.

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 the specific resource (one region's COGS worksheet) and precisely describes its contents: a row per (account, ASIN, SKU) catalog product and per cost period/batch, with currentCogs. This distinguishes it cleanly from the other worksheet siblings (get_fbm_worksheet, get_vat_worksheet, etc.) as the COGS one.

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

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

Explicitly routes the agent: 'Use it to match a seller's source file to exact SKUs/ASINs before building import_cogs rows' names the downstream sibling and the prerequisite step, and 'read a SKU's full FIFO ladder before restating it' gives a second concrete use case. Match-by-SKU-then-ASIN precedence is spelled out.

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?

readOnlyHint=true already establishes safety, and the description adds meaningful behavior: default FBM-only scope, fbmOnly=false including FBA, missingOnly behavior, pagination via limit/offset, and the key semantic that currentCost null means the seller's rate book applies. It leaves minor operational details (ordering, auth) unstated but covers the important data behavior.

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

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

Front-loads the resource definition, then the intended use, then defaults/filters/pagination. Every clause carries information about the result shape or call behavior, with no 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?

There is no output schema, so the description appropriately explains the returned row composition (account, ASIN, SKU, isFbm, L24M sales, currentCost) and the null override meaning. It omits return ordering and pagination metadata, but is otherwise sufficient for an agent to call and interpret this read-only worksheet.

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 high (71%), so the baseline is 3, but the description adds meaning beyond the schema by clarifying that fbmOnly=false includes FBA and by explaining the null-currentCost interpretation. It does not extend the accounts or reason parameters, but it meaningfully supplements the filtering semantics.

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 the specific resource and shape: a per-delivery-zone FBM worksheet with one row per (account, ASIN, SKU) product, including channel, L24M sales, and current override. It distinguishes itself from the downstream import_fbm_costs sibling by positioning itself as the matching step before import, so an agent can identify its role without opening schemas.

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

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

Gives a clear use case ('match a seller's per-product shipping file to exact SKUs/ASINs before building import_fbm_costs rows') and explains the fbmOnly/missingOnly filtering modes. It does not explicitly name exclusion cases or contrast with all sibling worksheet tools, but the intended workflow is clear.

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; the description carries the real burden and does so richly — it discloses that warehouses are read from shipments and never configured, that lastShipment is null on renamed plans, that missing COGS/VAT means overstated profit, how the P&L resolves costs and VAT, and the parameter-resolution fallback chain for stock. This is exactly the kind of behavioral context annotations cannot provide.

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 'Start here for any seller input' and organized domain by domain, and most detail is genuinely interpretive. But it is a very long, semicolon-chained wall of text for a three-parameter tool, with some over-specified asides (the full lastShipment null rationale, the five-parameter resolution chain) that slow tool selection rather than enabling it.

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 compensates by describing the return contents per domain in enough depth to reason about what the call yields. For a read-only setup tool covering five domains, nothing essential to correct invocation or interpretation 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 the baseline is 3; the description earns more by expanding each `domain` enum value into a concrete inventory of what will be returned (e.g., soldSkusMissingCogs for cogs, priced/container/row/required for fbm). It does not add anything about the `reason` parameter, and `accounts` scoping is only implied ('verdicts are never pooled across accounts'), keeping it from 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?

The description states the resource (the setup state of ONE seller-input domain) and enumerates each domain's contents in detail, which lets an agent distinguish it from the worksheet/import siblings. The opening phrase 'setup surface ... as the header of its Data Inputs page shows it' is somewhat abstract, but the per-domain breakdown removes ambiguity.

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 sequencing is given: read before an import to learn target format/valid codes, read again after to verify; for stock, read before query_inventory with includeReorder=true; for VAT, read the specific account because verdicts are never pooled. Each domain also names the next tools (get_cogs_worksheet, import_cogs, etc.), so the agent knows the alternatives and when they apply.

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?

With readOnlyHint=true the safety profile is covered, and the description adds substantive behavior: the resolution precedence chain (product row → product 'ALL' → account default region → account default 'ALL'), the meaning of source=null (no recommendation), and region 'ALL' semantics. It doesn't describe pagination totals or return envelope, but the resolution model is unusually well disclosed.

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 is front-loaded, but the body is a single dense run-on packed with internal jargon (own/resolved/source/paramsComplete) that is harder to parse than it needs to be. Most clauses earn their place, yet the structure could be broken up for readability.

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 7-param tool with no output schema, the description explains the return shape inline (own values, resolved values, source provenance, paramsComplete, velocity/FBA stock) and covers the resolution logic and 'ALL' region, so an agent knows both what it gets and how to interpret 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 71% and already documents region, reason, search, accounts, and missingOnly. The description adds meaning beyond the schema: what region 'ALL' actually lists (product × 'ALL' rows where a production lead time lives) and that missingOnly filters on RESOLVED parameters resolving nothing. limit/offset are only touched by 'Paginate with limit/offset'.

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 ('get_stock_worksheet' → one region's replenishment worksheet = Data Inputs 'Stocks' page rows) and defines the row grain as (account, ASIN). It clearly differentiates itself from the *_worksheet siblings (cogs, fbm, vat, tags) by naming the exact page and the resolution semantics it returns.

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 case ('match a seller's lead-time file to exact ASINs before import_stock_params') and a conditional behavior (missingOnly=true keeps products that resolve nothing). It ties sequencing to import_stock_params, but doesn't explicitly say when to use a different worksheet tool instead.

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 readOnlyHint, the description discloses a great deal: the six-number resolution chain (product → warehouse → account → fleet default → null), the straight-from-factory exception with null warehouseUnits and 'not applicable' sources, overdue defined as expected before today UTC, and that import_supply_chain closes orders by reference. These are exactly the non-obvious behaviors an agent would otherwise get wrong.

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 front-loads the identity of the resource correctly, but the bulk is one long run-on paragraph of field-by-field column semantics with parenthetical asides. Nearly every detail is substantive, yet the packing makes it hard to scan and would benefit from being split into purpose / fields / views / usage sections.

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 and only a readOnly annotation, the description carries the full burden of explaining the returned rows — and it does, covering accounts, warehouses, regions, ASIN/SKU counts, units, open orders and the numbers object with sources. An agent can reason about the payload without ever calling the tool.

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

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

Schema coverage is already 90%, so the baseline is 3, but the description adds genuine meaning: view semantics (missing-count never applies to straight-from-factory lines), warehouse resolution and region aliases, and what 'counts' returns. It does, however, reference a `counts` capability that has no corresponding parameter in the schema, which is mildly confusing.

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 concrete verb+resource: reading the Product table of the Supply chain page, one line per product × warehouse, with a named producer (import_supply_chain) and a named consumer workflow. It is unambiguously distinguishable from siblings like get_stock_worksheet or query_inventory, though the sheer density of field-level detail buries the core statement.

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

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

Explicitly says to use it 'to match a seller's file to the exact lines before import_supply_chain, and after, to verify', which is a real when-to-use condition tied to a specific sibling. It also cross-references get_setup for warehouse naming and explains pagination, but offers no explicit exclusions for when another worksheet tool is the better choice.

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?

With `readOnlyHint: true` already covering safety, the description adds substantial behavior: predefined rule-based drawers are computed and never listed, channel filtering changes row structure, and 1P rows have `sku` equal to the ASIN. It also explains that an ASIN sold on both channels appears as two separate rows.

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 a dense paragraph, it is front-loaded with the core purpose and every sentence carries operational information about filtering, channels, row semantics, or pagination. There is no filler or repetition.

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

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

For a complex read-only worksheet tool with no output schema, the description supplies the return shape, row identity, channel-dependent behavior, drawer behavior, and pagination model. An agent has enough information to call it correctly without needing the output schema.

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

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

The description adds meaning well beyond the 71%-covered schema for key parameters: `workspace` is implicit when one workspace is in scope, `channels` defaults to Seller Central and changes the returned rows, and `drawer` + `untaggedOnly` has a specific filtering meaning. It also explains pagination via `limit`/`offset`.

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 and verb: it returns the product-tagging worksheet for one workspace as JSON, including drawers and per-product current tags. It clearly distinguishes this from related workflow tools by naming `import_product_tags` and by explaining the worksheet/template role.

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

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

It explicitly says to use this before building `import_product_tags` rows to match a seller's tagging file to exact SKUs/ASINs. It also gives concrete usage variants: `drawer` plus `untaggedOnly=true` for products not yet tagged in a drawer, and `channels` for 3P vs 1P vs both.

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?

With readOnlyHint already declaring safety, the description adds useful behavioral detail: null category meaning, the dashboard's specific definition of missingOnly, and server-side pagination with limit/offset and total returned. It does not cover auth or rate limits, but those are not central here.

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 the resource and row shape, then explains missingOnly, gives the intended use, and ends with pagination. Every sentence carries useful information with no 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?

For a six-parameter read-only worksheet tool with no output schema, the description explains the returned row shape, the special missingOnly semantics, the intended downstream use, and pagination. Remaining gaps like account-filter behavior and reason are adequately covered by the schema.

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

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

Schema coverage is 67%, so the schema handles region, accounts, and reason reasonably well. The description adds real meaning for missingOnly by explaining the dashboard's precise missing-definition, and it clarifies limit/offset pagination and total returned.

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 precisely what the tool returns: one VAT region's worksheet with a row per (account, ASIN, SKU) sold product and its current category. It distinguishes itself from downstream import_vat_categories by framing the worksheet as the input used before building import rows.

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 a clear use case—matching a seller's tax-class file to exact SKUs/ASINs before constructing import_vat_categories rows. It does not explicitly name when not to use it or list alternative tools, but the context is concrete.

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?

The only annotation is readOnlyHint=false, so the description carries the rest and does it well: it discloses the destructive blast radius of 'replace' ('wipes and restates every (account, region) present in rows'), that merge touches ONLY sent keys, that fifo replaces the whole batch ladder, the preview-returns-token mechanism, plus auth prerequisites (OAuth connection, not a workspace API token) and the OWNER role requirement.

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

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

Front-loads the two-step rule, then mode semantics, then limits and prerequisites — a sensible ordering with no filler sentences. It is dense as a single block and repeats enum semantics that the schema also states, which costs it the top score.

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 by explaining what the preview returns (per-row warnings, SKU-grain diff, confirmationToken) and what the commit call expects. Combined with auth and role requirements, an agent has everything needed to call this 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?

Schema coverage is 86%, so the schema already documents most fields; the description adds the relational semantics the schema can't express — what a 'fixed' row replaces versus what a 'fifo' row replaces, and why mode choice changes destruction scope. It largely restates the mode enum and the 2000-row cap that already live in the schema, keeping it just short of 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?

Specific verb and resource ('Import COGS (cost of goods) rows for ONE seller account') with explicit scope (one account per call). It distinguishes itself from the read-side sibling by telling the agent to read the ladder first with get_cogs_worksheet, so the boundary is clear 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?

Gives an explicit workflow: call first without commit, show the diff and warnings, then re-call with commit:true and the token. It states when each mode applies ('merge' safe for partial files, 'replace' only for a full-region statement), when to split calls (>2000 rows), and the 1P exclusion for 'fifo'. No alternatives are left to inference.

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

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

Annotations only declare readOnlyHint=false; the description carries the rest and does it well, disclosing the two-step preview/commit requirement, the OWNER role + OAuth prerequisite, the 2000-row cap, the destructive semantics of 'replace' (rows absent lose their count), and the 0-vs-absent distinction. That is substantial mutation-transparency value beyond the annotations, though it does not describe the diff/warning payload in detail.

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

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

Front-loads the deprecation notice and the routing instruction, then the semantics. It is dense and somewhat long for a single description, but nearly every clause (coverage ladder position, 0-vs-absent, merge/replace, row cap, role) carries operational weight.

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 mutation tool with no output schema, the description supplies everything an agent needs to call it correctly: prerequisites, two-step flow, mode semantics, row limits, and the absent-vs-zero interpretation. 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 coverage is 83%, so the schema already documents most parameters (mode, asOf, region, quantity, commit, confirmationToken, reason, account). The description reinforces mode semantics and the preview/commit token flow, and clarifies that '0 is a real count, absent means unknown', but this largely duplicates the schema text rather than adding new syntax or constraint detail. Baseline 3 is appropriate given the high coverage.

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 (import) and resource (external stock of ONE account, units held outside Amazon per product × region) and positions it precisely within the product's data model (externalStock, coverageWithExternal). It explicitly distinguishes itself from import_supply_chain as the deprecated predecessor, so an agent can pick the right tool 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?

Explicitly says the tool is DEPRECATED and to prefer import_supply_chain for new callers, then gives the remaining use case. It also prescribes the mandatory workflow (preview without commit, show user, then commit with token) and spells out when 'merge' vs 'replace' applies.

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 provide only readOnlyHint=false, so the description carries nearly the full burden and does so: it discloses the destructive scope of 'replace' (wipes and restates every (account, zone) present), the confirmationToken requirement, the 2000-row cap, and the OAuth + OWNER role prerequisite. These are the exact traits an agent needs before invoking a mutation.

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 identity, then workflow, mode semantics, limits and prerequisites in a tight sequence. A couple of clauses restate schema-level details (e.g. the rule multipliers), costing a bit of density but nothing is truly wasted.

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 usefully sketches the preview return (warnings, SKU-grain diff, confirmationToken). It says less about what a successful commit returns, but for a 7-param destructive import the coverage is close to sufficient.

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 86%, yet the description still adds real meaning: it explains that zone is a delivery country or 'ROW', that rule controls what cost multiplies ('per_unit'/'per_parcel'/inherit), and spells out the exact upsert key set (asin, sku, zone, period) for merge mode. Some of the rule/period explanation duplicates the 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+scope: 'Import PER-PRODUCT FBM cost overrides for ONE account', and immediately frames the data as 'the exceptions to the rate book', which distinguishes it from the sibling import_fbm_zone_rates without the agent 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?

Clearly states the two-step workflow (preview without commit, then commit with token) and explains exactly when 'merge' vs 'replace' applies, warning that replace is destructive with a partial payload. It doesn't explicitly name import_fbm_zone_rates as the alternative for base zone rates, leaving that routing to inference.

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

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

Annotations only mark readOnlyHint=false; the description goes far beyond by disclosing the preview/validation/diff/confirmationToken flow, that 'replace' deletes every absent line, and the OAuth + OWNER role requirement. These are exactly the mutation and destructive-behavior details an agent needs before calling.

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

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

Front-loads the purpose, then the two-step mandate, then mode semantics, then prerequisites — a logical order with no filler sentences. It is a single dense paragraph with heavy parenthetical nesting, 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?

For a mutation tool with no output schema, the description supplies what's needed: it describes the preview's return (per-line warnings, a diff, a token), the confirm flow, the merge/replace consequences, and auth requirements. Nothing essential to calling it correctly is missing.

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

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

Schema coverage is already 83%, so the schema carries most parameter meaning; the description adds value by explaining zone containers ('one rate for every country of it without a rate of its own'), the 'ALL' zone for packing/picking, and that the commit call must repeat the SAME account/mode/rows plus the token. It largely restates zone/kind semantics already in the schema, so not a full 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 (Import) and resource (FBM rate book) with scope 'ONE account', and enumerates what the rates cover (shipping per container/country/ROW, packing per parcel, picking per unit). It is unmistakably clear what the tool does, though it never names a sibling (e.g. import_fbm_costs) to distinguish itself from.

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

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

Explicitly says this is the FIRST thing to set up and 'nothing is priced until a zone rate exists', mandates the two-step preview-then-commit flow, and explains when to pick 'merge' vs 'replace'. The conditions that select each behavior are spelled out, not implied.

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 say readOnlyHint=false, so the description carries the burden and does it: it discloses that a no-commit call validates against the catalog, returns per-row warnings, a per-drawer diff, BEFORE → AFTER statements and a confirmationToken, that unknown tags in the org-shared drawer are skipped, that nothing outside the named cells changes, that creating drawers/tags needs the owner role, the 2000-row cap, and the OAuth requirement.

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 a single dense block, but it is front-loaded with the two-step contract and the safety guarantee ('nothing outside the named cells changes'). Some sentences restate the `mode` schema description nearly verbatim, which costs a little against the otherwise tight prose.

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 by enumerating exactly what the preview returns (warnings, per-drawer diff, BEFORE → AFTER per SKU/drawer, token). For a 6-parameter bulk mutation tool, an agent has everything needed to call it 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?

Schema coverage is already 83%, yet the description still adds cross-parameter meaning the schema cannot: how `tags[drawer]` cells are read under each `mode`, that null/[] removes in 'set' but is a no-op in 'add', that a single string is comma-split, that `channel`/`sku` resolve 1P vs 3P, and that the commit call must reuse the same mode/rows plus the token.

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 ('Tag products in ONE workspace') and immediately frames it as a two-step import modeled on import_cogs, which distinguishes it from get_tags_worksheet, list_tags, and the other import_* 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?

Gives explicit when-to-use routing: 'set' for a spreadsheet column or an exclusive-tag move (Summer → Winter), 'add' when the seller says 'add', 'also', 'tag these as'. It also spells out the preview-then-commit sequence, when to pass `workspace` (several in scope only), and how 1P rows are named.

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 carry only readOnlyHint=false, so the description carries the behavioral burden and does: server-side validation scope (ASINs against stocked products, regions, ranges), returned per-row warnings and ASIN-grain diff, confirmationToken requirement, the 2000-row cap, refusal of empty rows, and the OAuth + OWNER role prerequisite. Merge/replace semantics are spelled out field by field, including that omitted keeps vs blanks and that null clears.

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 deprecation and successor, then the core operation; every clause is dense with operative content. It loses a point for restating material the schema already documents at length — merge/replace behavior appears in both the prose and the mode/field descriptions, and 'up to 2000 rows' duplicates maxItems.

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 two-step, role-gated, 2000-row batch mutation with no output schema, the description supplies everything needed to call it correctly: prerequisites, preview/commit flow, token handling, validation feedback shape, row and field semantics, and the fallback resolution model. Nothing material is left to inference.

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 83%, but the description adds meaning the schema cannot: the three-rank resolution hierarchy (own row → 'ALL' row → account defaults) that explains why a blank field is legitimate, and the merge-vs-replace consequence per field. It also documents the ALL pseudo-region and the deprecation path, which no parameter doc 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?

Opens with the deprecation and names the successor (import_supply_chain), then states a precise verb+resource: import the reorder parameters of one account, per product × stock region. An agent can tell this apart from set_stock_defaults and import_supply_chain 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?

Gives explicit routing: set account-wide values with set_stock_defaults and import only exceptions here; use import_supply_chain for the new table. Adds hard procedural rules — never skip the preview, call again with commit:true plus the token only after user approval — plus the factory-to-FBA edge case where external target and to-warehouse lead time are 0, not blank.

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, so the description carries most of the burden and does it well: it discloses destructive semantics of 'replace' (open lines absent from rows are deleted), that history is untouched, the 2000-row cap, and the OWNER role / OAuth requirement. It does not cover failure modes or how partial validation errors are returned, which keeps it short of a 5.

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

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

Front-loaded with the deprecation notice, then the ladder position, then the operational rules — the ordering is sensible. It is dense and repeats some merge/replace semantics already in the schema, so it is longer than strictly necessary, but no sentence is purely 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?

No output schema exists, yet the description explains what the preview returns (warnings, per-region diff, confirmationToken) and what the commit consumes. Combined with the permissions note and row cap, an agent has what it needs to sequence the call 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 83%, so the schema already documents mode, status, reference and expectedAt, and the description largely restates them. It still adds meaning the schema does not: the 'fifth rung of the ladder' framing, which downstream fields the open lines feed, and the guarantee that re-sending unreferenced lines never doubles them.

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, then pins down the exact scope: the seller's own purchase orders on its supplier, per product × stock region, explicitly not Amazon Vendor POs. It also names its successor (import_supply_chain) and the query tool that surfaces the result (query_inventory as onOrderUnits / nextExpectedAt), so an agent can place it among siblings immediately.

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

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

Explicitly says this tool is deprecated in favor of import_supply_chain and for whom it remains. It spells out the mandatory two-step flow (preview, show user, commit with confirmationToken) and which mode to use, including the re-send-with-status-'received' case, 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?

With only readOnlyHint=false in annotations, the description carries the behavioral burden and does so thoroughly: it explains merge semantics (omitted keeps, null clears), order closure via status, straight-from-factory special handling, preview validation/diff output, confirmation-token requirements, row limits, and OWNER/OAuth prerequisites.

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 purpose and critical two-step safety flow are front-loaded, and nearly every sentence adds operational value for a complex import. However, the description is a very dense single block, making it harder to scan than it could 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?

There is no output schema, but the description explains what the preview returns (warnings, per-warehouse diff, totals, confirmationToken), the write behavior, the row cap, and the authorization requirements. Given the tool's complexity, this is complete enough 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 already 80%, but the description adds significant cross-parameter meaning: the row identity model, how N orders map to N lines, how the six product-level numbers interact with warehouse lines, and how null versus omitted behaves for counts and lead-time fields.

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: import the PRODUCT table of the Supply chain page for one account. It further defines the row model (one line per product × warehouse, at most one supplier order) and notes what is not included, making the tool distinguishable from sibling import tools.

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

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

It gives clear usage conditions: call without commit first, validate/diff, get explicit approval, then call again with the same payload plus commit:true and the token. It also states limits and prerequisites. It references get_supply_chain_products for straight-from-factory detection but does not explicitly name alternatives for other supply-chain import scenarios.

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 carry readOnlyHint=false, so the description bears the weight and delivers: validation that rejects unknown/wrong-region codes as warnings-never-writes, per-row warnings and SKU-grain diff returned, destructive replace semantics with partial payloads, 2000-row cap, and OAuth + OWNER role prerequisites. This is rich behavioral context beyond 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?

Dense but front-loaded: the two-step protocol and the merge/replace distinction lead, with limits and prerequisites trailing. Every clause carries operational weight, though a single long paragraph could be broken for 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 destructive, two-step mutation with no output schema, the description covers the preview/diff/warnings return, token handling, safety of merge vs replace, row limits, and auth/role requirements — everything an agent needs to call it correctly and 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?

Schema coverage is high (86%), so the baseline is 3, but the description adds real meaning: merge touches only sent (asin, sku, region) keys, a null category CLEARS, replace wipes and restates each (account, region) present, and the commit/token coupling. These go beyond the field-level 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?

States a specific verb and resource ('Import per-product VAT categories') plus scope ('ONE seller account'), and situates it against siblings by referencing import_cogs as the pattern and get_setup domain=vat for context. An agent can distinguish it from set_vat_default_category and the other import_* tools 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?

Explicitly prescribes the two-step flow (preview without commit, then commit:true with token after user approval), names the merge vs replace choice and when each is safe, and notes categories only matter where Amazon does not price the tax (pointing to get_setup domain=vat). This is when/when-not/alternatives guidance at full strength.

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?

readOnlyHint already covers safety, so the description focuses on richer context: the default is Seller Central data unless a channel is passed, and the agent must never sum 3P and 1P figures itself. It also discloses that accounts can span multiple workspaces (agency/clients), which an agent could not infer from annotations or schema. Slightly indirect because much of the behavior described belongs to the calling tools rather than this one.

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 return-field inventory, then the channel definitions, then the cross-tool rule; each block earns its place. It is dense and long for a list tool, and the 3P/1P summation warning could be shortened, but 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?

No output schema exists, and the description compensates by listing every returned field including nested marketplace country/domain and workspace membership. For a discovery tool that gates the channel arguments of several sibling tools, it supplies everything needed to call it and use the result 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?

Only one optional parameter (`reason`), and the schema documents it fully at 100% coverage, so the baseline for a near-zero-parameter tool applies. The description wisely spends its space on return values and channel semantics instead of repeating the `reason` instructions.

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 ('List the seller's Amazon accounts you can query') and enumerates exactly what comes back (id, name, region, channel, marketplaces, workspaces). This is unmistakably distinct from the query_* and list_metrics siblings in the same namespace.

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?

Tells the agent how to read the `channel` field and explicitly names the downstream tools it governs (query_metrics, find_movers, explain_movement) plus the exact override syntax channels=['VENDOR'] / ['SELLER','VENDOR']. It also routes workspace-level disambiguation to the `workspaces` field and the `accounts` filter of other tools.

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; the description adds meaningful context beyond that — that these are raw seller-entered values rather than derived metrics, and that remediation happens via a separate two-step, approval-gated import_cogs. It doesn't discuss pagination or the `limit` behavior, which keeps it below 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?

Front-loaded with the core purpose and the key contrast, which is good, but the single dense parenthetical for 'fbm' is hard to parse and the sentence is heavily subordinated. It's information-dense but not well-structured for scanning.

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?

Covers the raw-vs-aggregated distinction, the three input kinds, audit use cases, filtering, and the remediation path — sufficient for a read-only listing tool with no output schema. Minor gap: nothing about what the returned rows look like or how `limit` truncates 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?

The description adds real semantic meaning to `type` (what 'cogs', 'fbm', 'vat' actually return, including the fbm zone vs sku level distinction) beyond the schema's terse 'Which input to audit'. It also explains the purpose of `skus` filtering. `limit`, `reason`, and `accounts` are left to the schema, which covers them adequately at 80% coverage.

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 ('List the seller's CONFIGURED per-SKU input values') and explicitly contrasts with the aggregated metric ('source of truth, not the aggregated metric'). It goes further to enumerate the three input kinds selected by `type`, so an agent can distinguish it from get_cogs_setup, get_vat_setup, etc.

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 a concrete purpose ('Use it to audit setup') with specific failure modes to look for (placeholder/negative/implausible costs, per-lot vs per-unit, wrong VAT categories, missing SKUs), and names the alternative for remediation ('To FIX missing or wrong COGS, use import_cogs (two-step, with user approval)'). This is explicit when-to-use plus alternative routing.

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

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

The readOnlyHint annotation already establishes the safety profile, and the description adds useful behavior beyond that: results are newest first, default page size is 20, and the filters are described. It stops short of describing the exact response shape, but with no output schema and annotations covering safety, this is still strong context.

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

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

The definition is front-loaded with purpose, then usage, then filters and pagination, and every sentence contributes. The opening sentence is long and slightly winding, but overall it is efficient and informative.

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 with ten optional filters, high schema coverage, and readOnlyHint annotations, the description covers purpose, usage, filtering, ordering, and pagination. An agent has enough information to select and call it correctly without additional 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 already high at 90%, so the schema carries most parameter detail. The description still adds meaningful semantics, notably that ASINs can be child or parent with no need to know which, and that text search covers description or type.

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 ('seller's EVENTS — the dated notes Nova draws on the charts') and immediately clarifies what counts as an event with concrete examples. It also distinguishes this listing tool from the sibling create_event by explaining that it is used to read existing events and check whether something is already logged.

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 when-to-use guidance: read events when explaining a movement to see what changed around that date, and check this list before calling create_event to avoid duplicate logging. The alternatives and the condition that selects them are named directly.

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=true, so the description carries most of the burden and does add real context: it explains the conditional `channels` field for 1P accounts and decodes each `basis` value (sell-out/sell-in/purchase-orders/stock). It does not cover output shape beyond field names or note any size/rate limits, keeping it below 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?

Front-loaded with the core purpose and the 'call this first' directive, then structured into a clearly scoped elaboration. The Vendor Central paragraph is dense and long relative to the tool's simplicity, but every clause conveys semantic meaning rather than 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?

There is no output schema, so the description must explain what comes back — and it does, enumerating the four core fields plus the conditional `channels` and `basis` semantics. Nothing an agent needs to interpret the result and pick a metric key 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?

There is a single parameter and schema description coverage is 100% — the `reason` field is fully documented in the schema, including the English-only and recording rationale. The description adds nothing about it, 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 ('List the metrics Nova can report') and immediately enumerates the returned fields (key, label, unit type, higher-is-better), which distinguishes it from siblings like query_metrics and describe_metric. An agent knows exactly what this returns 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?

Gives an explicit sequencing directive: 'Call this first to discover valid metric keys for the other tools.' That is a clear usage context. It stops short of naming alternatives (e.g., describe_metric for per-metric detail) or stating when-not to use it, 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?

Beyond the readOnlyHint annotation, it discloses that negations carry no spend/clicks/period (so no aggregation is meaningful), that the ads entity snapshot must be built first, and that only Sponsored Products is served with other adProducts values refused by name. These are exactly the non-obvious behaviors 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?

Front-loads what the tool is, then the workflow, then the level/kind row anatomy, then the SP-only constraint. Dense and useful throughout, though the SP-only restriction is stated twice (description and adProducts schema), which costs a little redundancy.

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

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

For a 15-parameter, no-output-schema tool, the description covers the row shape (adProduct, level, kind, keywordText, matchType, expressionType, expressionValue), the prerequisite snapshot, and the ad-product limitation. 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?

Schema coverage is already 87%, and the description still adds meaning: `level` is where the rule lives (campaign vs ad_group), `kind` is what it blocks, and it explains which fields a row carries for each kind (keywordText/matchType vs expressionType/expressionValue). It does not add much on q, states, or sort semantics, but that is minor given the strong schema.

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: lists the seller's negative keywords and negative product targets, explicitly framing them as blocked traffic. It also distinguishes the tool from query_search_terms and from any metrics tool, 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?

Gives explicit use cases (is this query already negated, which campaigns block a brand, ad-group-level exclusions) and a full workflow pairing query_search_terms as the candidate source with this tool as the negation check. It also names the alternative for spend data, so the boundaries are unambiguous.

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?

With readOnlyHint already declaring a safe read operation, the description adds substantial context: drawers group tags of one kind, `type` distinguishes manual seller assignments from predefined computed membership, and the returned IDs map to specific downstream filters. It does not discuss pagination or empty-drawer behavior, but the core data semantics are well disclosed.

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 the purpose and is dense with useful detail, but the long parenthetical lists of sibling tools and examples make it heavier than ideal. Every sentence is relevant, though the structure could be easier to scan.

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 explain what comes back, and it does: drawers, tags within each, IDs, and the meaning of `type`. For a read-only lookup tool with one fully described parameter, this is complete enough for an agent 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?

There is only one parameter, `reason`, and the schema describes it fully at 100% coverage. The description does not add anything about that parameter, so the baseline score applies because the schema already carries the meaning.

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

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

The description states a specific verb and resource: it lists "Your Filters" drawers and the tags inside each, along with the IDs other tools require. It clearly distinguishes itself from sibling query tools by explaining that this is the lookup layer that converts names into filter IDs.

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 when-to-use guidance: call this to turn a name the user says into the ID to pass in `tags`, because the filters take IDs, never names. It also names the downstream tools that consume the tag ID and explains the drawer-ID grouping used by query_metrics.

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?

Far exceeds what readOnlyHint=true conveys: it discloses refusal behavior (calls refused by name with a message naming ADS_FACT_ENABLED), null-vs-zero semantics with `unservedMetrics` notes, per-product attribution windows and history floors (`historyStartsAtByProduct`), that the profit keys trigger a P&L join and shift spend/sales to an attributed estimate, and that `currencyNotice` MUST be relayed. It also flags the non-additivity trap (never sum sales/orders/ACOS across products; spend is the one additive column).

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 questions, then sectioned with markers (💰 PROFIT KEYS, 🧭 AD PRODUCTS, ⏳ HISTORY, 💱 CURRENCY), so it is navigable despite its length. It is nonetheless very long for a tool description and repeats the null-vs-zero / unservedMetrics rule several times, which costs context budget even if each caveat is individually load-bearing.

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

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

For a 29-parameter, no-output-schema tool this is close to complete: it covers return shape ('rows with value, comparison value and variance, plus the reporting `currency`'), refusal cases, multi-product additivity limits, and history floor reporting. Nothing an agent would need in order to call it correctly appears missing.

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

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

Schema coverage is already 90%, so the baseline is 3; the description still adds real meaning — the metric key universe is declared a SEPARATE universe from list_metrics with an explicit allowed list, `adProducts` default behavior is explained, `groupBy` grains are grouped by category, and the bid vs reportedBid distinction on keyword rows is spelled out. It also explains consequences of parameter combinations (profit keys force the attributed estimate) that no schema field could 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?

Opens with a specific verb and resource ('Amazon advertising console — Sponsored Products + ... at the AD PRODUCT / PORTFOLIO / CAMPAIGN / AD GROUP / KEYWORD grain') and immediately enumerates the business questions it answers, so the agent knows exactly what it retrieves. It also explicitly distinguishes itself from query_metrics and list_metrics, which removes sibling ambiguity.

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

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

Explicitly routes between tools: 'For ad TOTALS by account, product or period, and for ANY year-over-year or long-history comparison ... use query_metrics instead', and names per-ASIN Sponsored Brands as belonging to query_metrics. It also states precise when-nots — profit keys cannot combine with the placement grain or a search-term filter, placement rows cannot combine with a keyword or product dimension, Sponsored Display has no search-term or placement report — plus a fallback instruction to 'try them and read the answer rather than assuming' for ADS_FACT_ENABLED.

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 declare readOnlyHint=true, so safety is already covered, but the description adds genuine behavioral context: rank direction (lower = better), the `scope` field on catalogue-wide results, the parentAsins+groupBy childAsin interaction, and the important caveat that an empty result means 'no filter match' rather than 'no BSR data'. It does not cover pagination behavior or the shape of series rows, which is the main residual gap.

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 claim and the sibling exclusion, and nearly every clause carries operational value. Slightly overstuffed: the design-rationale aside '(a plain average would sever it)' and the emphasis casing ('CORRECT', 'ONE call', 'ALL') are rhetorical rather than informative.

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 15 parameters and no output schema, the description carries the return-value burden well: it explains what 'latest' returns (last observed rank plus period-average main/sub category ranks, optional baseline delta), that rows come back per product, that catalogue mode exposes a `scope` field, and how errors surface on empty filters. Nothing critical is missing 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 already 80%, yet the description still adds non-obvious semantics the schema cannot express: the product list must match groupBy (skus/childAsins/parentAsins) and be passed in ONE call, and parentAsins combined with groupBy childAsin returns the parents' children. It also restates limit's default (50) and the baseline pairing. tags/accounts/marketplaces add nothing beyond the schema.

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 (BSR for the seller's products) and immediately differentiates from the nearest sibling: 'query_metrics does NOT serve BSR.' Also pins the scope (per-marketplace category/rank pair) rather than a blended average.

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

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

Explicit routing instructions — use THIS for any BSR question, query_metrics is not an alternative — plus concrete mode selection: granularity='latest' for a point-in-time read, a time grain for a series, and product-list vs catalogue-bestsellers depending on whether skus/childAsins/parentAsins are supplied. It even warns against the wrong invocation pattern (never loop one call per ASIN).

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?

With only readOnlyHint provided, the description carries the burden well: it discloses the ~95-day DSP history, empty-before-connection behavior, non-error no-advertiser response, level-specific metric universes, filter refusal behavior, and currency handling. There is 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 front-loaded with the critical DSP-vs-PPC distinction and follows a mostly useful structure. It is very dense and long, but much of the length is justified by the 29 parameters, metric enumeration, and absence of an output schema; some currency/answer detail 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?

No output schema exists, so the description must explain the return shape; it does so by covering `data`, `attrs`, `metrics`, `summary`, `levelNote`, `dspAdvertisers`, `period`, `currency`, `currencyBasis`, and notices. It also covers edge cases such as empty history, unattributed country rows, and non-additive audience segments.

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?

Although schema coverage is 100%, the description adds substantive meaning beyond it: `level` is framed as selecting one of Amazon's DSP reports, `metrics` form a separate universe from list_metrics and query_advertising, filters are level-specific, and `currency` pinning behavior is explained. This meaningfully reduces misuse risk for a 29-parameter 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?

The description states a specific resource, Amazon DSP advertising, and explicitly distinguishes it from Sponsored ads and query_advertising. It gives concrete examples of what the tool answers, such as cost, reach, line items, audiences, and countries.

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 routes the agent: use query_dsp for DSP, query_advertising for Sponsored ads, and query_metrics for P&L advertising totals. It also explains when no DSP advertiser is linked, which levels to start with, and why audience rows must not be summed.

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?

With only readOnlyHint=true in annotations, the description carries the burden and delivers: it discloses that no dates exist (fetchedAt is a nightly read at 01:30 UTC, never a business date), that marketplaceId is ignored by the API and destination must be read from stockLocation/fcCountry, that no shipment cost is exposed, and what isFromAwd flags. It also states the 400 product×location pair cap for summary calls.

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 scope, then caveats, then the summary mode — a sensible order. It is dense and re-explains fetchedAt in prose that the schema also covers, plus heavy ALL-CAPS and emoji usage, but nearly every sentence carries a distinct caveat rather than 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?

For an 18-parameter tool with no output schema, it explains the record shape (one per shipment with SKU lines including shipped/received quantities) and details the summary counters, which compensates for the missing output schema. Remaining gaps are minor, such as the exact response envelope and pagination behavior beyond offset/limit.

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 94%, so much is documented, but the description adds real meaning the schema lacks: the WORKING/READY_TO_SHIP versus SHIPPED/IN_TRANSIT mapping behind each category, and the nuance that with sku/asin the category is judged on that product's lines only. This is value beyond the schema's own wording, though some caveats (fetchedAt, stockLocation) are repeated from schema descriptions.

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: 'FBA INBOUND SHIPMENTS — the app's Inventory › Inbound shipments panel... every shipment of the last 18 months at its CURRENT state, one record per shipment with its SKU lines.' It also explicitly distinguishes itself from siblings: 'Not a metrics tool... ask query_inventory for totalFbaIncoming / inboundUnits per SKU.' An agent can identify this tool versus query_metrics and query_inventory 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?

States when to use it ('what is on its way to Amazon, what Amazon has received so far, which closed shipments came up short') and when not to (metrics/aggregation belong elsewhere). It also documents a second mode (summary=true) and its trigger conditions, plus the alternative of query_inventory for totals.

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?

Far beyond the readOnlyHint annotation, it discloses defaults (FBA-only figures, FBM-only SKUs hidden, inactive listings excluded), automatic switch-on of includeReorder, per-SKU non-additivity for non-*Pool columns, currency resolution rules, the Vendor Central refusal, and what groupBy='stockRegion' returns. These are exactly the behaviors an agent would otherwise get wrong.

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 opening sentence is well front-loaded, but the body is a several-thousand-word run-on of nested parentheticals that an agent cannot scan or retrieve from reliably. Valuable content is buried (the ⚠️ sum warning, the includeFbm behavior, the tiles caveat) inside dense field enumerations that belong in a reference doc, not a tool description.

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 26 optional parameters, no output schema, and three grouping modes, this tool needs heavy contextual support, and the description covers defaults, conventions, edge cases, and cross-tool routing. Nothing an agent needs in order to call it correctly appears to be missing.

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

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

Schema coverage is already 88%, so the baseline is 3; the description earns more by explaining interactions the schema cannot — that needsReorder/paramsMissing/reorder sorts auto-enable includeReorder, that includeWorking changes inboundUnits and projections, that sortBy/limit/offset do not apply to stockRegion tiles, and that stockRegions narrows tiles but not totals. Much of the field-by-field prose duplicates what the schema already says.

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 first clause states a specific resource and scope ("Current FBA inventory / stock health per SKU, per ASIN or per stock region") and names itself as the authoritative source matching the app's stock page. An agent can tell instantly that this is the inventory-read tool and not a worksheet importer or a general metrics query.

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 concrete routing: use this for FBA stock health, use query_metrics with channels=['VENDOR'] for 1P accounts (which are refused here), and query_subscribe_and_save to distinguish S&S offer states. It also supplies actionable sort recipes (daysOfInventory asc, fulfillmentChannel desc). It does not distinguish itself from siblings like get_stock_worksheet or query_inbound_shipments, so a 4 rather than 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 only carry readOnlyHint=true, so the description carries the rest — and it does: channel defaulting rules, empty-list-not-error behavior, Vendor Central rows lacking five checks, and the non-obvious flag semantics (a buyable listing is never is_suppressed; Amazon's LISTING_SUPPRESSED notice counts as is_quality_issue). It also discloses the catalog-recapture gate (contentFetchedAt=null) and the keywordsScanned=false trap where NULL means 'not looked at', not 'none written'.

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 is front-loaded before the field inventory, which is good, but the body is a single ~450-word block with nested parentheticals and some duplication of the `channels` and `bands` schema descriptions. The field-by-field row inventory is largely a substitute for the missing output schema, so it earns its place, but the packaging is denser than 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?

With 14 parameters, no output schema, and only one annotation, this description does the heavy lifting: it enumerates the returned row shape (status, issue flags, alert_band, buy-box block, content block), explains the channel-dependent shape differences, and warns about NULL semantics. An agent has enough to call it correctly and interpret results without additional 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 86%, so baseline is 3, and the description goes beyond it on the parameters that matter most: the omit-vs-pass semantics of `channels` (including the vendor-only scope case), what `skus` filters against for Vendor Central rows, and the effect of sort='severity'. A few parameters (tags, limit/offset, reason, marketplaces) are only covered by their 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 and scope: 'Current listing-health STATE per SKU', anchored to the app's Listing Health page so the agent knows exactly which entity is returned. It immediately draws the boundary against the sibling family of metrics tools by declaring 'Point-in-time entity state (NOT a metrics/date-range query — no from/to)'.

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

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

Explicitly enumerates the questions it answers (which listings are removed/suppressed/not buyable, what to fix first, who is losing the buy box, content audits), and states the negative case (not a date-range metrics query). It does not name the sibling tool (e.g. query_metrics) the agent should use instead for time-series questions, so routing relies on inference.

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

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

Annotations only declare readOnlyHint=true, yet the description discloses far more: notice fields that must be relayed (cogsNotice, marketplaceNotice, adsHistoryNotice, subscribeAndSaveNotice), partial/incomplete period semantics with null variances, vendor-vs-seller basis switching and unservedMetrics returning null rather than 0, and currency resolution rules. This is behavioral context no annotation conveys.

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 — the core grain/grouping guidance comes first — and most sentences carry information. But the description is enormous for a tool call, with long emoji-sectioned passages on Subscribe & Save and 3P/1P that largely restate what the schema's basis and channels descriptions already say, making it hard to scan.

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 27-parameter tool with no output schema, the description covers the return shape (rows with value, comparison value, variance, currency, coverage/notice fields), the caveats that qualify figures, and the refusal modes. Nothing material 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 already 89%, so the baseline is 3, but the description adds real meaning beyond it: how groupBy interacts with drawer/tag, why a time grain returns the whole series in one call, when metricFilters/sortBy are refused, and the semantics of costCategories subsets for profit analysis. It explains the intent of parameters, not just their shape.

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 plus scope: 'Query the seller's metrics over a period, optionally grouped and compared to a baseline period.' It then explicitly separates itself from siblings — query_advertising for breakdowns, query_subscribe_and_save for programme state, query_pnl_bridge for the order-vs-cash gap.

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?

Usage is unusually prescriptive: use a TIME grain for a whole series in one call, batch entity lists rather than looping, defer to query_advertising when a campaign/keyword/placement breakdown is needed, choose basis='cash' only when the user speaks of settlements/payouts, and pass channels=['VENDOR'] only for 1P questions. Both when-to-use and when-not-to-use are spelled out with named alternatives.

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 readOnlyHint annotation, the description discloses crucial behavioral details: sign conventions (sales positive, costs/fees negative), the absence of live overlays (current month incomplete on both sides), primary-currency behavior, null semantics (null = not carried, never zero), and that the settlement payout (Transfer) is excluded so totals tie to the settlement report to the cent.

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 the core purpose and is dense with useful detail, but it is extremely long and could be more scannable. Every section is relevant to the complex domain, so the length is largely justified, though some formatting could improve readability.

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 absence of an output schema and the complexity of the tool, the description is remarkably complete: it explains both views, the fields returned (sales, fees, bridge, byPurchaseMonth), how to interpret values, currency behavior, and null handling. An agent has everything needed to call and interpret the 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 coverage is 100%, so the baseline is 3; the description nonetheless adds meaningful interpretation of the view parameter by spelling out what each view returns and that settlementId implies view="settlement". It does not add much beyond the schema for the other parameters, so it sits 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?

The description states a specific verb and resource: it bridges the order-based and cash-based P&L of the same months. It distinguishes itself from siblings by explicitly naming query_metrics and explaining how its order/cash bases correspond to that tool's defaults and basis="cash" option.

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 when-to-use context ('for a finance team tying the commercial month to the settlement month'), gives clear guidance on choosing view="month" versus view="settlement", and notes that settlementId implies the settlement view. It also constrains scope to Seller Central accounts only.

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, and the description adds dense operational context well beyond that: Amazon serves a day of reviews ~3 days late with the last day still filling, counts are null (never 0) outside US/CA/MX/BR, ratings have no history before 2026-10-01, and reading review_units/review_rate on a free-trial org is floor-limited with a dataFloor field returned. It also discloses critical correctness traps (rows are ASIN-level, never sum across seller accounts or add `ratings` up) that no annotation or schema conveys.

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 purpose, then organized into numbered, scannable caveats with bold markers, and nearly every sentence carries a distinct pitfall. It is nevertheless very long and repeats points the schema already makes verbatim ('No comparison period: call once per period', the metric-key universe), which costs it a point.

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 10-parameter tool with no output schema, the description still names the return-shape fields an agent must interpret (reviews_served_from/reviews_served_to/reviews_complete_to, dataFloor, metricAliases, summary.total, rating_marketplace) and covers filtering, grain, pagination and account/permission constraints. There is nothing material left for an agent to guess before calling 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, and the description earns more by adding cross-parameter rules the schema does not express: metric-by-grain compatibility (review_units, review_rate, rating_marketplace are never per time bucket), the entity-vs-time groupBy exclusivity, and the 1000-bucket cap with no sortBy/limit/offset on a series. It does not clarify `reason`, `accounts`, or filter ID formats beyond what the schema already says, so it is short of 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?

The first sentence names the specific verb/domain (Amazon reviews and ratings of the seller's products), the grains (per ASIN and marketplace), the source (Amazon Data Kiosk), and enumerates the metric families returned. It explicitly distinguishes its metric key universe from list_metrics keys, so an agent can tell it apart from query_metrics, query_bsr or query_sqp 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?

Strong when/when-not guidance: 'NO comparison mode: call once per period', 'Vendor Central (1P) accounts have no reviews here', groupBy is either an entity grain or a time grain 'never both', and rating/ratings must be read in a call of their own. It never explicitly routes the agent to a named sibling (e.g. use query_metrics for sales, query_bsr for rank), so the alternative-condition step is implied 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 only declare readOnlyHint; the description carries the rest of the burden and does so densely — clicked-queries-only serving for groupBy='searchTerm', non-additivity of sales/orders/ACOS across ad products with the single additive column named, per-product attribution windows, null-vs-0 ACOS semantics, and currency resolution/relay rules. Far beyond what annotations or schema state.

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 lead sentence is well front-loaded, but the body is a wall of prose with emoji-tagged asides that drifts toward reference documentation — Sponsored Display's lack of a search-term report is stated twice, and the AD PRODUCTS paragraph is long enough to be skimmed past. For a 25-parameter tool the density is defensible, but it is not tight.

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: it explains the response's `currency`/`currencyBasis`/`currencyNotice` fields, `attrs.negatedLevel` and its null caveat, summary.count/total semantics under the click rule, and the '*' PDP placeholder. An agent has enough to call and interpret results 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 already 84%, but the description adds real meaning the schema lacks: the exact metric universe (which ads keys are rejected and why), what each groupBy actually resolves to at this grain, the adProducts default and its disjoint-block behavior, and currency pinning semantics. This is additive, not restated.

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: "The actual customer SEARCH QUERIES behind Sponsored Products and Sponsored Brands spend — the search-term report." It immediately names the questions it answers (negative-keyword candidates, auto-campaign discoveries) and explicitly disclaims Sponsored Display, so an agent can separate it from query_advertising and query_metrics.

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

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

Explicit routing throughout: use query_advertising for per-product ASIN metrics, query_metrics is never cross-summed, list_negative_targets with `q` for "have I ever blocked this", groupBy='adProduct' to split the money. It also spells out refusal conditions (Sponsored Display search-term calls, portfolio/adProduct without ADS_FACT_ENABLED) so the agent knows what will fail before calling.

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?

With only readOnlyHint declared, the description carries the burden and does so well: history is truncated by plan and signalled by `dataFloor` (absent when nothing withheld), weekly data lags ~10 days and monthly ~7 weeks, cross-row summing double counts ~2.4x so the pre-deduplicated `summary` must be used, YoY/WoW metrics are like-for-like only over keywords present in both periods and null below a reliability floor, and monetary values are forced to the org primary currency with an optional `currencyNotice` that must be relayed.

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 is front-loaded in the first sentence and the rest is chunked under scannable markers (period, history depth, comparison, dedup, queryTypes, PPC crossing, currency). It is long — roughly 400 words with several schema restatements — but nearly every block encodes a distinct failure mode the agent would otherwise hit, so little is truly wasted.

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 19-parameter, no-output-schema analytics tool this is thorough: it describes the response envelope fields an agent must interpret (`period.from/to` as period starts, `period.covers` in calendar days, `summary`, `dataFloor`, `comparable_keywords`/`comparable_share`, `currency`, `currencyNotice`) and the SQP-vs-ISO week mismatch that breaks joins. Nothing essential for correct invocation or correct interpretation appears 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 the baseline is 3; the description still adds genuine meaning beyond it by tying parameters to analytical intent — `grain` selects week vs month and their different lag profiles, omitting `from`/`to` yields the latest complete period, `keywords` accepts PPC targets because they resolve through the same clustering, and leaving `queryTypes` open returns head terms like 'makeup'. Some of this is restated from the schema (grain REQUIRED, from/to semantics), which caps it short of 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?

The opening states a specific resource (Amazon Search Query Performance / Brand Analytics) and a specific scope — organic query-level demand across the whole market plus the seller's slice. It explicitly distinguishes itself from the nearest sibling ("not query_search_terms … that one is what people typed before clicking YOUR ad"), 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?

It states concrete when-to-use conditions rather than implying them: 'use ["core","presence","suggested","competitor"] for actionable work, ["core"] for your tight market, ["own_brand"] for brand defence', and it names the alternatives (query_metrics, query_advertising, query_search_terms) plus the exact condition for crossing with them. It also tells the agent what NOT to do ('never this month', 'never period.from/to') and why.

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, so the description carries most of the burden and does so: currency conversion at the block's own window rate, nulls for windows without a rate, `convertedFrom` semantics, null meaning 'no offer snapshot in scope', the `notice` field meaning 'not read yet, never no change', ordering/limit behaviour, and repeated caution that a suspension must be stated without inferring consequences. These are exactly the non-obvious traits 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 four sections are labelled, but the body is a single dense block of 700+ words with parenthetical asides nested several levels deep, making it hard to scan in a tool-selection context. Much of the content is genuinely useful, but the packaging costs readability and repetition (the SUSPENDED/at-risk caveat is restated three times).

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?

Eleven parameters, no output schema, and the description compensates by documenting the shape of each section's return fields (health blocks, offers columns, changes kinds, summary row fields including eligibility derivation rules). For a read-only, no-output-schema tool of this complexity, nothing essential about correct invocation is left unstated.

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

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

Schema coverage is already 100%, so the bar is added meaning beyond the schema; the description supplies it for `currency` (must be an organization-configured code, per-block window conversion, refusal of other codes), `sinceDays`, `limit` (products Amazon warns about first, quiet products cut first), and `accounts`. It adds little for `skus`/`asins`/`marketplaces`/`reason` beyond what the schema states, so it stops short of 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?

Opens with a specific verb+resource (Subscribe & Save programme health, offers, per-product state) sourced from Amazon Replenishment daily snapshots, and enumerates the four sections explicitly. It is clearly distinguished from the sibling tools query_metrics and query_inventory, which are named for the cases this tool does not cover.

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

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

Explicitly routes the agent: use query_metrics for period-based S&S sales/units/stockout loss/discounts and query_inventory for projected units next to days of inventory. It also gives a concrete recipe for the daily check ('section changes with sinceDays 1, keeping rows where subscriptionsCancelled is true or eligibility is SUSPENDED with previousSubscriptions > 0') and a rule for when to pass `accounts`.

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 lone readOnlyHint=false annotation, the description discloses the merge semantics ('omit = unchanged, null clears'), a destructive side effect ('when a line's numbers end up blank its row is deleted'), the preview/commit protocol with confirmationToken, and the auth/role requirement. These are exactly the behavioral traits an agent cannot infer from the annotation.

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 purpose and scope are front-loaded and every clause carries operational meaning, but it is a single dense, em-dash-laden block with decorative asides ('Nova's number, the page's gold figure') that slow parsing. Justified in length by the tool's complexity, slightly improvable in structure.

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 12-parameter mutation tool with no output schema, the description covers the input-shape alternatives, merge/clear/delete semantics, the confirmation flow, and auth requirements. An agent has everything needed to call it correctly and safely without further documentation.

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 the baseline is 3, and the description earns an extra point by explaining the conceptual model behind the params: region 'ALL' vs per-warehouse rows, what each numeric field controls in the ladder, and how factoryLines differ (never 'ALL'). It stops short of adding format details beyond the schema, but the added meaning is real.

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 and resource — 'Set ONE account's numbers of the TOP table of the Supply chain page' — and immediately scopes it to the warehouse/3PL setup. It explicitly positions the tool against siblings by naming import_supply_chain (product-level lines) and get_setup (to enumerate domain/warehouse values), so an agent can distinguish it without opening any schema.

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

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

It states the precedence rule ('a value set here reaches every product without its own number'), the alternative that overrides it (import_supply_chain), the two alternative input shapes (single region vs rows/factoryLines), the mandatory two-step preview-then-commit flow, and the prerequisites (OAuth connection, OWNER role). That is close to a complete when/when-not/alternatives guide.

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?

With only readOnlyHint=false available, the description carries real weight: it discloses the mandatory two-step preview-then-commit flow with a confirmationToken, that omitting commit performs no write, that category null clears state, and the auth/role requirements. That is exactly the mutation-risk context annotations don't provide.

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 action and the two-step flow; every sentence carries operational information. The heavy capitalization and em-dash density make it slightly harder to scan than an ideal definition, but nothing 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?

Covers everything needed to call it correctly: fallback semantics, value choice, preview/commit sequence, clearing behavior, and auth prerequisites. With no output schema, the preview description ('current → new') adequately signals what comes back.

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 adds genuine semantics beyond the schema: it explains what 'A_NOVA_ZERO' actually means versus a concrete code and what null does to the default. It does not elaborate on reason or confirmationToken beyond the schema, keeping it below 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 and resource with explicit scope: set (or clear) ONE account's DEFAULT VAT category, defined as the fallback for products without their own. That definition distinguishes it from bulk-import siblings like import_vat_categories and from per-product settings.

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 concrete when-to-use guidance for the key decision: 'A_NOVA_ZERO' for zero-rated/VAT-outside-Nova sales vs a real code to apply one category catalog-wide, plus null to clear. Preconditions (OAuth connection, OWNER role) are stated. It does not explicitly route to a sibling alternative (e.g. import_vat_categories for bulk), so not a 5.

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