Amazon Seller Central and Ads data for AI: account health, FBA inventory, reimbursements, keywords.
Scored across 23 tools
Most tools are cleanly separated by domain—sales, ads, inventory, health, keywords, reimbursements, compliance—and paired tools like get_reimbursements/get_recoverable_reimbursements explicitly cross-reference each other. However, get_sales vs get_orders_summary and get_campaigns vs get_campaign_detail could still be confused at a glance.
The dominant get_<domain>_<detail> snake_case pattern is predictable and readable. The exceptions—fetch, find_campaign, search, search_vault—are understandable but break the otherwise consistent verb_noun convention, and 'fetch' is notably generic.
23 tools is on the heavier side, but the broad Amazon-seller scope—health, ads, sales, inventory, keywords, reimbursements, compliance, documents—mostly justifies the count. A few tools could be consolidated, but none feel purely redundant.
The server offers strong read-side coverage across most seller insight domains, including paired views like received vs recoverable reimbursements and summary vs detailed sales. The main gap is the lack of write/action tools—approve, reject, update, or create—though the descriptions suggest this is intentionally an observational surface.
Fetch a record returned by search, by its id: its main fields as plain text (case details, status, dates).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document id from search (e.g. "poa:<uuid>"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation is read-only and non-destructive. The description adds meaningful behavioral detail by stating the response is 'plain text' and limited to 'main fields' such as case details, status, and dates, which goes beyond what the annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence that front-loads the core purpose and includes the most relevant output details. There is no wasted 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?
For a simple read-only tool with one fully documented parameter and no output schema, the description adequately explains what it returns and where the id comes from. Nothing essential is missing for an agent to use 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?
The single parameter is fully documented in the schema, including the id format example 'poa:<uuid>'. The description only restates that the id comes from search, adding no significant meaning beyond the schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Fetch') and resource ('a record returned by search'), and clarifies the scope by id. It clearly distinguishes this from the many sibling get_* tools by anchoring it to search results.
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 phrase 'returned by search' implies this tool should be used after a search operation, which provides some usage context. However, it does not explicitly state when not to use this tool or mention alternatives, leaving the guidance at the implied level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a campaign exactly from the full synced campaign table.
| Name | Required | Description | Default |
|---|---|---|---|
| asin | No | Optional advertised-ASIN filter; never an implicit campaign choice. | |
| name | No | Exact campaign name first; otherwise returns bounded name candidates. | |
| limit | No | Candidates per page (default 20, max 25). | |
| state | No | ||
| cursor | No | Opaque continuation cursor returned by a prior call. | |
| campaignId | No | Exact SellerForge ad_campaigns UUID. |
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 that the data comes from the 'full synced campaign table,' but does not disclose candidate/pagination behavior, return shape, or what happens on no match. Given annotations carry the safety burden, this is adequate but not rich.
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 a single, front-loaded sentence with no filler. It conveys the main purpose and exactness in minimal words, earning every character.
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 six optional parameters and no output schema, the description is minimal but not inadequate: the schema compensates for parameter semantics. However, the description does not explain what 'resolve' returns, how failures or ambiguous names are handled, or the pagination mechanics, leaving some burden on the agent to infer behavior from 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 83%, and the schema already documents each parameter, including the important caveat that asin is 'never an implicit campaign choice.' The description adds no parameter-level meaning, so the baseline score of 3 applies because 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 action ('Resolve a campaign exactly') and resource ('full synced campaign table'), making clear this is an exact-match lookup rather than a general search. It distinguishes itself from siblings like get_campaigns and search by emphasizing exactness, though it does not explicitly name those alternatives.
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 explicit guidance on when to use this tool versus siblings such as get_campaign_detail or search. The word 'exactly' implies use when a precise campaign identifier or name is known, but this is left to inference rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Amazon Account Health: AHR score + status, ODR/LSR/OTDR/VTR/IPI metrics, policy violations, and the top risks. Use for "account health", "suspension risk", "my ODR".
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is covered. The description adds useful detail about the response contents but does not disclose additional behavioral traits such as data freshness, scope limits, or response timing; it is adequate without being rich.
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 two concise sentences, front-loading the resource and its output contents while adding practical usage phrases at the end. There is no fluff or repetition of schema 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 parameterless, read-only tool, the description adequately covers the main result categories and use-case phrasing. Since there is no output schema, the enumerated metrics and risks help compensate, though a brief statement about the response structure or that it reflects current health could add further completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, leaving nothing for the description to document about inputs. The description instead clarifies what the output contains, which is appropriate for a parameterless tool and earns the baseline 4.
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 clearly names the resource (Amazon Account Health) and specifies what it returns: AHR score/status, ODR/LSR/OTDR/VTR/IPI metrics, policy violations, and top risks. It does not explicitly contrast with sibling get_* tools, so it falls short of a 5 on differentiation, 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?
The description explicitly provides trigger phrases to use the tool: "account health", "suspension risk", "my ODR". This gives clear when-to-use guidance, though it does not mention when not to use it or name alternative tools for related queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your staged / applied / rejected SellerForge actions in the approval queue.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows (default 20, max 50). | |
| status | No | Filter by status. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'List' aligns with that. The description adds the statuses (staged/applied/rejected) but misses 'failed', and it does not disclose pagination, output format, or other behavioral nuances. It adds moderate value beyond 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?
A single, focused sentence that front-loads the core purpose. There is no filler or redundant 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 simple list tool with two optional parameters and no output schema, the description conveys the essential purpose. The omission of the 'failed' status and lack of return format details are minor given the low complexity, but the description is mostly sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage of both parameters, including enums and limits. The description adds no extra meaning about the parameters, so it relies on 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 clearly identifies the resource (SellerForge actions) and the action (list) with statuses, and it uses 'approval queue' to distinguish from other get_* tools. However, it omits the 'failed' status that appears in the schema, which is a minor gap in completeness.
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 what it lists (actions in the approval queue) and implies a query context, but it does not explicitly compare to sibling tools or state when not to use it. No alternatives or exclusionary conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
AI Search Visibility: readiness scores for AI shopping assistants (Alexa for Shopping / COSMO) on tracked ASINs — latest score + WoW change, drops, top fixes, competitor compare. Use for "AI visibility", "Alexa readiness", "COSMO score".
| Name | Required | Description | Default |
|---|---|---|---|
| asin | No | Focus on one tracked ASIN (own or competitor). |
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 some useful context about the response contents (latest score, WoW change, drops, fixes, competitor compare), but it discloses no other behavioral traits such as data freshness, scoping rules, or pagination. This is adequate but not rich.
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 two sentences long, starts with the core purpose, and packs useful details (metrics, scope, trigger phrases) without redundancy. Every piece supports tool selection and invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description compensates by enumerating the main return components. It covers what the tool does, what it operates on, and when to use it. It could go slightly further by clarifying what happens when no asin is provided, but for a read-only summary tool with one optional parameter, the definition is adequately 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%: the only parameter, asin, is described as focusing on one tracked ASIN. The description's phrase "tracked ASINs" adds little beyond the schema. The description neither adds format details nor clarifies behavior when the optional parameter is omitted, so it meets the baseline for fully covered schema parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns readiness scores for AI shopping assistants, including specific metrics (latest score, WoW change, drops, top fixes, competitor compare). This distinguishes it from siblings like get_keyword_rank_history or get_sales, and the included trigger phrases reinforce its specific domain.
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 explicitly says "Use for "AI visibility", "Alexa readiness", "COSMO score"", which gives clear selection triggers. It does not, however, mention when not to use it or contrast it with any sibling tool, so it stops short of full exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent notable business events (spend spikes, rank changes, stockouts, health changes) as a timeline.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Trailing window in days (default 30, max 90). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this is a safe read-only call, and the description adds the event categories and timeline format. It does not specify the exact shape of each event or how 'notable' is determined, but for a read-only overview tool this is acceptable context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the core purpose and placed the clarifying event list in parentheses. Every word 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?
For a one-optional-parameter read-only tool with no nested objects or output schema, the description plus schema covers the essential call semantics. A timeline implies chronological ordering, and the days parameter defines the window, so an agent has enough to invoke correctly, though return-field details are 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?
The schema fully documents the only parameter 'days' including default and max, and the description's 'Recent' aligns with the trailing-window concept. The description adds no new semantic detail about the parameter, so it stays at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific query ('get recent notable business events') and fills in the resource with concrete event categories (spend spikes, rank changes, stockouts, health changes). It is clearly distinct from sibling detail-tool names like get_sales and get_inventory_snapshot, though it does not explicitly name an alternative.
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 explicit when-to-use or when-not-to-use guidance is given. The phrase 'notable business events... as a timeline' implies use for a high-level anomaly timeline rather than deep drill-downs, but an agent choosing between this and get_account_health or get_sales gets no direct routing cue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Campaign identity/configuration with campaignMetadataAsOf, plus publication-qualified recent spend and mature attribution facts (ad sales, orders, ACoS, ROAS) when available. Metadata and performance windows have separate dates. Observation only; targets, efficiency conclusions, recommendations, and proposal evidence remain withheld.
| Name | Required | Description | Default |
|---|---|---|---|
| campaignId | Yes | SellerForge ad_campaigns id (uuid). | |
| targetLimit | No | Target rows to return (default 25, max 50). | |
| targetOffset | No | Target row offset (default 0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior, and the description adds useful caveats: facts are provided 'when available', metadata and performance windows have separate dates, and targets/recommendations/proposal evidence are withheld. This goes beyond the annotations without contradicting them.
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 compact and front-loaded with the core content, followed by availability caveats and explicit non-guarantees. It is slightly dense with domain jargon, but every sentence adds useful 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 read-only detail tool with no output schema, the description covers the main facts returned, data availability caveats, and what is deliberately excluded. It is sufficient for an agent to understand what to expect without being overly verbose.
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 all parameters are already documented. The description adds context about the response content but does not add parameter-level meaning 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?
The description clearly identifies the tool's scope: campaign identity/configuration plus spend and attribution facts. It is specific enough to distinguish this from list-oriented siblings like get_campaigns, though it lacks an explicit verb like 'retrieves' or 'returns'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool for campaign-level detail, but it does not explicitly say when to use it versus find_campaign, get_campaigns, or other related tools. No exclusions or alternative tool guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Amazon Ads campaign identity/configuration with campaignMetadataAsOf, plus publication-qualified recent spend and mature attribution facts (ad sales, orders, ACoS, ROAS) when its exact-account reader is enabled and complete. Metadata and performance windows have separate dates. Observation only; no efficiency conclusions, recommendations, or proposals.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Spend descending. Other Ads-derived sorts remain disabled. | |
| limit | No | Max campaigns to return (default 25, max 50). | |
| state | No | Filter by campaign state, e.g. 'enabled' or 'paused'. |
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 meaningful context beyond that: separate metadata and performance date windows, reliance on an exact-account reader being enabled and complete, and the restriction that this is observation only with no efficiency conclusions. This helps an agent understand limitations without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and contains no filler, but the first sentence is a dense, jargon-heavy run-on that packs in 'campaignMetadataAsOf,' 'publication-qualified,' and 'mature attribution facts' without unpacking them. It would benefit from breaking the content into clearer, more readable clauses, so it is not well-structured enough for a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the burden of explaining what gets returned; it does qualitatively list campaign config and performance facts. Still, key terms like 'publication-qualified,' 'mature attribution,' and 'exact-account reader' are left undefined, and there is no mention of pagination behavior or how the three parameters shape the result set beyond what the schema already states.
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%, with all three parameters (sort, limit, state) already documented in the input schema. The description adds no parameter-level detail, but it does not need to because the schema fully handles semantics; this is the appropriate baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource as Amazon Ads campaign identity/configuration and enumerates the included performance facts (spend, orders, ACoS, ROAS), so an agent can infer it returns campaign data. However, it lacks an explicit verb like 'list' or 'get' and does not clearly distinguish itself from the sibling get_campaign_detail, which is likely the singular-detail counterpart.
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 only usage-related signal is the conditional 'when its exact-account reader is enabled and complete,' which is more of a data-availability caveat than guidance on when to select this tool over siblings. It does not mention alternatives such as get_campaign_detail or find_campaign, nor does it state when a caller should prefer list-style retrieval over detail lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Voice of Customer — Amazon's aggregated review topics, sentiment trends and verbatim quotes + category return reasons. Use for "reviews", "why did my rating drop".
| Name | Required | Description | Default |
|---|---|---|---|
| asin | No | Optional — one ASIN for its detailed feedback; omit for a catalog overview. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, covering the core behavioral safety profile. The description adds context about the data nature (aggregated, verbatim quotes, sentiment trends) but does not disclose additional behavioral details like pagination, rate limits, or auth requirements. With annotations present, the bar is lower, and the description adds some value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at two sentences, front-loads the 'Voice of Customer' brand, then lists the included data types and use cases. It is efficient with no filler, though it could be slightly more structured with a verb-led 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?
The tool is low complexity with one optional parameter, and the schema covers that parameter. No output schema exists, but the description enumerates the major output categories ('review topics, sentiment trends, verbatim quotes + category return reasons') and gives concrete use cases. This is sufficient for an agent to select and invoke the tool correctly, though it does not describe the exact response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already explains the single optional 'asin' parameter in detail ('Optional — one ASIN for its detailed feedback; omit for a catalog overview'). The tool description does not add parameter-level detail beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource: 'Amazon's aggregated review topics, sentiment trends and verbatim quotes + category return reasons.' It distinguishes itself from siblings by focusing on customer feedback/reviews rather than campaigns, sales, or keywords. However, it lacks an explicit action verb like 'retrieves' or 'gets,' so it stops short of the strongest purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Use for "reviews", "why did my rating drop"' provides explicit guidance on when to invoke this tool. It gives clear use cases but does not mention when not to use it or name alternative sibling tools, so it lacks exclusions but still offers clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decision Log: every AI-proposed or automated change (assistant, automations, MCP, quick-fixes, listing pushes) with why + status + directional 7-day after-change movement. Returns a rollup and recent entries. Use for "what changed", "decision log", "did my changes work".
| Name | Required | Description | Default |
|---|---|---|---|
| range | No | Look-back window (default 30d). | |
| source | No | Filter to one origin. | |
| status | No | Filter to one status. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds useful behavioral context: it includes why, status, and directional 7-day movement, and returns a rollup plus recent entries, which sets clear expectations about the response.
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 two sentences with no filler. It front-loads the definition and scope, then gives a usage directive. Every sentence 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?
For a read-only tool with no output schema, the description tells the agent what will be returned (rollup, recent entries) and what kind of data is included. It could describe the response shape in more detail, but the schema covers filters and the annotations cover safety, making this adequate.
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% with all three parameters having enum values and descriptions, so the schema carries the parameter documentation. The description adds some context by listing source categories, but it does not materially extend the schema's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (decision log) and says it returns a rollup and recent entries, with a clear scope: every AI-proposed or automated change. The list of change types and the mention of 'what changed' make it distinct from sibling tools like get_business_events or get_action_status.
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 when to use it: for 'what changed', 'decision log', and 'did my changes work'. It does not mention exclusions or name alternatives, but no sibling tool serves the same purpose, so the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The seller's escalation plans and their statuses.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 minimal behavioral context: it indicates the tool returns escalation plans and their statuses. It does not disclose whether it returns all escalations, only active ones, or any pagination/ordering behavior, but with no parameters and read-only annotations, the bar is lower.
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 a single short sentence, which is concise, but it is a noun phrase rather than an action-oriented description. It earns its place but does not add much value beyond the title 'Escalations'.
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 parameterless read-only tool, the description is minimal but not entirely inadequate. However, it does not explain what an 'escalation plan' is, what statuses look like, or how this relates to sibling tools like get_poa_cases. An agent would have to guess at the tool's exact purpose and output shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics burden. The description's mention of 'escalation plans and their statuses' gives a basic sense of what the returned data covers, which is sufficient for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'The seller's escalation plans and their statuses.' is a noun phrase, not a verb phrase. It states a resource but not an action, so an agent cannot tell what operation this tool performs (list? get? retrieve?). It also does not distinguish it from siblings like get_poa_cases or get_action_status.
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 guidance is given on when to use this tool versus alternatives. The readOnlyHint annotation implies it is a safe read, but the description itself provides no context about when escalations are relevant or how this differs from get_poa_cases or get_action_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current source-qualified FBA and AWD physical inventory components. Reports quantities and evidence gaps; cover and stock status are withheld without qualified velocity, and network/reorder advice is additionally withheld without arrival evidence.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 meaningful behavioral detail beyond that: it discloses that cover/stock status and network/reorder advice are conditionally withheld, which is non-obvious output behavior. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but free of filler, front-loading the resource and key reported fields before explaining withholding conditions. The heavy domain terminology slightly reduces readability, but every sentence 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 no inputs and no output schema, the description carries the burden of explaining both returned content and conditional omissions, which it does. It could be more complete by defining terms like 'qualified velocity' and 'arrival evidence,' but for a no-parameter read-only snapshot it is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters and schema description coverage is 100%, so the baseline is 4. The description cannot add parameter-level meaning, but it does contextualize what the returned inventory information covers and under what conditions additional data appears.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (FBA and AWD physical inventory components) and a clear reporting verb ('Reports quantities and evidence gaps'). It is specific enough to distinguish this tool from the sibling getters, which target different resources such as keywords, sales, or campaigns.
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 explicit guidance on when to use this tool versus alternatives, nor does it name any sibling for comparison. The intended use is only implied by the tool name and the resource-focused wording, not by any stated selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Query Performance (Brand Analytics) for an ASIN by keyword: search volume, your conversion rate vs the category, purchase share and organic click share.
| Name | Required | Description | Default |
|---|---|---|---|
| asin | Yes | Required — SQP is per own-ASIN. | |
| weeks | No | Trailing window in weeks (default 4, max 12). | |
| keyword | No | Optional single query (exact). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description only needs to add context beyond safety. It adds the metric list as the return content, but it does not disclose important behavioral traits such as brand-analytics eligibility or what happens when the optional keyword is omitted. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single information-dense sentence with no filler, and the useful metrics are listed compactly. It repeats the tool title at the start, but the rest 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?
The core purpose and return content are covered, and the parameters are fully documented, which is good for a simple read-only lookup. However, with no output schema, the absence of guidance on omitted-keyword behavior and result structure leaves a real gap for an agent.
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; every parameter already has a meaningful schema description. The description only reinforces the centrality of keyword and does not add syntax, formatting, or omission behavior 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 identifies a specific resource—Search Query Performance (Brand Analytics) for a given ASIN and keyword—and lists the returned metrics (search volume, conversion rate vs category, purchase share, organic click share). It is clear and distinguishable from rank-history or keyword-list siblings, but it does not explicitly name a differentiating 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?
The phrase 'for an ASIN by keyword' and the schema note that SQP is per own-ASIN give an implied use case. There is no explicit statement of when to use this over get_keyword_rank_history or get_keywords, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank/share snapshot history for one keyword phrase (most recent 30 points).
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | The keyword phrase to look up. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds a useful behavioral cap ('most recent 30 points') and single-keyword scoping, but it does not disclose ordering, time intervals, or what each snapshot point contains. This is similar to the baseline where annotations cover safety but return behavior is thin.
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 a single focused sentence with no filler. It front-loads the resource and scope, then appends the limit 'most recent 30 points'. Every word adds value.
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 simple read-only, one-parameter tool, the description is mostly complete: it states what is returned, for what input, and how many points. With no output schema, it could have described the shape of a snapshot point more explicitly, but this is a minor gap given the low complexity.
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 fully documents the only parameter. The description only restates 'one keyword phrase' and adds no additional semantic details like matching behavior or formatting, so the baseline score 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 names a clear resource ('rank/share snapshot history') with a specific scope ('one keyword phrase') and a quantifier ('most recent 30 points'). It is more specific than the tool name/title, though 'rank/share' is slightly ambiguous and no sibling is explicitly contrasted.
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 phrase 'for one keyword phrase' implies this is for single-keyword historical lookups, but the description does not mention related tools like get_keywords or get_keyword_market_performance, nor does it say when not to use this tool. Usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tracked keywords and organic/sponsored rank for the seller's ASINs. Use for "keyword rank", "am I ranking for X".
| Name | Required | Description | Default |
|---|---|---|---|
| asin | No | Filter to one ASIN. | |
| trackedOnly | No | Only keywords being rank-tracked (default true). |
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 useful context about the data scope (tracked keywords, organic/sponsored rank, seller's ASINs) but discloses no additional behavioral traits such as filtering defaults or return 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?
Two short sentences, no filler, and the core purpose is stated first. The use-case guidance is concise and directly actionable.
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 simple read-only tool with optional filters and no output schema, the description is largely sufficient. It could be improved by noting the distinction from get_keyword_rank_history, but the core selection and invocation context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the input schema, and schema coverage is 100%. The description adds no parameter-level meaning beyond the schema, so the baseline score of 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 clearly identifies the resource: tracked keywords and organic/sponsored rank for the seller's ASINs. The use cases 'keyword rank' and 'am I ranking for X' make the purpose understandable, though it lacks an explicit verb and does not distinguish itself from the closely related sibling get_keyword_rank_history.
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 explicitly states 'Use for "keyword rank", "am I ranking for X"', giving clear context for when to invoke this tool. It does not, however, mention when not to use it or point to alternative tools such as get_keyword_rank_history for historical rank data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Listing audit scores and the worst-scoring listings with fixes. Use for "listing quality", "what to fix on my listing".
| Name | Required | Description | Default |
|---|---|---|---|
| asin | No | Filter to one ASIN. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the tool returns scores, worst-scoring listings, and fixes, but it does not disclose details like how many listings are included, whether results are ranked, or any filtering behavior beyond the optional ASIN parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The first sentence states what the tool provides, and the second gives concrete usage intent. Every word 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?
This is a simple read-only tool with one optional parameter and no output schema. The description covers the core return value (scores, worst listings, fixes) and the key use cases, which is sufficient for an agent to select and call it correctly. Minor details like result count or ranking order are not essential for 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?
The input schema fully describes the single 'asin' parameter at 100% coverage, so the schema carries the semantic weight. The description does not add any additional meaning or usage guidance about the ASIN filter, which keeps this at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource ('listing audit scores' and 'worst-scoring listings') and the intended outcome ('fixes'), making the tool's purpose clear. It is distinguishable from broad siblings like get_account_health or get_sales by its focus on listing quality, though it does not explicitly name an alternative.
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 explicit usage triggers: 'listing quality' and 'what to fix on my listing'. This tells an agent when to invoke the tool, but it does not mention when not to use it or point to a sibling alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Orders SUMMARY: exact-marketplace revenue, orders and units for recent completed days. Trends and averages appear only once their windows are complete. For a specific window like "last 7 days", use get_sales.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the data covers only 'completed days' and that trends/averages appear only after their windows are complete, which is non-obvious and valuable for an agent. While annotations already indicate readOnlyHint=true and destructiveHint=false, the description adds meaningful behavioral context about data freshness that goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. It front-loads the core purpose and scope, then immediately routes to the alternative tool. Every word is purposeful and the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool, the description is complete enough: it tells the agent what data to expect, the timing caveat, and provides a pointer to an alternative. An output schema is absent, but for a summary tool, return value specifics could be assumed; still, the description could mention the granularity of units or whether data is per-day or aggregate, but these are minor gaps given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This tool has zero parameters (as per context signals), so the baseline for parameter semantics is 4. The description adds contextual meaning about the data coverage and timing, even though there are no parameters to document. No additional parameter explanation is needed because there are none.
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 clearly states the tool provides 'exact-marketplace revenue, orders and units' for 'recent completed days', which identifies a specific verb (get), resource (orders summary), and scope. It also distinguishes itself from get_sales by explicitly mentioning which tool to use for a different time window.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool (for a complete-day summary) and when not to — 'For a specific window like last 7 days, use get_sales'. This provides clear routing between siblings and an alternative, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The seller's POA cases (violation type, status, last update).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 a little context by naming the data fields returned, but it does not disclose ordering, filtering scope, or whether this reflects all POA cases or only open ones.
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 a single compact sentence that communicates the resource and key returned fields with no redundant wording. It is fully front-loaded and appropriate for the tool's zero-parameter complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool, the description gives enough surface information: it identifies the resource and the fields the agent can expect. It could be slightly more explicit about saying it returns a list or that it represents all POA cases, but nothing critical is missing given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter semantics for the description to clarify. The baseline of 4 applies because the description does not need to compensate for any undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the seller's POA cases and lists the key fields included (violation type, status, last update). The resource is specific enough to be distinguished from siblings like get_action_status or get_escalations, though it does not explicitly contrast with 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?
The description gives no guidance on when to use this tool versus alternatives. It neither mentions a trigger condition nor names sibling tools that might be more appropriate for related queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Possible FBA REIMBURSEMENT discrepancies SellerForge detected that are not yet verified or filed: counts and raw estimates, not confirmed money owed. Use for "what might Amazon owe me", "reimbursement claims", "FBA discrepancies".
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false. The description adds meaningful behavioral context: the data is 'not yet verified or filed' and consists of 'counts and raw estimates, not confirmed money owed', so callers understand the reliability and provisional nature of the 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 description is only two sentences, front-loads the key distinction of unverified/unfiled discrepancies, and adds quoted use cases without filler. Every sentence 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?
For a zero-parameter read-only tool with no output schema, the description sufficiently explains what the data is, what it represents, its reliability, and when to use it. Nothing essential is missing for an agent to decide whether to call this 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?
The schema has zero parameters and 100% schema coverage, so there are no parameters for the description to document. This matches the established baseline for zero-parameter tools.
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 clearly what the tool returns: 'Possible FBA REIMBURSEMENT discrepancies SellerForge detected that are not yet verified or filed' as 'counts and raw estimates'. This is a specific resource delivered by the tool and is distinguishable from siblings like get_reimbursements without needing to open schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit use cases in quoted intents: 'what might Amazon owe me', 'reimbursement claims', 'FBA discrepancies'. It also implies the tool is for unverified/unfiled discrepancies rather than confirmed money, but it does not explicitly name a sibling alternative such as get_reimbursements for confirmed/filed amounts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FBA reimbursements already RECEIVED (paid) in a recent window, by category. For possible discrepancies not yet filed, use get_recoverable_reimbursements.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Trailing window in days (default 90, max 365). |
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 known. The description adds meaningful scoping behavior: only paid/received reimbursements, recent window, categorized results, and a clear boundary against un-filed discrepancies. It doesn't describe pagination or return format, but that is minor for this simple read operation.
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 short sentences with no fluff. The core scope is front-loaded, and the sibling alternative is given in a compact second sentence. Every word 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?
For a one-parameter, read-only, list-style tool, the description plus schema is sufficient. It states what is returned (received reimbursements, by category), the time window, and the correct alternative. No output schema exists, but the tool's return shape is not complex enough to require further elaboration.
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% for the single optional days parameter, which is fully documented with default and max. The description's phrase 'recent window' loosely relates to days but adds no new syntax or format details, so the schema carries the weight and the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (FBA reimbursements), the status filter (already RECEIVED/paid), the window (recent), and the grouping (by category). It also distinguishes this tool from the sibling get_recoverable_reimbursements by stating that this one covers already-paid reimbursements only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when not to use this tool: for possible discrepancies not yet filed, use get_recoverable_reimbursements instead. That gives the agent a clear routing rule and prevents mis-selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SALES / REVENUE for 1–30 completed exact-marketplace days. Adopted atomic-V2 scopes return account-summary-qualified Amazon Sales & Traffic ordered-product sales, units, and order items (not unique orders); exact mature summary/child-ASIN mismatch evidence may qualify only those account totals. Never allocate them to ASIN/SKU or use them for margin or break-even ACoS. Non-adopted scopes retain qualified Orders labels. Preserve explicit gaps and report a trend only when returned. Use for "sales", "revenue", "how much did I sell", "sales last 7 days".
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Trailing completed-marketplace-day window (1–30, default 7). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations only declare readOnlyHint, openWorldHint, and destructiveHint. The description adds substantial behavioral nuance beyond that: results are account-summary-qualified, not unique orders, cannot be allocated to ASIN/SKU, legacy non-adopted scopes keep 'Orders' labels, explicit data gaps must be preserved, and trends should only be reported when returned. This is rich, non-obvious behavior that helps the agent use results correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long and dense, but every sentence earns its place by conveying a distinct constraint or use case. It is front-loaded with the core purpose and then layers caveats and usage intent. Slightly better formatting (e.g., bullets) could improve scannability, but it is not bloated or redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must explain what the tool returns, and it does: sales, units, order items, with the caveat that they are not unique orders. It also covers data-gap handling and trend reporting. For a single-optional-parameter read-only tool with these complexities, the description leaves no critical operational gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter, days, and the schema already describes it thoroughly with type, default, minimum, maximum, and meaning ('Trailing completed-marketplace-day window'). The description repeats the range in prose but adds no new parameter-level semantics. With 100% schema coverage, the baseline of 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 opens with a specific verb and resource: 'SALES / REVENUE for 1–30 completed exact-marketplace days.' It enumerates the return metrics (sales, units, order items) and explicitly distinguishes itself from order-level tools by noting it returns 'not unique orders.' This lets an agent differentiate it from siblings like get_orders_summary without deep schema inspection.
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 explicit when-to-use guidance: 'Use for "sales", "revenue", "how much did I sell", "sales last 7 days".' It also provides strong when-not guidance by warning against allocating to ASIN/SKU or using for margin/ACoS. However, it does not name a specific alternative tool to route to for those excluded use cases, so it falls short of the top score that requires naming alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Keyword search over your SellerForge RECORDS — compliance/POA cases, escalation plans, and product listings (by ASIN or title) — returning ids + deep links. NOTE: for sales, ads, inventory or health NUMBERS use the get_* metric tools (get_sales, get_campaigns, get_inventory_snapshot, get_account_health, …); this searches records, not metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Free-text query. |
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 that the tool returns ids and deep links, which is useful but not extensive. It does not mention pagination, result limits, or other behavioral constraints, so the extra context beyond annotations is modest.
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 two sentences with no filler. The first sentence fronts the core purpose and return value; the second is a targeted disambiguation note that prevents misuse. Every word 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?
For a simple read-only search tool with one well-documented parameter, the description covers what it searches, what it returns, and when not to use it. The absence of an output schema is compensated by the explicit 'ids + deep links' mention. It could note pagination, but that is not essential 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?
The schema has 100% coverage for the lone 'query' parameter with 'Free-text query.' The description adds that the search works over 'product listings (by ASIN or title) and records,' which gives concrete meaning to the free-text query. It also implies that the query can be an ASIN or title, which is valuable beyond the schema's generic phrasing.
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 action (keyword search), a specific resource (SellerForge RECORDS), enumerates the record types (compliance/POA cases, escalation plans, product listings), and specifies the return value (ids + deep links). It explicitly distinguishes itself from metric tools by stating 'this searches records, not metrics,' which differentiates it from the large group of get_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit when-not rule: 'for sales, ads, inventory or health NUMBERS use the get_* metric tools.' It names the alternative tool family and the condition that selects them. It also clarifies the record scopes, so an agent knows exactly when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search the seller's Document Vault (SOPs, supplier docs, margins, goals).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search phrase. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds some behavioral context by specifying full-text scope and document types, but it does not mention result format, pagination, or any query behavior beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action and resource, with no redundant words or repetition of annotation fields. Every phrase 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?
For a simple, single-parameter read-only tool with full schema coverage, the description covers what and where it searches. It does not describe the result shape, but no output schema exists and the return of a search tool is fairly inferable, so this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter query is already documented in the schema with 100% coverage, so the baseline is 3. The description reinforces that it is a full-text search, but adds no syntax or formatting rules 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?
Description opens with the specific verb 'Full-text search' and identifies the exact resource, the seller's Document Vault, with examples of what it contains (SOPs, supplier docs, margins, goals). This scope is enough to separate it from the bare 'search' 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?
The description implies the tool is appropriate when looking for Document Vault content, but it never states when to prefer it over the sibling 'search' tool or when not to use it. No alternatives or exclusions are named, so usage is inferred rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
fetchfind_campaignget_account_healthget_action_statusget_ai_visibility_summaryget_business_eventsget_campaign_detailget_campaignsget_customer_feedbackget_decision_logget_escalationsget_inventory_snapshotget_keyword_market_performanceget_keyword_rank_historyget_keywordsget_listing_auditsget_orders_summaryget_poa_casesget_recoverable_reimbursementsget_reimbursementsget_salessearchsearch_vaultReal-time Amazon product, seller, and search data for AI agents across 21 marketplaces.
Amazon Seller Central and Ads inside Claude or ChatGPT. Real fees from your own settlements.
Amazon PPC data, P&L and inventory for AI assistants; changes only after your approval.
Amazon keyword volume, reverse-ASIN, and SERP data across 11 marketplaces.
Add one secure layer between your agents and this server.
