Connect ad accounts

Prompts for the connection setup needed to start using Picaro.AI. Account switching and re-login after a dropped connection are also covered here.

For MCP connections

MCP only This category is for managing your Picaro connection from an MCP connection (Claude / ChatGPT, etc.). If you use the Picaro.AI dashboard, you are connected automatically when you log in, so it is not needed.

When this category applies

• “Check the current connection status and the default account.”
• “Switch to a different Amazon Ads account.”
• “The connection seems to have dropped — re-login.”
• “Link an Amazon Ads account so a new campaign can be created.”

---

Prompt 1: Check connection status and switch accounts

🎯 Goal

Verify the current Picaro connection and default account, then switch to a different account if needed.

📋 When to use

• Confirm the current connection status.
• Confirm which account operations are running against.
• Switch to a different account.

📝 Prompt

Check the current Picaro connection and default account:
1. Confirm the Picaro connection is active
2. Show the current default account and time elapsed since the last switch
3. List accessible Amazon Ads accounts
4. If needed, switch to {{TARGET_ACCOUNT}}

For agencies managing multiple clients, set the default account once
instead of passing account_id each time — subsequent prompts will
automatically operate against that account.

Placeholders:

Placeholder	Description	Default resolution
{{TARGET_ACCOUNT}}	Target Amazon Ads account name or ID to switch to (e.g., “Client A”, “JP-12345”)	If omitted, list accounts only — no switch

⚙️ What the AI does

1. Verifies the Picaro connection is active — if the connection has dropped, surfaces the re-login steps in Prompt 2.
   • Why first: an invalid connection makes every subsequent step fail, so block at the entry point.
2. Displays the default account and time elapsed — shows how long since the last switch.
   • Why elapsed time: helps catch the case of operating against a stale account setting.
3. Lists accessible Amazon Ads accounts — every account the user holds read permission for.
4. Switches if requested — validates read permission on the target account before persisting.
   • Why validate first: prevents accidental switches to the wrong account.

📊 Example Output

Picaro connection: active (endpoint picaro.ai, last verified 2 min ago)

Default account: Client A (JP-12345, 14 days since last switch)

Accessible Amazon Ads accounts: 4

#	Display name	Account ID	Country	Default
1	Client A	JP-12345	JP	✓
2	Client B	JP-23456	JP	—
3	Client C	US-34567	US	—
4	Internal test	JP-99999	JP	—

To switch, specify something like “switch to #2”.

🔒 Safeguards

• Permission is validated before persisting a switch (accounts without access cannot be set as default).
• The default account is only changed when “switch” is explicitly requested.
• Switch history is recorded in the connection log so past switches can be audited later.
• For list-only requests, no write operation is issued.

🚦 Execution mode

Phase	State	Condition
Phase 1 (current)	One-shot	Available with just the Picaro connection
Phase 2 (Q3 2026)	Stays one-shot	Why one-shot: once set, the default rarely changes for ~6 months — automation priority is low
Phase 3 (Q4 2026)	One-shot (only on expiry)	Notify when the connection expires
Phase 4 (2027)	Auto-renew + expiry notification	Notify on expiry and surface the re-login flow

👉 Next steps

• Set targets for sales, ad spend, and ACoS — Once the default account is fixed, register the target ACoS and TACoS so subsequent prompts can reference them automatically.
• Classify ads with labels and naming rules — Define the product taxonomy per account to unlock label-level KPI aggregation.

---

Prompt 2: Re-login after a connection error

🎯 Goal

Refresh an expired or unauthenticated Picaro connection safely, staying as the same user.

📋 When to use

• A connection-error message appeared and needs to be cleared.
• After re-logging into Picaro.AI, the AI agent environment’s connection also needs updating.
• A message such as “session expired” was shown.

📝 Prompt

Refresh the Picaro connection:
1. Issue a re-login URL
2. Open that URL in a browser and log in to Picaro.AI
3. Once done, resend any prompt and it will run on the new connection

Note: switching to a different Picaro account is NOT supported here.
Disconnect and reconnect the Picaro extension in your AI agent environment instead.

Placeholders: none (fixed to re-login as the same user)

⚙️ What the AI does

1. Issues a re-login URL — the URL is short-lived.
   • Why short-lived: reduces the risk of a third party picking up the URL and abusing it.
2. Guides the browser flow — open the URL and complete login on Picaro.AI.
3. Confirms how to resume — after login, resending any prompt in the same session picks up the new connection.
   • Why “send another prompt”: connection state is re-read on the next prompt send.

📊 Example Output

Re-login URL issued

Open the URL below in a browser within 10 minutes and log in to Picaro.AI:

https://picaro.ai/auth/reconnect?token=...

Once done, resend the operation in this chat and it will re-run on the new connection.

To switch to a different Picaro account, do not use this flow — disconnect the Picaro extension in your AI agent environment and reconnect with the other account.

