AI Connectors: Tool Reference

This is a companion reference to the Capsule AI Connectors doc. It lists every tool an AI tool can call once connected, grouped by the area of your account it covers.

Contacts, Opportunities & Projects

Tool	What it does
`get_contact`	Get a single Contact by ID
`list_contacts`	List or filter Contacts
`update_contact`	Update Custom Field values on a Contact
`create_contact`	Create a Contact - either a Person or an Organization
`get_opportunity`	Get a single Opportunity by ID
`list_opportunities`	List or filter Opportunities
`calculate_value_of_opportunities`	Get the total and projected value of a filtered set of Opportunities
`update_opportunity`	Update Custom Field values on an Opportunity
`create_opportunity`	Create an Opportunity - it must be linked to a Contact and placed on a Milestone
`get_project`	Get a single Project by ID
`list_projects`	List or filter Projects
`update_project`	Update Custom Field values on a Project
`create_project`	Create a Project - it must be linked to a Contact

The three update_* tools can only add or change Custom Field values - they cannot rename a record, reassign its owner, or touch any other core field. Existing Custom Field values are overwritten, not merged, and there's no way to delete a value through these tools.

The create_* tools aren't limited to Custom Fields. When you create a Contact, Opportunity or Project you can set its core details too, such as its name, owner, team, tags, dates and Custom Field values, and apply Tracks to it. Once a record exists, the update_* tools can only change its Custom Fields.

Sales Pipelines, Milestones & Lost Reasons

Tool	What it does
`list_pipelines`	List Sales Pipelines, optionally searching by name
`get_pipeline`	Get a single Pipeline by ID
`list_milestones`	List Milestones - for one Pipeline, or across all of them
`get_milestone`	Get a single Milestone by ID
`list_lost_reasons`	List Lost Reasons, optionally searching by name
`get_lost_reason`	Get a single Lost Reason by ID

Project Boards & Stages

Tool	What it does
`list_boards`	List Project Boards, optionally searching by name
`get_board`	Get a single Board by ID
`list_stages`	List Stages - for one Board, or across all of them
`get_stage`	Get a single Stage by ID

Tags & Custom Fields

Tool	What it does
`get_tag`	Get a Tag definition by ID, for Contacts, Opportunities or Projects
`list_tags`	List Tag definitions for Contacts, Opportunities or Projects
`get_custom_field`	Get a Custom Field definition by ID
`list_custom_fields`	List Custom Field definitions (this doesn't include DataTag fields)
`list_custom_fields_for_data_tag`	List the Custom Fields grouped under a specific DataTag

Activities, Entries & Tasks

Tool	What it does
`list_entries`	List notes, emails and completed Tasks logged against a Contact, Opportunity or Project
`get_entry`	Get a single note, email or completed Task by ID
`list_activities`	List Activities (notes, emails, Tasks) with filtering
`list_activity_types`	List the Activity Types available on the account
`list_tasks`	List Tasks (open only by default - see Task filters below)
`list_task_categories`	List Task Categories, optionally searching by name
`get_task`	Get a single Task by ID
`create_entry`	Create a note on a Contact, Opportunity or Project (attachments aren't currently supported)
`create_task`	Create a Task, optionally linked to a Contact, Opportunity or Project

Tracks

Tool	What it does
`get_track`	Get a Track by ID, including its Tasks
`list_tracks`	List the Tracks applied to a Contact, Opportunity or Project
`get_track_definition`	Get a Track Definition by ID - a Track Definition describes a sequence of Tasks
`list_track_definitions`	List Track Definitions, optionally filtering by record type (Contacts, Opportunities or Projects)

Users & Teams

Tool	What it does
`list_users`	List Users on the account
`get_user`	Get a single User by ID
`get_current_user`	Get the User that your AI tool is currently authenticated as
`list_teams`	List Teams, including their members
`get_team`	Get a single Team by ID, including its members

Account

Tool	What it does
`get_account`	Get the current Capsule account - its name, subdomain and URL, plus the URL templates for linking to a Contact, Opportunity or Project in Capsule

list_pipelines, list_lost_reasons, list_boards, list_milestones, list_stages, and any tool listed above with an ID lookup all return standard pagination - 100 records per page by default. Ask your AI tool for the next page if you have more results than that.

Creating records

The create_* tools share a few rules. This table shows what each one needs, and what else you can set.

Tool	Required	Optional details
`create_contact`	The Contact type (person or organization), plus the name for an organization	Title, job title, parent organization (people only), about, owner, team, addresses, phone numbers, email addresses, websites, tags, Tracks, Custom Field values
`create_opportunity`	A name, a Contact and a Milestone	Description, expected close date, closed date, owner, team, value and currency, duration, lost reason, probability, tags, Tracks, Custom Field values
`create_project`	A name and a Contact	Description, linked Opportunity, owner, team, Stage (and its Board), status, start, expected close and closed dates, tags, Tracks, Custom Field values
`create_task`	A description and a due date	Detail, due time, owner, category, a linked Contact, Opportunity or Project, status, completed time, repeat
`create_entry`	The note content	A linked Contact, Opportunity or Project, Activity Type, date and time of the entry

Rules that apply when creating records

Linking: A Task or note can be linked to at most one Contact, Opportunity or Project. An Opportunity and a Project must each be linked to a Contact.
Defaults: The owner is the current user, the team is the owner's default team (ignored if your plan doesn't include Teams), a note's Activity Type is Note, a Project's status is Open, and an Opportunity's currency is the owner's default.
Names that don't exist yet: A Tag or organization name that doesn't exist creates a new one. A Task Category name that doesn't exist creates a new one for Administrators only, and returns an error for everyone else. Where you can, use IDs instead of names, and use the list_* tools to find them.
Completed and repeating Tasks: Set the status to completed to create an already-completed Task. The completed time only applies together with that status, and defaults to now. A Task can repeat weekly, monthly or yearly, every given number of weeks, months or years.
Closing Projects: Setting a closed date closes the Project. Send it with a status of closed, or leave the status out, because a status of open discards the date. If a Project is created as closed with no date, today's date is used.
Notes:create_entry creates notes. Attachments aren't currently supported.

Filtering Contacts, Opportunities, Projects and Activities

The list_contacts, list_opportunities, list_projects, and list_activities tools accept a filter made up of one or more conditions, each checking a field against a value using an operator. You don't need to build this yourself - just describe what you're looking for and your AI tool will construct the filter. There are some underlying rules:

Text fields (e.g. name, email, city) support is, is not, contains, starts with, and ends with.
Number fields (e.g. IDs, tag IDs) support is, is not, is greater than, and is less than.
Date fields (e.g. date added, date updated) support is, is not, is after, and is before.
Yes/no fields (e.g. has email address, has open tasks) support is and is not.

For Contacts specifically, you can also filter on a parent Organization's name, tags, and Custom Field values - useful for questions like "which people work at organizations tagged as VIP".

Filtering Tasks

list_tasks uses a simpler set of filters rather than the condition-based filter above: updated since (a date and time), status (open, completed or pending), owner, category, a due-date range, whether the Task is repeating, and the type of record it's related to (Contact, Opportunity or Project). By default, only open Tasks are returned unless you ask for a different status.

Go to section