Agent Tool Definitions

Use these tool definitions to connect an AI agent to Atomic's subscription management workflow. They cover finding merchants, reading a user's connected subscriptions, preparing Transact sessions, and checking cancellation results.

A tool definition tells the model what a function does, when to use it, and which inputs it accepts. Your backend implements that function and supplies the credentials and user context when the model calls it. For steps that need the user's interaction, the app opens the Transact SDK to handle merchant sign-in and cancellation confirmation.

The tools.json download contains the seven definitions used by the example app, each with a name, description, and JSON input schema. Register them with your agent framework and use the Cancel Subscriptions guide to follow how the backend handlers, app, and Atomic work together. The download contains definitions only; the guide links to the example's implementation.

Download the definitions

curl -O https://docs.atomicfi.com/agent-tools/subscriptions/tools.json

Tools in this version

These summaries describe each tool's role. The download includes the full instructions for the model and each tool's input schema.

Tool	What it does
`upsert_user`	Creates the Atomic user if needed at the start of each conversation.
`find_company`	Searches for a company by name and says whether Atomic supports subscription cancellations there.
`list_cancellable_companies`	Lists companies where Atomic supports cancelling a plan.
`get_user_subscriptions`	Shows the user's connected accounts, with the bills and plans Atomic found on each.
`get_actions_for_company`	Gets the available cancel-plan and connect-account actions for the user at a merchant, including cancellations for specific subscriptions.
`get_action_config`	Creates a public token and launch configuration for a cancel-plan or connect-account action. The app displays a button to open Transact.
`check_events`	Reads the latest task statuses from stored webhooks so the agent can report cancellation progress and results.

Implement each handler on your server using the example handlers and system prompt as references for API calls, response fields, and result handling. The example uses LangChain; adapt the definition fields to your framework's tool format when using another framework.

Your backend owns execution, credentials, user sessions, and event storage. Pass userIdentifier and conversationId from your server's authenticated context. They are not tool inputs. Company and action IDs returned by Atomic remain visible to the model.

For example, this server-side LangChain code pairs the downloaded find_company definition with its handler from the example checkout. Place tools.json at the root of that checkout. Supply the user and conversation through the agent's invocation context, using values from your authenticated session.

import { readFile } from 'node:fs/promises'
import { tool } from 'langchain'
import { findCompany } from './agent/tools/find-company.js'

const snapshot = JSON.parse(await readFile('./tools.json', 'utf8'))
const definition = snapshot.tools.find((entry) => entry.name === 'find_company')
if (!definition) throw new Error('Missing find_company definition')

const findCompanyTool = tool(
  async (input, runtime) => {
    const { userIdentifier, conversationId } = runtime.context ?? {}
    if (!userIdentifier || !conversationId) {
      throw new Error('Authenticated user and conversation context are required')
    }
    const result = await findCompany.handler(input, { userIdentifier, conversationId })
    return JSON.stringify(result)
  },
  definition
)

// Include findCompanyTool in your agent's tools array.

This example registers one lookup tool. For get_action_config, keep the public token and launch configuration in an artifact sent only to the app. The example's tool adapter shows how to separate that artifact from the result the model receives.

Versions

The tool set is versioned. formatVersion describes the file format, and source.commit records the example revision the definitions come from. We measure how agents use these tools, so names, inputs, and the number of tools can change between versions. Before you update, compare the source commit with the one you built against, and review the definitions, handlers, and system prompt together. The download notes describe the file format and how it's produced.