🔒 Safeguards

• The re-login URL must be used within 10 minutes (Why 10 min: short enough to limit interception risk, long enough for normal browser use). Reissue if expired.
• The URL is bound to the session’s user, so it cannot be used to switch to another account.
• For account-switching, a separate path (reconnect the Picaro extension in your AI agent environment) is explicitly surfaced.
• Browser sign-in is performed by the user, so the AI cannot log in under a wrong account.

🚦 Execution mode

Phase	State	Condition
Phase 1 (current)	One-shot	Run on each error
Phase 2 (Q3 2026)	Stays one-shot	Why one-shot: connection refresh happens ~once every 6 months — automation priority is low
Phase 3 (Q4 2026)	One-shot (only on expiry)	One click from the expiry notification issues the URL
Phase 4 (2027)	Auto-renew + expiry notification	Auto-refresh via refresh token; notify only on actual expiry

👉 Next steps

• Check connection status and switch accounts — After re-login, sanity-check that the default account is what is expected.
• Send feedback and support requests — If connection errors persist after re-login, attaching version info speeds up the fix.

❓ FAQ

Q: The re-login URL expired. A: Resend the same prompt to issue a fresh URL. The old one becomes invalid.

Q: How to switch to a different Picaro account? A: This re-login flow does not support account switching. Disconnect the Picaro extension in your AI agent environment and reconnect with the other account.

---

Prompt 3: Link an Amazon Ads account (for new campaign creation)

🎯 Goal

As a prerequisite to creating a new ad campaign, link the Amazon Ads account to Picaro and retrieve the available advertising profiles.

📋 When to use

• Link an Amazon Ads account in order to create a new campaign.
• Confirm available advertising profiles after linking.
• Prepare prerequisites before moving on to the campaign-creation prompts.

📝 Prompt

Link an Amazon Ads account for new campaign creation:
1. Check the current connection status
2. If not linked, issue a connection URL
3. Open that URL in a browser and log in to Amazon
4. After completion, retrieve the list of available advertising profiles
5. Use the retrieved profile to create the campaign

Note: this link is required ONLY for creating new ad campaigns.
It is NOT required for fetching, analyzing, optimizing, or dashboard
display of ad data.

Placeholders: none (the link target is selected in the Amazon-side UI during the flow)

⚙️ What the AI does

1. Checks current Amazon Ads account connection — if already linked, skips to step 4 (profile listing).
   • Why check first: prompting a re-login when already linked creates double-authentication confusion.
2. Issues a connection URL if not linked — generates a URL that lands on the Amazon authorization screen.
3. Guides the browser flow — the user logs in to Amazon and approves the target account.
4. Retrieves the advertising profile list — after linking, displays available profiles grouped by country.
   • Why group by country: the same advertiser has separate profiles per country; grouping prevents wrong-profile linking.
5. Hands off to the campaign-creation prompt — the retrieved profile ID is used in the next prompt.

📊 Example Output

Amazon Ads account connection: not linked

Open the URL below in a browser and log in to Amazon:

https://picaro.ai/auth/amazon-ads?token=...

After login, select the ad account to link and approve.

---

After connection (reference)

Available advertising profiles: 3

#	Profile name	Country	Account type
1	Picaro Brand JP	JP	Seller
2	Picaro Brand US	US	Seller
3	Picaro Vendor JP	JP	Vendor

To continue with campaign creation, specify something like “create a campaign on profile #1”.

🔒 Safeguards

• The connection URL is short-lived.
• Before linking, the AI states explicitly: “this link is for new campaign creation — it is not required for data retrieval, analysis, or optimization”.
• Connection scope is limited to ad management permissions only (unrelated data such as order information is not accessed).
• Browser approval is performed by the user, so wrong-account linking does not occur.
• No re-authentication is prompted when already linked.

🚦 Execution mode

Phase	State	Condition
Phase 1 (current)	One-shot	Run only when creating a new campaign
Phase 2 (Q3 2026)	Stays one-shot	Why one-shot: linking is normally a one-time operation — not a candidate for automation
Phase 3 (Q4 2026)	Stays one-shot	Notify on expiry detection
Phase 4 (2027)	Fully automatic (refresh token)	Auto-refresh via refresh token; surface re-auth only on actual expiry

👉 Next steps

• Create Sponsored Products (SP) campaigns — Specify the retrieved advertising profile to move on to campaign creation.
• Classify ads with labels and naming rules — In parallel with campaign creation, organizing the product taxonomy enables label-level KPI views.

❓ FAQ

Common misconceptions

For the situations below, this link is NOT required. These are Picaro-side data ingestion problems — contact support instead:

• Ad data shows 0 / empty
• Placement data cannot be fetched
• Dashboard sales / ad spend show 0
• Errors occur in bid optimization / budget adjustment

