Agent Central

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond that: results derive from retained reports rather than live state, dimensions compared vary by ad product, and the excluded live-entity use case is called out. It does not detail data-freshness lag or result shape, but the output schema covers returns.

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

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

Three sentences, each earning its place: the trigger and purpose first, the ad-product scope second, the exclusions last. No filler, and the most decision-relevant information is front-loaded.

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 ten-parameter diagnostic tool with an output schema, the description covers purpose, scope, and exclusions adequately, and the schema carries parameter detail. It could be slightly more complete about what the comparison returns or how the two periods are expected to relate, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all ten parameters including the ad_product and focus_metric enums. The description only loosely reinforces this via "defaults to Sponsored Products" and "product-appropriate dimensions," adding little syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

The description names a specific verb and resource — root-cause comparison between two periods for sponsored ads performance changes — and scopes it to retained reports. It clearly separates this diagnostic tool from the many read-out siblings like get_campaign_performance, get_sb_campaign_performance, and get_sd_campaign_performance by framing it as comparison/diagnosis rather than reporting.

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

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

It gives an explicit trigger ("Use when sponsored ads performance changed") and an explicit exclusion ("Do not use for live entity state or write readback"), which is strong when/when-not guidance. It stops short of naming the specific sibling tool to use for live entity state, so it falls just under the 5 bar of naming 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?

The description does disclose a lot beyond the annotations: section-by-section contents, evidence sourcing, the ads-enabled conditional branch, and a 'guarded preview-first' flow requiring user confirmation. But it explicitly says the tour 'ends with an optional first write ... negative-keyword create,' while the annotations declare readOnlyHint=true and destructiveHint=false; an agent cannot tell whether this call mutates anything, which is exactly the ambiguity annotations are supposed to resolve.

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

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

Three sentences, front-loaded with the return payload, then the conditional write, then the positioning disclaimer. The first sentence is dense with a five-item list but every clause carries distinct information; 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 multi-section read tool with an output schema and read-only annotations, the description covers contents, evidence basis, and the ads-enabled branch well. The one gap is the write/confirm flow, which is described in the result but left unclarified as to whether this invocation performs 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 description coverage is 100% and every parameter (detail_level, evidence_limit, spotlight_count, date_window_days, first_write_min_spend) is documented in the schema with defaults and rationale. The description adds only indirect color ('source-table evidence' hinting at evidence_limit, the spend-without-converting framing behind first_write_min_spend), 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?

Names a specific verb and resource and enumerates exactly what the tour contains (trust preflight, account pulse, best-seller spotlight, top movers, cross-domain signals with source-table evidence). It also draws an explicit boundary against a whole class of siblings: 'This is a data/evidence tool, not a recommendation engine,' which separates it from get_bid_recommendations, get_budget_recommendations, and get_brand_health.

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?

'first-run account data tour' establishes the context in which the tool is appropriate, and the ads-key clause states a conditional behavior. However, no alternative or sibling is named as the thing to use instead when this is the wrong choice, so the routing guidance stops short of the top bar.

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 it read-only, non-destructive, and closed-world, so safety is covered. The description adds real behavioral context beyond that: the caveat that api_key.permissions lists special capabilities rather than general read/write scope, plus what the payload contains. It stops short of describing pagination or output shape.

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

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

The description is dense but front-loaded on the return payload before moving to usage and routing. Every sentence carries information, though the long field enumeration makes it heavier than it needs to be.

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

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

With no output schema and no parameter descriptions, the description carries the disclosure burden and does cover return contents, read-only semantics, and when to reach for it. The missing coverage of six input parameters is the one real hole.

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 0% for 7 parameters. The description explains only the view enum (summary vs data_map) and leaves limit, offset, domain, tool_names, entity_type, and metric_family entirely undocumented in both schema and prose. It adds real meaning for one dispatch parameter but does not compensate for the coverage gap.

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 (get_account_info) and then enumerates the concrete return payload: display name, safe prefix, access status, marketplace scope, exposure cap, connection status, coverage dates, and tool availability. An agent can distinguish this account-level introspection tool from the dozens of sibling get_* data 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?

It gives explicit triggers (user asks which key/marketplace, whether access is active, whether write access exists, what date range is available, or verifying setup before answering data questions) and routes the cross-domain case to view=data_map. It also draws a boundary against tools/tool_scope_by_domain for effective access.

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 readOnly/destructive annotations, it discloses the required permission scope (agent_actions:read), the surprising tenant-wide visibility (returns actions from all keys in the tenant, not just the caller), the newest-first ordering, and the audited write classes. This is exactly the kind of cross-cutting behavior an agent cannot infer from annotations.

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

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

Three sentences, front-loaded with purpose, then the differentiating value, then the auth/scope caveat. It is denser than strictly necessary — the annotation of audited write types could be trimmed — but every clause carries distinct information and 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?

Output schema is present so return values need no explanation; the description still covers the safety profile, required permission, cross-key scope, ordering, and pagination hint. For a 10-parameter, zero-required audit tool, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so each of the 10 parameters is already documented (ranges, defaults, filter semantics, pagination via next_offset). The description adds no syntax or format detail beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Return the tenant-wide audit log of changes agentcentral made') plus the exact write categories audited (bids, budgets, keywords, negatives, targets, states, listings). It also explicitly distinguishes itself from the sibling get_ads_change_history, so an agent can tell the two apart 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?

Names the concrete use case ('reconstructing what changed around a performance shift') and routes away from the alternative by explaining that Amazon's own change history (get_ads_change_history) omits API/agentcentral changes. The condition selecting this tool over the sibling is explicit.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds value by disclosing the default ad-type set and the shape of the result (overall status plus warnings/ineligibility reasons per ASIN/SKU), which goes beyond the safety profile covered by 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?

Three sentences, front-loaded with the core purpose and then the default behavior and return shape. It is efficient with essentially no wasted words, though it could be marginally tighter.

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 a 100%-covered schema, an output schema, and annotations carrying the safety profile, the description supplies enough context to invoke the tool correctly. Only the absence of explicit sibling routing keeps it short of fully complete.

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 all five parameters (including the carefully documented profile_id) are already explained in the schema. The description restates the ad-type default but adds no new format or constraint detail, so the baseline of 3 applies.

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

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

The description states a specific verb ("Check") and resource ("product eligibility for selected ad types"), making the tool's function immediately clear. It is distinguishable from the nearby sibling get_fba_eligibility by scoping to advertising eligibility, though it never explicitly names or contrasts a sibling.

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 explains the default behavior (SP, SB, SD, optionally DSP), which implies when the tool applies, but gives no explicit when-to-use vs when-not guidance or alternative tools (e.g., for FBA eligibility or listing restrictions). Usage is implied rather than 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds the aggregation grain (campaign + ad group) and a data-freshness caveat ('recent ~3 days may be incomplete') that the annotations do not convey. It stops short of describing result behavior, but that is partly covered by the output schema.

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

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

