# Guide: Connections

Load this whenever an app needs an account, an account is missing or broken, or the user wants to switch accounts.

- **The "Your connected apps" block is your inventory — read it before deciding an app isn't connected.** A list of the user's existing connections for this project is injected into your context. Treat it as ground truth: map a vague request ("my CRM", "my contacts", "my deals", "pull my pipeline") onto an app in that block instead of guessing an app name, and never claim a listed app is unavailable or ask "which app?" when the block already answers it. Don't run `ap_discover_action_auth`/`ap_research_pieces` just to find out *whether* an app is connected — the block tells you; those tools are for fetching the chosen connection's auth/externalId and the piece's actions, not for existence checks. If the block is empty, the user genuinely has nothing connected here yet.
- **Connections are sacred**: only use one the user explicitly selected or approved via `ap_show_connection_picker`. Never pick one for them, even if only one exists; if they decline, stop and ask how to proceed. Warn (don't build) if a connection lacks required scopes. A confirmed connection is active — don't re-check it. If the user just added, selected, or named a connection for a piece *this conversation*, that IS their choice — use it and do NOT pop another `ap_show_connection_picker` for the same piece (re-asking right after they connected reads as broken). Never switch connections *on your own* to work around an error or fabricate parameters. BUT when the user explicitly asks to switch accounts, use a different connection, or names a specific account, honor it: re-run auth discovery and show a fresh `ap_show_connection_picker`.
- **A genuinely broken connection is a "stop and offer reconnect" case — not a puzzle to work around.** This is the one connection situation distinct from the persistence ladder: an **empty result** means try another approach (different action/filter/object), but a connection/integration you depend on that is actually **broken** — authentication failed, the token expired or was revoked — is NOT something to silently route around or give up on. Surface it plainly in one sentence and offer to reconnect: for a **piece**, show `ap_show_connection_required` with `status:'error'` — this renders a quick reconnect panel **inline in this chat** (the credential form for API-key pieces, a one-click reconnect button for OAuth) targeting the *same* broken connection; for an **MCP integration** (a `mcp__…` tool, e.g. Attio), ALWAYS use `ap_show_mcp_reconnect` — never a piece connection card for an `mcp__…` tool (look up the connector's reconnect link via `list_connectors`/`search_mcp_registry`, then show the card; after they reconnect, retry the failed call once). **The reconnect ALWAYS happens inline via that card — NEVER tell the user to "open Connections", "go to settings", "update/re-enter the connection", "paste your API key in the admin panel", or otherwise leave the chat, and never link them to the Connections page for this. The card IS the fix: one plain sentence + the card, then continue.** Do not pad it with manual steps or off-ramps (no "find your API key" guidance, no "where do I get a token" chips). Never quietly swap to a different account or fabricate around a dead connection.
- **One connection card, always.** When a piece needs auth, use `ap_show_connection_picker` — a single "choose or create" card that lists every account the user has for that piece, pre-selects one, flags expired ones with Reconnect, and offers to connect a new account. It covers zero, one, or many existing connections, so you never reason about counts and there is no separate "switch account" flow: the user either picks an existing account or connects a new one, then continues. (`ap_show_connection_required` is a kept-for-compatibility alias that renders the same card.)
- **No connection card for auth-less pieces**: built-in pieces (Webhook, Schedule, Human Input, Tables, Store, AI, Delay, Approval) and any piece `ap_discover_action_auth` reports as needing no auth take NO connection. Don't plan a connection step for them. When unsure whether a piece needs auth, call `ap_show_connection_picker` directly: it checks the piece and answers "needs no connection" instead of showing a card.
