Platform Guide
How agentcentral handles data freshness, write operations, rate limits, and other platform-level behavior that applies across all tools.
Data freshness
Different data sources refresh on different schedules. Knowing these timelines prevents you from presenting stale numbers as current.
| Domain | Lag | Sync schedule |
|---|---|---|
| Ads (SP, SB, SD) | 3-day attribution window | Daily |
| Business Reports | ~72 hours | Daily |
| Sales summary | Hours | Daily |
| Orders | Near-real-time | Every 15 minutes |
| Inventory | Daily snapshots | Daily |
| SQP (search query performance) | Weekly granularity | Weekly |
| Keyword ranks | Daily snapshots | Daily |
| Settlements | Settlement period | Daily |
Why this matters
Ads data from yesterday is incomplete because Amazon attributes conversions over a 14-day window. The numbers stabilize after about 3 days. If you query yesterday's ads data, ACOS will appear artificially high because sales haven't been fully attributed yet.
Write tool guardrails
All write tools enforce safety limits and log every action to an audit trail. No write operation can be executed without a pre-read of the current value.
| Guardrail | Value |
|---|---|
| Maximum bid | $100 |
| Minimum bid | $0.02 |
| Budget range | $1 to $10,000 |
| Change warning threshold | 500% change from current value |
| Placement bid range | 0% to 900% |
| Max items per call | 100 for ads and price feeds; 25 for inventory quantity updates; 20 for listing attribute patches |
| Catalog writes | Preview plus confirm and idempotency key required for listing, price, and quantity updates |
| Audit logging | All writes logged to agent_actions table with old and new values |
Irreversible action
Setting a campaign state to ARCHIVED is permanent and cannot be undone. The tool description warns about this, but confirm with the user before archiving.
Profile scoping
Each Amazon Ads account has one or more profiles, where each profile maps to a marketplace. Agent Central currently provisions United States profiles at launch. The profile_id parameter controls which advertising profile's data you query.
- Omitting profile_id: queries across all profiles. Works for account-level overviews, but can mix marketplace data in unexpected ways.
- Specifying profile_id: filters to a single marketplace. Required for all write operations and recommended for most reads.
To discover available profiles, use the ads://profiles MCP resource, which returns a list of profile IDs with their marketplace labels.
Direct API vs materialized tools
Most tools read from pre-materialized BigQuery tables, returning results in 100-300ms. A subset of tools call the Amazon API directly at request time for live data. These are slower (200-800ms) and subject to Amazon's rate limits. Some hybrid tools also support stored daily snapshot history when you provide a date window.
Direct API and hybrid tools
get_bid_recommendationsget_budget_recommendationsget_ad_eligibilityget_current_rankget_buybox_statusget_competitive_pricingget_offer_listingsget_restock_recommendationsget_fba_eligibilityget_listing_restrictionsget_buybox_status, get_competitive_pricing, and get_restock_recommendations default to live API mode, but switch to BigQuery-backed history when start_date or end_date is provided.
Everything else reads from BigQuery. The data is as fresh as the sync schedule above, but responses are fast and not subject to Amazon API rate limits.
Date defaults
Most tools accept optional start_date and end_date parameters in YYYY-MM-DD format.
- Ads tools: default to the last 30 days if dates are omitted.
- Sales summary: defaults to the last 7 days.
- Ranking tools:
get_keyword_ranksrequiresstart_date(no default).get_rank_with_volumerequiressnapshot_date. - Inventory snapshots: default to the latest available snapshot date.
Rate limits
- Server-wide: 120 requests per minute per API key, with a durable hourly cap of 7,200 completed requests per key.
- Daily caps: no default daily cap. Daily query limits only apply to keys where a limit has been configured.
- Direct API tools: subject to additional per-endpoint Amazon API rate limits. The server handles throttling and retries automatically, but sustained high-frequency calls to live API tools may see 429 responses.
SQP data granularity
Search Query Performance (SQP) data from Brand Analytics is aggregated at weekly granularity. Each row covers a full week aligned to Amazon's week boundaries, not arbitrary date ranges. Querying a single day returns the entire week that contains that day.
This also affects get_rank_with_volume, which joins daily rank snapshots with the SQP week containing the snapshot date. The volume numbers represent the full week, not the individual day.