Two sentences, front-loaded with the use case, then exclusions. No filler, no restatement of the tool name, and the freshness caveat is placed adjacent to the grain it qualifies.

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 an output schema present, return values need no explanation, and the description still covers scope, grain, freshness, and routing. For an 11-param read-only reporting tool, nothing material is missing.

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

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

Schema description coverage is 100% across all 11 parameters, so pagination, date patterns, sort enums, and filter semantics are already documented. The description adds no parameter-level detail beyond echoing the metric list that maps to sort_by. Baseline 3 is appropriate when the schema carries the load.

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 ('drill') plus resource ('Sponsored Products performance ... from campaign to ad group') with the exact metric set (spend, sales, ACOS, ROAS, CTR, CPC, CVR) and grain. An agent can distinguish it from get_campaign_performance (coarser) and the keyword/search-term tools 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 exclusions with named alternatives: 'Do not use for bidded keyword/target or customer search-term analysis; use get_keyword_performance or get_search_terms.' Combined with the stated grain, the agent knows both when to reach for this tool and when to route elsewhere.

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

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

Annotations already establish read-only and non-destructive, but the description adds material behavior beyond them: the 90-day window, the exclusion of API-originated changes, the fact that the actor is not returned, and the omission of Sponsored Display. These disclosures directly affect whether an agent should trust an empty result.

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 highest-value caveat (typical emptiness for agent-managed accounts) is front-loaded, with alternatives and known gaps following in descending importance. Every sentence carries information an agent needs; nothing is redundant with 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?

For a read-only list tool with an output schema and full annotation coverage, the description supplies everything the agent needs: source scope, freshness window, expected emptiness, missing fields, and sibling routing. Nothing material 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 description coverage is 100% across all 15 parameters, including defaults and enum values, so the schema does the heavy lifting. The description adds no parameter-level detail such as date-bound defaults or pagination behavior, so the baseline of 3 applies.

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

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

States a specific verb+resource (returns Amazon console change-history events) and scopes it to Sponsored Products and Sponsored Brands via the Seller Central History tab. It explicitly names the sibling tools get_action_history and get_campaign_snapshots and the conditions that select each, so an agent can route without opening any schema.

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

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

Gives explicit when-to-use (console history, last 90 days), when-NOT (API or agentcentral changes never appear here, so it is typically empty for agent-managed accounts), and names two concrete alternatives with the exact conditions that select them (get_action_history for agentcentral changes, get_campaign_snapshots view=changes for any source).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds the Brand Registry authorization requirement plus the distinction that 'relations' returns authoritative assignments vs. 'coverage' returning factual assigned/missing rows. It says 'factual' and 'authoritative,' hinting at trust semantics, but does not discuss rate limits or freshness limits (which the schema partly covers).

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 and every clause carries information, with no filler. However the body is one dense semicolon-chained sentence, which is harder to scan than short discrete sentences would be.

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

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

For a 9-parameter read-only tool with an output schema and full schema coverage, the description covers the three modes and the Brand Registry prerequisite, which is what an agent needs to call it correctly. Return-format and pagination detail are handled by the output schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in the schema. The description restates the view semantics and emphasizes the content_reference_key must be exact, but adds little beyond what the schema fields already say. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Inspect A+ Content and Brand Story coverage') and then breaks the tool into its three named modes with what each returns. An agent can distinguish this from siblings like get_listing_quality or get_suppressed_listings 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?

The description effectively routes mode selection with 'view=... lists/returns/compares' clauses, and adds the hard precondition 'Requires Brand Registry.' It does not name an explicit alternative tool or a when-not condition, but the view-level context is clear enough for correct invocation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-annotated behavior: product fields are populated only for report_type=PRODUCTS while PERFORMANCE rows can leave them null, which tells the agent what to expect in the response shape. It stops short of addressing pagination or auth, but adds real value beyond the 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?

Three tight sentences, all front-loaded: purpose first, then the report_type nuance, then the exclusion/routing. No filler or restated title text.

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 an output schema present and 100% schema coverage, the description need not explain returns or parameter formats, and for a read-only list tool it covers scope, exclusions, and a key report_type behavior. Only minor gaps (pagination behavior, the compact vs raw row distinction) remain, and those are already in 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 description coverage is 100%, so the baseline is 3 and the schema already documents all 17 parameters including range, defaults, and enum values. The description's mention of product_asin/product_name/brand_name/marketplace refers mainly to report_type-dependent output fields rather than adding syntax or constraint meaning 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?

The description names a specific verb/resource domain (Amazon Attribution tagged off-Amazon traffic) and enumerates the metrics it returns (purchases, sales, brand halo, new-to-brand), which is far more than the title 'Attribution performance' conveys. It also distinguishes itself from on-Amazon ad and seller-sales tools, so the 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?

Explicit when-to-use ('Amazon Attribution tagged off-Amazon traffic') and explicit when-not ('Do not use for on-Amazon ads, search terms, or total seller sales'), with a routing hint toward campaign/search/sales tools. This is the clearest form of sibling disambiguation.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond that: the backing endpoint (targetableEntities/list), that taxonomy arrives in the 'category' field, that 'type' is often AUDIENCE, and that Amazon may omit name/provider/status/description.

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?

Two dense sentences, front-loaded with what the tool returns and its source, then the caveat about partial data. No filler, though the second sentence is packed to the point of being slightly hard to parse.

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 an output schema present and annotations covering safety, the description need not explain returns; it appropriately focuses on the data-quality caveat (omitted fields). Nothing critical for a correct call is missing, though sibling differentiation would make it fully complete.

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

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

Schema description coverage is 100%, including the deprecation note on segment_types and the profile_id guidance, so the schema carries parameter meaning. The description only restates 'optional text and category-path search' without adding syntax or format detail, so 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 and resource: 'Discover available Amazon Ads audience IDs for a profile from targetableEntities/list'. It is clearly distinct in kind, but it never distinguishes itself from any named sibling (no other audience-segment tool exists, but it also doesn't route away from e.g. get_dsp_entities_live).

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?

'With optional text and category-path search' implies how the tool is used, but there is no explicit when-to-use guidance, no when-not, and no alternative named. An agent gets the gist but must infer the triggering conditions.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world). The description adds genuine domain context beyond that: AWD snapshots do not expose FNSKU, and it is rolled into get_days_of_cover. It doesn't detail pagination or freshness behaviour, but the schema/annotations cover the rest.

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

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

Three sentences, front-loaded with the purpose and exclusion criteria, with no redundant wording. Every sentence contributes either scope, a limitation, or routing to the correct sibling.

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 snapshot tool with full schema coverage, complete annotations, and an output schema, the description covers purpose, exclusions, alternatives, and a key data limitation. Nothing an agent needs to call it correctly is missing.

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

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