Q: Linked successfully, but campaign creation throws an error. A: The selected profile may be wrong. Use Prompt 1 to confirm accessible accounts and re-specify the profile for the target country.

Q: How to revoke a previously linked account? A: Revoke the app linkage from Amazon’s security screen. Picaro detects the expiry on the next access.

---

Prompt 4: Check version

🎯 Goal

Retrieve the current Picaro.AI version and build timestamp so a bug report or support ticket can include them.

📋 When to use

• Confirm the Picaro.AI version currently in use.
• Verify whether the latest version is running.
• Gather information needed for a bug report.

📝 Prompt

Retrieve current Picaro.AI version information:
- Version number
- Build timestamp
- Key changes in this version

Attaching the version number to a bug report speeds up the fix.

Placeholders: none

⚙️ What the AI does

1. Retrieves the version number — the semantic version of the Picaro.AI instance the AI agent environment is connected to.
   • Why the version number: it is the most reliable handle for narrowing down the fix target.
2. Retrieves the build timestamp — when that version was built.
3. Shows recent changes — the key changes from the release notes.
4. Generates a paste-ready line for bug reports — a one-line summary ready to attach.

📊 Example Output

Picaro.AI version

• Version: 2.14.3
• Build: 2026-05-15 09:22 JST
• Endpoint: picaro-mcp-server.workers.dev

Key changes (2.14.3)

• Faster N-gram analysis processing
• Improved Sponsored Products (SP) label-level KPI aggregation
• Bid optimization stability fixes

Attach this to bug reports: Picaro.AI 2.14.3 (2026-05-15 build)

🔒 Safeguards

• Read-only operation (no writes or billing changes occur).
• Internal API keys and endpoint tokens are excluded from the output.
• Release notes shown are limited to publicly released content.

🚦 Execution mode

Phase	State	Condition
Phase 1 (current)	One-shot	Run as needed
Phase 2 (Q3 2026)	Stays one-shot	Why one-shot: version checks are irregular — not a candidate for automation
Phase 3 (Q4 2026)	Stays one-shot	Notify on major version updates
Phase 4 (2027)	Stays one-shot + auto notification	Auto-notify when a version bump introduces breaking changes

👉 Next steps

• Send feedback and support requests — Attaching the retrieved version info speeds up support response.
• Check connection status and switch accounts — After a version update, sanity-check the default account.

---

Prompt 5: Diagnose your connection and data foundation

🎯 Goal

Check your connection, permissions, advertising-data subscription and ingestion status together, and establish what you can analyze right now. Also use it to narrow down “the numbers aren’t showing”.

📋 When to use

• Confirm the prerequisites before starting an analysis.
• A prompt returned nothing and you need to tell a setup problem from a data problem.
• You manage several accounts and want to be sure which one is the default.

📝 Prompt

Diagnose the Picaro MCP connection and the range of data available on this account.

1. Connection and access - version and environment, authentication state, role and plan,
   the range of tools available, and the result of each check (with cause and fix for
   anything not ok). Always confirm that the default account matches the account you want
   to analyze. If it differs, state that the account must be passed explicitly from here on.
2. Advertising profile - ID / country / currency / timezone / account type.
   Currency and timezone feed directly into how periods and amounts are read, so always write them.
3. Advertising data subscription - state and activation time per dataset.
   Say per ad type (SP / SB / SD) whether it is usable for analysis, and warn not to include
   any period before the activation time.
4. Ingestion status - check <period to check> per report and per date, and identify the last
   settled day. Do not use the per-day overall status (a single ad type with no delivery drops
   the whole day to "no data" and excludes days that are actually settled).

Finish with a usable / not usable verdict, a list of constraints (what cannot be done, why,
and the workaround), and next actions (who does what to resolve it).
Mark anything you could not retrieve as "not retrievable" and do not fill it in by inference.
Do not perform any write or settings change.

Placeholders: <period to check> (e.g. the last 14 days)

🔒 Safeguards

• Read-only operation. No settings are changed and nothing is written.
• Anything that could not be retrieved is reported as “not retrievable” rather than inferred.

👉 Next steps

• Check connection status and switch accounts — if the default account is not the one you want.
• Send feedback and support requests — if a check fails for a reason you cannot resolve yourself.

---

Prompt cheat sheet

What to do	Prompt to use
Check connection status / switch accounts	Prompt 1
Re-login after a connection error	Prompt 2
Link an Amazon Ads account for new campaign creation	Prompt 3
Check version	Prompt 4
Diagnose connection, permissions and data prerequisites	Prompt 5

Related categories

• Set targets for sales, ad spend, and ACoS — After connection, registering target ACoS and TACoS makes them automatically referenced by subsequent prompts.
• Create Sponsored Products (SP) campaigns — Proceed after the link in Prompt 3 is complete.
• Send feedback and support requests — Attaching the version info from Prompt 4 speeds up the fix.