{ "formatVersion": 1, "source": { "repository": "https://github.com/atomicfi/manage-agent-example", "commit": "36cdefec7f014040beb07ed88e5b0fb09daa5df9" }, "tools": [ { "name": "upsert_user", "description": "\nMake sure Atomic knows this user, registering them if it doesn't. Call this once at the start of\nevery conversation, before any other tool.\n- It takes no input. The user is identified by the server, never by you.\n- Call it again if another tool fails with code 40011 (Atomic doesn't know the user), then retry\n that tool.\n- Don't mention this step to the user.", "schema": { "type": "object", "properties": {}, "additionalProperties": false } }, { "name": "find_company", "description": "\nLook up a merchant by name to see whether Atomic can cancel subscriptions there. Call this whenever\nthe user names a merchant, before you say whether Atomic can help with it.\n- Search with the name the user used, for example 'Netflix' or 'Spotify'. Typos and partial names\n work.\n- Search by merchant name only. If the user names a category such as 'streaming' or 'gym', ask which\n merchant they mean.\n- Results are candidates. Continue only with a result whose name plainly matches what the user said.\n If two results could match, ask which one. If none matches, tell the user you couldn't find that\n merchant, and don't draw conclusions about other merchants.\n- Returns Atomic's company search response; the companies are in data.\n- availableActions without 'cancel-plan': Atomic can't cancel subscriptions at this company.\n- availableActions with 'cancel-plan': call get_actions_for_company next with the company's _id. It\n tells you whether this user can cancel there right now, or has to sign in first.\n- status describes the whole company. 'disabled' means it can't be used. For 'under-maintenance',\n still call get_actions_for_company.", "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 50, "description": "The merchant's name. 50 characters at most." } }, "required": ["query"], "additionalProperties": false } }, { "name": "list_cancellable_companies", "description": "\nList the companies where Atomic supports cancellation. Use this when the user asks what you can\ncancel. For a merchant the user named, use find_company.\n- Returns Atomic's company list response; the companies are in data.\n- A company on this list supports cancellation in general. Call get_actions_for_company to see\n whether this user can cancel there right now.\n- status 'under-maintenance': cancellation there is temporarily unavailable. 'disabled': it can't be\n used.", "schema": { "type": "object", "properties": {}, "additionalProperties": false } }, { "name": "get_user_subscriptions", "description": "\nShow the user's accounts: the companies they have connected through Atomic, with the bills and plans\nAtomic last read on each. Use it when the user isn't sure what they pay for, or to check a plan's\nstatus after a cancellation.\n- The data is a snapshot from lastSyncedAt, not live.\n- connectionStatus 'connected': Atomic can read this account. 'initial': the user started connecting\n but never finished, so Atomic has no bills there. 'disconnected': the user's sign-in expired or\n was revoked, and they must sign in again through Atomic before anything else works there.\n- An empty list means the user hasn't connected any accounts. It tells you nothing about what they\n subscribe to or whether a plan is active, so say that you can't see their subscriptions yet.\n- processing true: Atomic is working on this account. Wait before starting anything new there.\n- Each account and bill lists its actions (cancel-plan and connect-account only). They come from the\n connected account, so they're never optimistic, and for a connected account they match what\n get_actions_for_company returns. A company the user hasn't connected doesn't appear here, but\n get_actions_for_company may still offer an optimistic cancellation there.\n- A plan with a pendingChange changes on pendingChange.startDate, for example a cancellation that\n takes effect at the end of the billing period.", "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Optional. Limit the result to one company, using the company's _id from find_company." } }, "additionalProperties": false } }, { "name": "get_actions_for_company", "description": "\nList what this user can do at one company right now: cancel a plan, or connect (sign in to) their\naccount there. It works whether or not the user has connected an account at the company: before they\ndo, it returns optimistic actions, such as a cancel-plan action at a single-plan company like\nNetflix. The response doesn't say whether the user has connected; get_user_subscriptions shows that.\nCall it every time before you propose a cancellation, because actions change as plans change. Offer\nonly actions it returns.\n- type 'cancel-plan': a cancellation. Name each one by its bill.name, the subscription it cancels. A\n cancel-plan action without a bill is optimistic: Atomic hasn't read the user's account yet, so\n call it 'your subscription'. Start it with get_action_config.\n- type 'connect-account': a sign-in, not a cancellation. Signing in lets Atomic read the user's\n bills at this company. Companies with many subscriptions, such as Apple or Amazon, have no\n optimistic cancellation, so the user must sign in before Atomic can offer one. Start it with\n get_action_config.\n- Both types returned: offer the cancel-plan action that matches the subscription the user means.\n Offer connect-account only when none matches, explaining that signing in may let Atomic find it.\n- Only connect-account returned: explain that the user needs to sign in to the merchant through\n Atomic before a cancellation is possible, and ask if they'd like to.\n- automated false: tell the user Atomic will open the merchant's own page and they'll finish it\n there.\n- disabled true (the merchant is under maintenance): leave it out, and offer to connect the user\n with your support team.\n- Several cancel-plan actions: list them and ask which one the user means.\n- No actions: the plan may already be cancelled. Call get_user_subscriptions with the same companyId\n and check the plan's status and pendingChange. If the plan is cancelled or inactive, or has a\n cancellation pending, tell the user that. Otherwise, say cancellation isn't available for this\n account right now and that you don't know why, then offer to connect the user with your support\n team.", "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "The company's _id, from find_company." } }, "required": ["companyId"], "additionalProperties": false } }, { "name": "get_action_config", "description": "\nPrepare Atomic's Transact SDK to run one action for the user: a 'cancel-plan' action cancels a\nplan, and a 'connect-account' action signs the user in to their account at a company, so Atomic can\nread their bills there and offer cancellations for them.\n- Pass the action's actionId and type, from get_actions_for_company or get_user_subscriptions.\n- The user's app then shows a \"Cancel \" or \"Connect \" button. Nothing reaches the\n company until the user taps it and finishes in the Atomic screen, where they may be asked to sign\n in.\n- Never ask for the user's password. Atomic collects sign-in details itself.\n- After calling, tell the user to tap the button to continue. When they leave the Atomic screen, you\n get a transact-finished or transact-closed event.\n- The app shows only the newest button, so a new one replaces any earlier button; never tell the\n user to tap an earlier one.\n- If check_events shows a connect-account task completed, call get_actions_for_company again for\n the company to find the cancellations now available. Atomic may still be reading the user's bills\n for a short while; if get_actions_for_company still returns no cancel-plan action for the\n subscription, tell the user their subscriptions are still loading rather than asking them to sign\n in again.", "schema": { "type": "object", "properties": { "actionId": { "type": "string", "description": "The actionId of the action to run." }, "type": { "enum": ["cancel-plan", "connect-account"], "description": "The action's type." }, "companyName": { "type": "string", "description": "The company's name, shown on the button, for example 'Netflix'." } }, "required": ["actionId", "type", "companyName"], "additionalProperties": false } }, { "name": "check_events", "description": "\nCheck where the user's recent Atomic tasks stand, such as a cancellation, the refresh that follows\nit, or a sign-in. Call this after a transact-finished or transact-closed event, and when the user\nasks whether a cancellation went through. The system prompt explains how to read the result and what\nto tell the user.\n- now: the current time (UTC), to tell recent tasks from earlier ones. Only count a task as part of\n the cancellation the user just worked on if its company matches and it was updated in the last 15\n minutes; older tasks are from earlier cancellations.\n- tasks: the stored task-status-updated webhooks, newest first, one row per task with its latest\n status. Each row has task_id, action (what the task did: 'cancel-plan' is a cancellation,\n 'refresh' resyncs the user's data afterwards, 'connect-account' is a sign-in), company_id (pass it\n as companyId to get_user_subscriptions to read that company's account), company_name, status\n ('processing', 'completed', or 'failed'), reason (why it failed), and updated_at (UTC). Once a\n refresh has completed, the user's new data is ready to read with get_user_subscriptions.", "schema": { "type": "object", "properties": {}, "additionalProperties": false } } ] }