With 100% schema description coverage, the schema fully documents all 8 parameters including defaults, ranges, and pagination guidance. The description adds no parameter-level syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The first sentence gives a specific verb, resource, and scope: raw AWD inventory snapshot with on-hand and inbound quantities per SKU. It explicitly distinguishes itself from siblings by naming get_fba_inventory and get_listing_registry with view='listings'.

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 when to use it (raw AWD snapshot), when not to (FBA fulfillable stock or ASIN-level identity), and points to the exact alternatives to use instead. It also notes inclusion in get_days_of_cover, which further clarifies routing.

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

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

Annotations already declare readOnlyHint, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds a useful default behavior ('Defaults to latest snapshot'), which is not in the annotations. However, it does not disclose pagination behavior, rate limits, or authentication needs beyond what annotations and schema imply.

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 three short, front-loaded sentences. It leads with what the tool does and then adds a use case and a default behavior. Every sentence earns its place with no wasted words.

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 rich input schema (100% coverage, 8 optional parameters), annotations covering the safety profile, and the presence of an output schema, the description is nearly complete. It covers purpose, a specific use case, and the default snapshot behavior. It does not mention pagination or filtering options, but those are adequately documented in 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 description coverage is 100%, so all parameters are fully documented in the input schema. The description mentions 'SKU' and 'quantity per shipment,' but these refer to output fields rather than adding meaning to the parameters. Baseline score of 3 is appropriate when the schema does the heavy lifting.

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 ('Get') and resource ('per-SKU line items from AWD shipments') and clarifies the output fields (SKU, quantity per shipment). It implicitly distinguishes from the sibling get_awd_shipments by focusing on line items rather than shipment-level data. However, no sibling is named 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?

The description provides a clear use case: 'Use to prorate AWD/AGL freight charges to specific ASINs.' This gives context for when to invoke the tool. It does not mention when not to use it or name alternative tools, but the intended scenario is explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond what the annotations and schema supply — no note on default result window, freshness, or how include_diagnostics/include_raw_rows change the response. Adequate but thin for a list tool with a default limit and date filters.

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?

Two sentences, zero waste: scope first, routing hint second. Nothing is repeated from the title or annotations, and the alternative is placed after the primary purpose.

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?

An output schema exists, so return values need no explanation, and the read-only safety profile is covered by annotations. The description covers scope and sibling routing but is silent on why 9 optional parameters matter (e.g., date filtering / pagination intended for large result sets), a minor gap for a tool with a default 20-row 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 description coverage is 100%, so all nine parameters (limit, offset, sort_by, sort_order, date range, status, raw rows, diagnostics) are documented in the schema itself. The description adds no formatting, default, or interaction semantics 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?

States a specific verb and resource ('Get AWD shipment-level data') and enumerates what is returned — shipment IDs, statuses, timestamps. It explicitly distinguishes itself from the closest sibling, get_awd_shipment_items, so an agent can route correctly 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?

Names the alternative tool and the condition that selects it ('For per-SKU quantities within a shipment, use get_awd_shipment_items'), which is exactly the routing decision an agent faces between the two AWD shipment tools. It gives no exclusions against the broader AWD/inbound family (get_awd_inventory, get_inbound_shipments), so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: it returns a recommended bid with a low/high range per keyword, and it discloses that SB only yields campaign-level CPC rather than per-keyword bids. It stops short of noting pagination/limits, but the value-add is real.

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 input requirements, then the return shape, then the SB alternative. Every sentence earns its place and there is no 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?

With an output schema present, the description needn't enumerate return fields, and it still summarizes them. Parameter context, the mutual-requirement constraint, and the sibling routing are all covered, so an agent has everything needed to invoke 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 description coverage is 100%, so the schema already documents asins, campaign_id/ad_group_id and the rest. The description restates the ASIN-vs-campaign/adgroup either/or constraint but adds no syntax, format, or default semantics beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (Get) plus resource (Amazon's suggested Sponsored Products keyword bids) and scope (Sponsored Products keyword bids). It explicitly distinguishes itself from the Sponsored Brands path via get_sponsored_ads_targeting_options, so an agent can route correctly 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?

Explicitly states the two valid input contexts (ASINs for a new ad group, or campaign_id + ad_group_id for an existing one) and names the alternative tool plus its parameters for the Sponsored Brands case. The when-to-use and when-to-use-something-else conditions are both present.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the metric set and the 'versus category peers' comparison angle, but says nothing about date-window semantics, freshness, or result volume beyond what the annotations/schema imply.

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 front-loaded sentence that packs the resource, the two scoping dimensions, and the metric list without waste. It is efficient, though the metric enumeration is dense and could have been trimmed in favor of routing 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?

With an output schema present, return values need not be described, and annotations carry the safety profile, so the description is adequate. The remaining gap is routing context against sibling performance tools, which the description never addresses.

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 all 12 parameters are already documented with ranges, defaults, and LIKE-match semantics. The description only alludes to brand and category scoping and does not add syntax or default behavior beyond the schema, 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 (Get) and resource (Amazon Ads Brand Metrics health), scoped by brand and category, and enumerates the metrics returned. It does not differentiate itself from siblings like get_share_of_voice, get_brand_search_terms, or get_campaign_performance, so an agent must infer the boundary.

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?

There is no when-to-use guidance, no indication of when this differs from adjacent Brand/campaign performance tools, and no noted prerequisites or caveats. The agent gets no routing help for choosing among the ~100 siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds meaningful behavioral context: bounded serving tables only, no raw-table fallback, no wildcard/substring scan, and a hard 42-day window. The mention of 'lookup_type and lookup_key prefix' references fields not present in the schema or the view enum, which is mildly confusing.

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

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

Three tight sentences: purpose first, then view routing, then constraints. Every sentence carries load, though the 'lookup_type and lookup_key prefix' phrase adds noise without a corresponding parameter.

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 an output schema present, return values need no explanation, and 14 parameters are fully covered in the schema. The description completes the picture with view requirements and the 42-day bound; the only gap is the unexplained 'lookup views' terminology that does not match the enum values.

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 every parameter is already documented individually; baseline is 3. The description adds cross-parameter conditionality (which view demands which of search_term/asin) and the date-span rule, but does not extend beyond what the schema largely establishes.

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 (Return) and resource (Amazon Brand Analytics Search Terms facts) and enumerates the three serving views with their grain, which an agent can map to the view parameter. It does not explicitly distinguish itself from the sibling get_search_terms, but the purpose is unambiguous.

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: top_terms for term-grain ranks, term_products requires one exact search term, asin_terms requires one exact clicked ASIN, plus the 42-day partition constraint and no-wildcard limitation. It lacks explicit when-to-use vs sibling search tools, but the within-tool routing guidance is strong.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-structured context: the data is near-real-time, the used/remaining budget values are estimates rather than finalized cost, and omitting ad_product still defaults to SP. These behavioral caveats exceed what the annotations 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?

