Amazon Seller Central & Ads MCP

Payout balance and why it moved

get_payout_balance

Read-onlyIdempotent

The seller's Amazon payout balance and why it moved, from Amazon's own settlement lines: what the current settlement started from (negative = still owed to Amazon), what is released and held now, and the last settlements broken into buckets with the posting date of every advertising invoice, debt adjustment and carried balance. Use it for 'why is my balance negative', 'what triggered −X', 'what did Amazon deduct', 'when do I get paid'. Money only — units live in get_inventory_reconciliation.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_payout_balance"
  }
}

Input Schema

Name	Required	Description
`account`	No	Seller id of the client account (from list_my_accounts). Only needed when several connected accounts cover this marketplace; with several and no account the tool refuses rather than guessing.
`payouts`	No	How many recent settlements to break down (default 4, max 12).
`marketplace_id`	No	Marketplace id (from list_my_marketplaces); inferred when the seller has one.

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 9, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety needs no restating. The description adds real behavioral context: the source of truth is Amazon's settlement lines, negative values mean money still owed, and the response is broken into buckets with per-invoice posting dates. It does not mention the multi-account refusal behavior, but that lives in the schema parameter description.

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

Conciseness4/5

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

Front-loaded with purpose before examples, and no sentence is filler. The opening sentence is long and clause-stacked (start/held/released/segment breakdown packed in), which costs a point against a cleaner two-sentence split, but the examples at the end are high-value routing signal.

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

Completeness5/5

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 return-shape duty and does so: starting balance semantics, released vs held, settlement buckets, and posting dates per advertising invoice, debt adjustment and carried balance. Combined with annotations and full schema coverage, an agent has everything needed to call and interpret this.

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

Parameters3/5

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

Schema description coverage is 100%, and the schema already documents account provenance, the default/max on payouts, and marketplace inference. The description adds virtually nothing parameter-level, so the baseline of 3 applies.

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

Purpose5/5

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

States a specific resource (the seller's Amazon payout balance) and what the tool explains (why it moved), grounded in 'Amazon's own settlement lines'. It also explicitly demarcates scope against a sibling: 'Money only — units live in get_inventory_reconciliation.' An agent can distinguish this from get_profit_summary or get_inventory_reconciliation 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.

Usage Guidelines5/5

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

Gives literal user phrasings that select this tool ('why is my balance negative', 'what triggered −X', 'what did Amazon deduct', 'when do I get paid'), plus an explicit exclusion routing unit-level questions to get_inventory_reconciliation. When-to-use and when-not-to-use are both present.

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

All Amazon Seller Central & Ads MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?