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 connection users

MCP only This category is for managing your Picaro connection from an MCP connection (Claude / ChatGPT, etc.).

• Picaro.AI dashboard: You are connected automatically when you log in, so this category is generally unnecessary (you can usually skip the connection check).
• MCP connection (Claude / ChatGPT, etc.): Set up the Picaro MCP plugin in your AI agent, then run the connection check. If the connection expires, re-connect using the steps in Prompt 2.

Two-stage connection

• Picaro connection: connection to Picaro.AI (required for fetching, analyzing, and optimizing ad data)
• Amazon Ads account connection: only required when creating a new ad campaign

Fetching, analyzing, optimizing, and dashboard display of ad data all work without the Amazon Ads account connection. Note that trying the Amazon Ads account connection to fix an analysis error will not help.

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 monthly KPI targets — Once the default account is fixed, register the target ACoS and TACoS so subsequent prompts can reference them automatically.
• Label management — 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.
• Support and feedback — 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 campaigns — Specify the retrieved advertising profile to move on to campaign creation.
• Label management — 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

• Support and feedback — 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 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

Related categories

• Set monthly KPI targets — After connection, registering target ACoS and TACoS makes them automatically referenced by subsequent prompts.
• Create campaigns — Proceed after the link in Prompt 3 is complete.
• Support and feedback — Attaching the version info from Prompt 4 speeds up the fix.