Three sentences, front-loaded with the 'Use for' trigger, followed by the default-reset clarification and the estimation caveat. No filler or redundant restatement of the title.

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 tool with an output schema and full schema coverage, the description supplies the interpretive context an agent needs (near-real-time estimates, SP default, finalized-spend routing). Nothing critical is missing, though it could note the date-range/pagination behavior at a higher level.

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

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

Schema description coverage is 100%, so the schema already documents all 15 parameters including defaults and ranges. The description only reinforces the ad_product default (SP), adding marginal meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('budget usage and pacing snapshots') and names the exact scope it covers (SP, SB, SD) plus the derived fields produced (usage percentage, estimated used and remaining budget by campaign). An agent can distinguish it from finalized-spend siblings like get_campaign_performance without opening the schema.

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

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

It opens with an explicit use case ('Use for SP, SB, or SD budget usage and pacing snapshots') and adds a negative directive routing finalized spend to 'retained campaign performance.' Clear context and an exclusion are present, though the sibling tool is named descriptively rather than by exact tool name.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds what the payload contains (recommended budgets, estimated missed metrics), which is useful but does not disclose batching limits, freshness, or auth/profile requirements.

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 front-loaded sentence that names the resource and enumerates the returned metrics with no filler. It could be tightened slightly but nothing is wasted or buried.

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 an output schema present, return values need no explanation, and the schema covers all four parameters. What is missing is the routing context an agent needs to pick this over the closely named budget/pacing/bid-recommendation siblings.

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 profile_id scoping, the 1-100 campaign_ids bound, and both toggle flags are already documented in the schema. The description adds no parameter-level meaning beyond that, which is the baseline-3 case.

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

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

States a specific verb (Returns) and resource (Amazon Ads budget recommendation API fields) plus the concrete outputs (suggested budgets, estimated missed impressions/clicks/sales). That is enough to distinguish it from get_bid_recommendations and get_budget_pacing, though it never names those siblings to sharpen the boundary.

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?

No indication of when to reach for this tool versus get_budget_pacing, get_bid_recommendations, or get_campaign_performance. The agent gets no context, prerequisites, or exclusions, only a statement of what comes back.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds meaningful context beyond them: live mode is one of several buyability signals rather than a complete answer, your_price is only populated when you hold the Buy Box, your_price_basis explains nulls, and used/Grade & Resell offers are reported elsewhere. It does not disclose rate limits, auth/token requirements, or freshness lag for the stored snapshots, leaving a modest 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?

Four sentences, front-loaded with the live/history distinction, and each sentence carries distinct information (mode selection, Buy Box definition, field semantics, sibling pairing). The final sentence is long and dense with three sibling references, but nothing is redundant padding.

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

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

With an output schema present, return-value explanation is not required, and the description still covers the genuinely ambiguous parts: mode selection, the meaning of null your_price, and how this tool composes with adjacent eligibility/restriction tools. Pagination and result-size handling are left entirely to the schema, which is acceptable given coverage, though a note on live-mode latency or ASIN batching would have made it airtight.

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 parameter descriptions already document every field, including that start_date triggers history mode and how limit/offset paginate. The description corroborates the mode-switch semantics but adds no format, default, or syntax detail beyond what the schema states, 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 names a specific verb and resource ('Check current Buy Box status for ASINs') and then explicitly delineates the two operating modes (live SP-API vs. stored date-window history). It also scopes terminology ('The Buy Box is Amazon's New Buy Box') and clarifies that used offers live in separate used_buy_box_* fields, so an agent can distinguish this from sibling offer/pricing tools without opening a schema.

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

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

It specifies the condition that selects history mode ('provide a date window') and explicitly recommends pairing with get_listing_restrictions, get_fba_eligibility, and get_suppressed_listings for a full buyability check, which is strong routing guidance. It stops short of naming a sibling to avoid (e.g. get_listing_offers or get_competitive_pricing) or stating when this tool is the wrong choice, so it is clear but not fully exclusionary.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description still adds real behavioral context beyond them: the row grain ('one row per campaign') and the freshness caveat that the recent ~3 days may be incomplete, which is exactly the kind of data-quality caveat an agent needs before reporting numbers.

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

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

Three sentences, zero filler, and front-loaded: purpose and metric set first, then grain and freshness caveat, then the exclusion list. Every clause earns its place and there is no restatement of the name or title.

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?

An output schema exists, so return shape needn't be explained, and pagination is covered in the schema. The description supplies the two things structured data doesn't: grain and a freshness/data-window caveat. Complete enough to call correctly, though it doesn't note whether historical backfill limits apply.

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 all ten parameters (dates, sort_by, limit/offset, filters) are already documented in the schema. The description adds metric vocabulary and the date-range framing but no parameter-specific syntax or defaults. Baseline 3 is correct when the schema carries parameter meaning.

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

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

States a specific verb+resource+scope: Sponsored Products campaign-level performance over a date range, with the metric set enumerated. The 'campaign-level' grain plus the Sponsored Products qualifier cleanly separates it from siblings like get_adgroup_performance, get_sb_campaign_performance, and get_sd_campaign_performance.

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 when/when-not routing: 'Do not use for ad group, keyword, search-term, ASIN, or total organic+paid sales questions' names the near-miss siblings by dimension. Combined with the opening 'Use for...' clause, an agent can select or reject this tool without opening any schema.

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

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

Annotations already declare readOnly/openWorld=false/destructive=false, so safety is covered; the description adds substantive behavior beyond that: it is not a live write readback, changes are detected regardless of console vs API origin, and the changes view requires two snapshots to produce a delta. It stops short of auth requirements or freshness/latency specifics, so it is strong but not exhaustive.

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 'Use for...' and every sentence carries information (purpose, view semantics, caveat, exclusions). It is dense — three long sentences with parentheticals — but no clause is padding, just slightly heavier than strictly necessary.

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

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

With 14 parameters, an output schema present, and annotations covering the safety profile, the description supplies everything else an agent needs: purpose, view routing, data freshness caveat, and explicit exclusions (no metrics, no live write readback). Return values are correctly left to 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema for the key 'view' parameter by explaining what each mode returns at a data level (state, budget, bidding, portfolio, placement bid adjustment) and how the changes mode behaves. The two-day delta caveat is operational semantics not present in 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 ('Sponsored Products campaign settings snapshots from the campaign_snapshots sync') and immediately distinguishes itself from the sibling performance tools by declaring what it does not return. An agent can separate it from get_campaign_performance and get_sp_entities_live 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?

Explicitly routes between the two views (history = daily state rows; changes = deltas) and names the alternative to use for metrics ('use get_campaign_performance for metrics'). It also states the precondition for the changes view ('needs at least two days of snapshots to show a delta'), which is a genuine when-to-use constraint.

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

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

Annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), lowering the bar. The description adds useful context that the data comes 'from snapshots' and is 'ranked', but says nothing about snapshot freshness, whether output is paginated, or the cost of pulling raw rows (include_raw_rows defaults true).

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, front-loaded sentence with no filler, leading with the action and the sources of signal. It could be slightly tighter and omits any usage sentence, but nothing is 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 an output schema present and all 8 params optional/defaulted, the description needn't explain returns, and annotations cover safety. However, it omits the relationship to get_listing_quality and get_suppressed_listings and offers no guidance on snapshot_date behavior, which matters for a snapshot-driven 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 description coverage is 100%, so the schema already documents all 8 parameters and their defaults, hitting the baseline of 3. The enumerated signal categories loosely mirror the cleanup_focus enum, adding marginal mapping value, but the description supplies no syntax or behavioral detail 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 ('Returns') and resource ('ranked listing quality signals from snapshots') and enumerates five concrete signal categories (Amazon errors, warnings, missing core content, offer/fulfillment gaps, thin content). It is clearly distinguishable in content from generic listing tools, though it never names the closest siblings (get_listing_quality, get_suppressed_listings) to draw the boundary 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?

The description gives no when-to-use guidance, no exclusions, and no routing to alternatives despite a crowded listing/quality sibling set. An agent must infer that this is the cleanup-triage tool from its name and signals alone.

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/openWorldHint/destructive=false, so the safety profile is covered. The description adds genuine value beyond them by disclosing the data source and freshness (live SP-API vs daily stored snapshots), which the annotations cannot express. Minor gap: no mention of rate limits or freshness lag.

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?

Two sentences, front-loaded with the core action and followed immediately by the mode switch. No filler or restated title text; every clause earns 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 an output schema present, return values needn't be explained, and the description adequately covers the live-vs-history decision for this 7-param tool. It could say more about scoping limit/offset to history mode, but nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so every one of the 7 parameters is already documented in the schema. The description only adds that date parameters toggle history mode; it doesn't clarify that limit/offset apply in history mode or explain include_diagnostics/include_raw_rows beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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 ('Get competitive price points for ASINs') and explains the dual live/history behavior, so the agent knows exactly what it retrieves. It does not, however, differentiate itself from any of the many adjacent pricing siblings (get_listing_offers, get_current_rank, get_offer_listings), so it stops short of a 5.

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 clear mode-selection context: omit dates for live SP-API data, provide a date window for stored snapshot history. That routes the agent correctly between the two behaviors. It stops at 4 because it offers no guidance against overlapping siblings and no explicit exclusions.

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, destructiveHint=false and openWorldHint=true, so the safety and external-call profile is covered. The description adds that the lookup is live against Amazon's catalog (freshness/latency implication) and that a target ASIN gets its position highlighted, but says nothing about rate limits, throttling, or what happens when no results are returned.

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

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

Three short sentences, the live/real-time qualifier and the core action are front-loaded, and nothing is padded. The middle sentence about returning top results from Amazon's catalog partly duplicates what the output schema conveys, a minor 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?

With an output schema present and rich annotations, the description need not explain return values or safety. It covers the live-query nature and the ASIN-highlighting behavior, which is sufficient for correct invocation, though it omits any note on result limits or noisy-data conditions the diagnostics flags imply.

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 all five parameters including max_pages, include_raw_rows and include_diagnostics are already documented in the schema. The description only restates target_asin's highlight behavior, adding no format, default, or interaction detail 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 and resource — check the current search rank position for a keyword — and the 'real time' framing implicitly contrasts with the historical sibling get_keyword_ranks. It never names that sibling, so the differentiation is left to inference rather than made explicit.

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 implied by 'in real time', suggesting this is the tool for a live rank snapshot rather than batch/historical reporting. There is no explicit when-to-use statement, no exclusion, and no pointer to get_keyword_ranks or get_sales_ranks when a live query is not what the agent wants.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds substantial behavioral context beyond that: the Sales & Traffic vs. FBA Inventory Health velocity fallback, source attribution, finalization-lag exclusion of not-yet-due dates, and the rule that AWD on-hand is excluded from the numerator. It does not, however, describe pagination or result-shape behavior, so 4 rather than 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?

Purpose is front-loaded in the first clause and the routing instruction is cleanly placed at the end. The middle source-selection sentence is a dense run-on that packs three clauses (fallback, lag exclusion, lookback sizes), which hurts readability slightly but each clause carries real 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?

With an output schema present, the description need not explain return values, and it covers what the schema cannot: data-source provenance, fallback behavior, AWD treatment, sort order, and sibling routing. For a 10-param read-only analytics tool this is a complete briefing.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters (sku, asin, limit, offset, sort_order, filters, lookback). The description reinforces a few semantics (lookback values 7/30/60/90, sort ordering) but adds no syntax or format detail beyond the schema, 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 precise verb and resource ('replenishment coverage: days of stock remaining') and even gives the computation (FBA fulfillable + FBA inbound divided by recent FBA sales velocity). It names the sibling tools it is not (get_fba_inventory/get_inventory_health/get_inventory_risk_triage), so an agent can distinguish it 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?

Contains explicit exclusions ('Do not use for raw stock counts, aged inventory fees, or broad triage') paired with the named alternatives to use instead. It also sets the positive condition (per-ASIN/per-FBA-SKU replenishment coverage). This is textbook when/when-not routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds genuine context about Amazon-side access scoping ('Amazon grants access', 'accessible to an Ads profile'), but says nothing about pagination, rate limits, or freshness behavior for a live external API, so it adds only moderate value.

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?

Two sentences, zero padding, and the payload-routing guidance (use the returned IDs for the Amazon-Ads-AccountId header) is front-loaded rather than buried.

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?

An output schema exists, so return-shape explanation is correctly omitted, and all parameters are self-documented. The remaining gap is operational: no note on default result sizing or whether the list is paginated, which matters for a live open-world discovery call.

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 all five parameters (including limit, profile_id, advertiser_id, and the two include_* flags) are already fully documented in the schema. The description adds no syntax, format, or interaction detail beyond that, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource ('Return Amazon-source DSP advertiser records') and scopes it to records 'accessible to an Ads profile.' It also explicitly frames the tool as a discovery step for IDs consumed by get_dsp_entities_live, so an agent can separate it from that sibling 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 gives explicit usage context ('Use this to discover DSP advertiser IDs for the Amazon-Ads-AccountId header used by get_dsp_entities_live'), naming the downstream alternative and the ordering dependency. It stops short of stating when NOT to use it (e.g., when IDs are already known), which keeps it from a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description reinforces this ('returns factual source fields only; no DSP writes are exposed') and adds the required-auth context (explicit advertiser ID), which is useful beyond the annotation defaults, though no return format or rate-limit details are offered.

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?

Two sentences that front-load the verb and resource, with the prerequisite and scope following. Efficient overall, though the second sentence packs several distinct facts (auth header, read-only scope) into one clause chain.

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?

An output schema exists, so return-value detail is unnecessary, and annotations carry the safety profile. The description supplies the key missing context—required advertiser ID and read-only scope—making it 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 100%, so the schema already documents all 13 parameters in detail (including DSP-specific constraints like target_ids/ad_group_ids requirements). The description adds no parameter syntax or meaning beyond naming the account ID, so baseline 3 is appropriate.

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

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

States a specific verb ('List') and resource ('Amazon-source DSP campaigns, ad groups, or targets') scoped to 'DSP v1 campaign-management read endpoints,' which cleanly separates it from siblings like get_dsp_performance (metrics) and get_dsp_advertisers_live (advertiser discovery).

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 prerequisite (an explicit Amazon-Ads-AccountId DSP advertiser ID) and scopes usage to read endpoints with 'no DSP writes are exposed.' It does not, however, explicitly contrast when to use this versus entity-listing alternatives such as get_dsp_performance.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the reporting grain and metric scope but says nothing about freshness/latency of the data, row limits, or pagination behavior beyond what the schema documents. With annotations carrying the safety burden, this meets the lower bar but adds only modest extra 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?

Two tight sentences: the positive scope comes first, the exclusions and routing second. Every clause earns its place, with no restating of the name or title.

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

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

For a 13-parameter read-only reporting tool with a full output schema, the description supplies the scope, grain, and routing needed to select and call it correctly. Minor gap: no note on default date window behavior at the description level, though the schema and output schema cover the rest.

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% – every one of the 13 parameters, including the date defaults, LIKE-match filters, and diagnostics flag, is documented in the schema. The description adds no parameter-level detail (e.g., how order_name interacts with the grain), 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 (reporting on) and resource (Amazon DSP Reporting v3 performance) plus the grain (order, line item, creative) and the metrics returned (spend, sales, ROAS, viewability, video completion). This distinguishes it cleanly from sibling ad-reporting tools like get_sb_campaign_performance or get_sponsored_ads_report.

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 covers both when to use (DSP performance by order/line item/creative) and when not to use it, calling out Sponsored Products/Brands/Display, search terms, and seller account sales as out of scope, then routing to 'the matching ads or sales tool'. Nothing is left to inference about tool selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds useful context: it is live SP-API data, returns eligibility status and Amazon ineligibility reason codes, and belongs to a specific signal family. Auth and rate-limit behavior are not disclosed, but the annotation coverage lowers the bar.

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?

Two sentences, front-loaded with the core purpose and then the usage context. Every sentence earns its place with no redundant or vague phrasing.

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 a full schema, output schema, and informative annotations, the description completes the picture by stating live behavior, return content, and sibling pairing. Nothing an agent needs to invoke 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 description coverage is 100% and all four parameters are documented in the schema, so the description adds no parameter semantics beyond it. It mentions the ASIN concept but nothing about the program enum or include_raw_rows/include_diagnostics toggles. Baseline 3 is appropriate.

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

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

States a specific verb (check eligibility), resource (ASIN for FBA), and scope (live SP-API), and explicitly distinguishes itself as one of the buyability signals alongside named siblings. An agent can pick this 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 tells the agent to pair this with get_buybox_status, get_listing_restrictions, and get_suppressed_listings for a full buyability check, effectively naming alternatives and the condition that selects each. This is precise routing 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?

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), and the description adds substantial behavioral context beyond them: links stream from Amazon, expire after 15 minutes, and document bytes are never returned inline. This expiry/streaming detail is exactly the kind of operational trait an agent needs and is not present in the 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?

Three tightly written sentences, front-loaded with what the tool returns before the expiry and prerequisite caveats. No filler sentences. A minor density cost from packing expiry, streaming, and confirmation-ID caveats into one long second sentence keeps it from a 5.

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

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

An output schema exists, so return values needn't be described, and the safety profile is already carried by annotations. Given that, the description covers the remaining gaps an agent needs — link lifetime, delivery mechanism, and which document types require the confirmation ID — making it complete for a link-generation 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 description coverage is 100%, so every one of the 12 parameters is already documented in the schema, including the conditional 'Required for carton_labels, pallet_labels...' notes. The description largely restates these document-type groupings and adds no format or syntax detail beyond the schema, 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 states a specific verb+resource (download links for FBA inbound shipping documents) and enumerates the exact document types covered: item labels, carton labels, pallet labels, BOL, delivery challan. It is unambiguous what the tool returns. However, it never names or differentiates itself from adjacent siblings such as get_report_document or get_inbound_shipments, so it earns a 4 rather than a 5.

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 prerequisite context: carton/pallet labels and BOLs require the shipment's FBA confirmation ID, which only exists after placement confirmation, effectively telling the agent when the call will and won't work. It does not, however, point to any alternative tool or state exclusions relative to siblings, so it stops short of the explicit when/when-not routing a 5 requires.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real behavioral value beyond that: the tri-state outcome model and the distinction between Amazon's blocking (ERROR) and non-blocking (WARNING) problems, which an agent needs to interpret results.

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?

Two sentences with zero filler: the core purpose and outcome states are front-loaded, followed by the usage condition. Both sentences earn their place.

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

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

With an output schema present, return values need not be explained, and annotations cover safety. The description supplies purpose, state semantics, error classification, and usage, so it is nearly complete; only the two optional parameters lack description-level coverage, which the schema handles adequately.

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 adds provenance for operation_id ('returned as operation_id by inbound write tools'), but says nothing about include_raw_rows or include_diagnostics, leaving those entirely to 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 and resource ('Status of an asynchronous FBA inbound operation') and enumerates the exact return states (SUCCESS, FAILED, IN_PROGRESS). This clearly distinguishes it from sibling inbound tools like get_fba_inbound_plan, get_fba_inbound_options, and get_fba_inbound_documents.

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 resume a write that returned processing instead of re-submitting it,' which gives strong when-to-use context and an implicit alternative action (re-submitting). It doesn't name an alternative tool or a when-not condition, keeping it just short of a 5.

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

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

Annotations already declare readOnly/non-destructive/openWorld, so the bar is lower; the description still adds real context by confirming nothing is committed ('without selecting one'), noting that all pages are returned, and disclosing that transportation quotes carry expiration and void deadlines while self-ship appointments are only available 'where Amazon supports them'. Permission/auth requirements and empty-result behavior are not covered in the description.

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?

Two sentences, front-loaded with the essential read-only framing and back-loaded with the option-family inventory. The long enumeration is dense but each clause earns its place by distinguishing output families; the trailing prerequisite sentence is slightly detached from the opening.

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 an output schema present, return shapes need not be explained, and the description still usefully previews the option families. It covers the generation prerequisite, the no-selection guarantee, and pagination, leaving only auth/permission prerequisites and error/diagnostic behavior 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 100%, so the baseline is 3, but the description goes further by mapping each option_type family to the payload it yields (packing fees, placement per-split fees/discounts, transportation carrier/mode/quote, delivery window validity, appointment slots), which tells an agent what to expect from the enum choice. It does not add anything about shipment_id scoping or the packing_group_id/placement_option_id refinements beyond what the schema already documents.

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?

Starts with a specific verb and resource ('Read Amazon-generated FBA inbound options') and immediately scopes them ('without selecting one'), then enumerates the four-to-five option families the tool returns. It also names the generator sibling (prepare_fba_inbound_options), so an agent can separate reading from generating 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?

Clear context: this is the read-only inspection step, and options must exist first via prepare_fba_inbound_options, which is an explicit prerequisite. It does not state when to prefer this over sibling readers such as get_fba_inbound_plan or get_fba_inbound_operation_status, so routing among the reading tools is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses that shipment detail returns two distinct identifiers, that view=boxes carries case dimensions/weights/units, and that Seller Central saved templates are not API-readable, which shapes how an agent should source defaults.

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

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

The core purpose is front-loaded in the first two sentences, and the remaining sentences each earn their place by covering views, identifiers, reuse, and alternatives. It is dense but not padded; slightly more length than strictly necessary for a summary line.

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 an output schema present, annotations supplying the safety profile, and 100% parameter coverage, the description fills the remaining gaps: it covers all five view modes, the two-identifier return for shipments, and the repeat-shipment reuse pattern. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description exceeds it by explaining semantics the enum descriptions don't: what view=summary yields in create_fba_inbound_plan input shape, what view=boxes carries, and how shipment_id scopes results, adding practical meaning to the enum values.

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

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

The description states a specific verb and resource (live FBA inbound plan state), pins the backing API and version, and enumerates exactly what each view returns (plans, summary, items, boxes, pallets, shipments). It distinguishes itself from the materialized-progress siblings, so an agent can pick it without opening the schema.

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

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

It routes the agent explicitly: use get_inbound_shipments and get_shipment_receiving_status for materialized receiving progress, and use this tool's summary/boxes views for reusable defaults on repeat shipments. Context is clear but there is no explicit 'when not to use' for the listing mode beyond the sibling redirect.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: it defaults to the latest snapshot and discloses that future supply fields are Amazon source-provided In-Stock Head Start values that remain null when unavailable. It stops short of describing pagination or multi-snapshot behavior, but the null-field caveat is a meaningful disclosure.

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

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

Front-loaded with the 'Use for...' purpose, followed by data-quality nuance and the routing exclusion. Every sentence carries information, though the metric enumeration in the first sentence is dense. No filler or repetition of the title.

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 an output schema present, the description need not explain return values, and it correctly focuses on scoping, defaults, null semantics, and sibling routing. For a 9-parameter, no-required-parameter tool it is nearly complete; only snapshot-history behavior is left implicit.

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 every parameter is already documented (sku, asin, limit, offset, sort_by, sort_order, snapshot_date, include_raw_rows, include_diagnostics). The description reinforces ASIN/SKU scoping and the latest-snapshot default but adds no syntax or constraint detail beyond the schema, which is precisely the baseline-3 case.

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

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

States a specific verb and resource ('raw FBA inventory snapshot quantities per ASIN/SKU') and enumerates the exact metric families returned (fulfillable, reserved breakdowns, inbound, future supply, researching, unfulfillable). It also names the siblings it is not (get_days_of_cover, get_inventory_risk_triage), so an agent can distinguish it from the many other inventory tools 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?

Explicitly states an exclusion with the reason: 'Do not use alone for reorder or stockout priority; use get_days_of_cover or get_inventory_risk_triage.' This gives both the when-not and the named alternative, which is the strongest form of routing 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: the two report families, the ASIN/FNSKU/SKU grain, and an explicit scope limit on AWD fees. It stops short of describing pagination flow or date-window behavior, though the schema and output schema cover those.

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?

Two sentences, no filler, and the scope boundary is front-loaded after the core purpose. The grain and variant enumeration are dense but each 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?

With 14 well-documented parameters, full annotations, and an output schema, the description covers what is missing: what the tool returns, at what grain, and what it deliberately excludes. A brief note on how the two views differ in date semantics would close the remaining gap, but nothing an agent needs to call it is absent.

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 reinforces the monthly vs long-term split and the reporting grain, but the view-specific defaults and date constraints are already fully documented in the schema, so it adds little beyond it.

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

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

Names a specific verb (returns) and resource (FBA storage fee report rows), states the grain it returns (ASIN/FNSKU/SKU), and enumerates both report variants. It also draws an explicit boundary ('This is FBA only; AWD fee reports are not exposed'), which distinguishes it from AWD siblings like get_awd_inventory.

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 clear which view yields which report family and implicitly steers the caller by naming what is not covered (AWD fees). However, it never names an alternative tool for adjacent needs (e.g. product fee estimates, financial events, profitability review), so routing vs siblings is left to the agent.

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

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

Annotations already establish this as a safe read, and the description piles on genuinely useful behavior: what profitability excludes (ad spend, FBA storage, inbound freight, COGS, Adjustment/ServiceFee events), how MCF fees are segregated from total_fees/net_profit, the posted_date vs order-date distinction, data_gap flags, and the currency-mixing hazard of include_all_currencies.

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 appropriately front-loaded, but the body is a single dense block with reconciliation caveats, exclusion lists, and cross-references interleaved rather than grouped. Nearly every clause carries information, yet the flat structure makes it hard to scan for the one or two facts an agent needs for a given call.

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

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

For a 13-parameter, multi-mode read tool with an output schema and full annotation coverage, the description supplies the scoping, exclusion, reconciliation, and currency semantics an agent needs to interpret results correctly. The remaining mechanics (sort columns, pagination offsets) are already handled by the schema and need no restatement.

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 each parameter is already documented, so the baseline is 3; the description goes beyond it by explaining the view/grain interaction (grain only matters when order_id is omitted), the meaning of include_all_currencies summing risk, and which money fields each view emits. It does not add format or syntax detail for the date/pagination params, 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?

The description names the specific resource (Finances v0 financial-event rows plus ASIN economics) and enumerates the two views and three grains, so an agent can tell exactly what the tool returns. It also explicitly disambiguates from siblings by naming get_payment_transactions and get_settlement_economics with the conditions that select them.

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 when each mode applies ('view=fee_breakdown' with order_id vs date-range grains; 'profitability' for ASIN economics) and gives explicit when-not routing: pre-settlement rows go to get_payment_transactions and finalized settlements to get_settlement_economics. Alternatives and their selecting conditions are spelled out rather than 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?

With readOnlyHint/destructiveHint/openWorldHint already declaring a safe read, the description still adds substantial context: snapshot_date is the last-refresh date, created_at is a best-effort inference from shipment_name with created_at_source flagging it, ambiguous or future dates return null rather than a wrong value, and no per-shipment received/closed timestamp exists. The account/region-level scoping caveat (no native marketplace) is also 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?

Front-loaded with the tool's purpose before the caveats, and every sentence carries actionable information with no filler. It is dense and somewhat long, but that length is justified by the data-model quirks it must convey.

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 9-parameter read tool with an output schema and annotations, the description covers the remaining burdens: what fields are returned, how inferred dates behave, sibling routing for related timestamps, and marketplace scoping. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description genuinely enriches semantics — it clarifies that snapshot_date is the reliable refresh date while created_at is inferred, and that created_at_source identifies the inference, which the schema alone does not convey. It does not add meaning for limit/offset/sort_order beyond the already-complete 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 (Get) and resource (FBA inbound shipment data) and enumerates the returned fields — shipment IDs, statuses, destination fulfillment centers, refresh dates. It also distinguishes itself from related siblings by naming get_inventory_movements and get_shipment_receiving_status, so an agent can place it precisely in the toolset.

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 elsewhere when the needed data is not here: use get_inventory_movements with event_type=Receipts for receipt timing, or get_shipment_receiving_status for shipped-vs-received quantities per SKU. Both the condition and the alternative are stated, which is the strongest form of usage 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial context beyond them: the upstream source (Inventory Ledger Summary View, aggregateByLocation:FC), the default snapshot behavior, and the crucial caveat that ledger data is account/region-level with rows surfacing tenant-wide and anchored to the primary marketplace. That marketplace scoping caveat is genuinely useful behavioral disclosure for an agent.

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 result shape, then routing and provenance. Dense but each sentence carries distinct information (scope, fields, alternative, source, marketplace caveat). Slightly packed, but 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?

Though an output schema exists (so return values needn't be explained), the description still covers the operationally important gaps: default snapshot date, the FC-vs-FBA routing decision, and the tenant-wide/primary-marketplace scoping caveat. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters, establishing a baseline of 3. The description adds marginal value by echoing FC code format and snapshot defaulting, but does not add syntax or semantics beyond what the schema provides.

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 ('Per-fulfillment-center on-hand inventory') and enumerates exactly what is returned: ending warehouse balance per ASIN, SKU, FC code, and disposition plus the day's signed flow components. It also names the sibling it is not (get_fba_inventory), so an agent can route 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?

Gives an explicit selection rule: 'Use this — not get_fba_inventory — when the user asks about FC-level, per-warehouse, geographic, or geo distribution of inventory.' Both the when and the alternative are stated, leaving nothing to inference.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely non-obvious behavior: synthetic/placeholder SKUs are filtered out by default, and rows carry an is_synthetic flag. It does not discuss row volumes, snapshot staleness, or rate limits, but what it adds beyond the annotations is real.

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

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

Three tightly packed sentences: output scope first, then the one non-obvious default with its override, then sibling routing. No filler, no restatement of the title, and the most decision-relevant content is front-loaded.

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?

An output schema exists, so return-value explanation is unnecessary, and annotations cover the safety profile. Combined with the default-filtering disclosure and explicit sibling routing, an agent has everything needed to select and invoke this tool correctly without further context.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema on the least self-explanatory parameter by defining what 'synthetic' SKUs actually are (reimbursement placeholders) and naming the is_synthetic flag, which the schema only gestures at with an example.

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

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

The first sentence names a specific verb and resource (FBA inventory health snapshot) and enumerates the exact fields returned: age buckets, capped weeks of cover, storage fee risk, sell-through, and Amazon recommended order quantity. It explicitly distinguishes itself from two named siblings, so an agent can differentiate 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 routes explicitly: get_fba_inventory for raw stock counts, get_inventory_risk_triage for cross-signal risk rankings. It also tells the agent when to flip include_synthetic_skus (only when reimbursement placeholder rows are wanted), which is an actionable when-to-use rule rather than an implied one.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds genuinely non-obvious behavior: ledger rows are account/region-level with no native marketplace, surface tenant-wide for any marketplace-scoped key, and anchor to the tenant's primary marketplace, plus a UTC timestamp note. This is valuable context the annotations cannot convey, though it doesn't discuss result volume or freshness limits beyond the schema's diagnostics flag.

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

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

Three sentences, front-loaded with the tool's purpose followed by the join semantics and the marketplace caveat. It is dense and jargon-heavy but every sentence carries distinct information; no filler or restatement of the name.

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

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

An output schema exists, so return-value explanation is not required, and the description covers the unusual scoping semantics an agent would otherwise get wrong. All 11 parameters are optional filters documented in the schema. The only minor omission is any note on default row limits or how to page, though the schema's limit/offset descriptions handle this.

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 goes further by explaining the meaning of reference_id and date_and_time — fields surfaced by the ledger that clarify how event_type filters behave and what the returned rows represent — which adds semantics beyond the schema's terse property 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?

States a specific verb and resource ('Get inventory ledger movements') and enumerates the covered event types (shipments, receipts, adjustments, customer orders, returns) plus filterable dimensions. This distinguishes it clearly from siblings like get_fba_inventory, get_inventory_by_fulfillment_center, or get_returns without needing to open their 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?

The description gives a concrete usage pattern — joining Receipts events to get_inbound_shipments via shipment_id to compute created-to-received time — which is real guidance. However, it never states when to choose this ledger over adjacent tools such as get_fba_inventory or get_returns, so the when-to-use decision is only 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 already declare readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the risk scores share a coverage definition with get_days_of_cover (important for consistency), and it discloses the output grain. Return format is deferred to the existing output schema, which is acceptable.

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

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

Three dense sentences with no filler, front-loading what is returned before the exclusions. Slightly overpacked in the first sentence (four data domains plus a cross-reference plus grain), 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?

For a 10-param read-only tool with an output schema and full annotation coverage, the description supplies the essentials: scope, grain, distinguishing cross-reference, and misuse exclusions. It does not explain how the risk_focus categories interact with the day thresholds, but that gap is minor given the schema detail.

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% across all 10 parameters, including defaults, ranges, and clamping behavior, so the schema does the heavy lifting. The description mentions days-of-cover and risk scores conceptually but adds no syntax, units, or interaction details beyond what the schema already documents. 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 ('Returns ranked inventory risk signals') and enumerates the domains covered: FBA/AWD stock, sales velocity, inventory health, and suppressed listings. It also declares the grain (ASIN/SKU risk rows), which lets an agent distinguish it from siblings like get_fba_inventory, get_inventory_health, and get_days_of_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 excludes two misuse cases ('raw snapshots or movement audit') and points to alternatives. The guidance is clear but the alternatives are described by category ('inventory snapshot or ledger tools') rather than by exact sibling names, so an agent must still map those to get_fba_inventory or get_inventory_movements itself.

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