Skip to content

Built-in tools

Alpha

This page describes the current code. Tool names and limits may still change before the first release; any change will be listed in the Release Notes.

A tool is one operation an AI client may call. The extension comes with two, and both are read-only:

Tool What it does
civi_describe Describes the data. With no entity, it lists the entities below. With an entity, it lists that entity's fields: name, title, type, and the choices for short option lists. Custom fields appear as Group_Name.Field_Name. The AI calls this first, to learn exact field names
civi_get Reads records of one entity: the fields to return, filters, sort order, and how many rows. It is a bounded APIv4 get, not a way to run any API call

Both run as the signed-in user, with that user's CiviCRM permissions (APIv4 with checkPermissions on). If someone cannot see a contact, case or field in CiviCRM, these tools cannot either. Both need the access CiviCRM permission, on top of the permission to connect.

The ten entities

The two tools work on these entities only. The AI cannot name any other.

Entity What it is
Contact People, organisations and households
Activity Activities: calls, meetings, emails and so on
Case Cases (CiviCase)
Contribution Donations and payments (CiviContribute)
Membership Memberships (CiviMember)
Event Events (CiviEvent)
Participant Event registrations
Relationship Relationships between contacts
CaseContact Which contacts belong to which case
ActivityContact Which contacts are on an activity, and in which role (source, assignee or target)

A field on a linked record can be read through the entity it belongs to, such as contact_id.display_name on an Activity. The signed-in user's permissions apply to those too.

Limits

  • Rows: each call returns at most the site's row cap (default 50; see Setup). The result says when there were more rows than it returned, so the AI can narrow the question or ask for the next page.
  • Fields and filters: up to 40 fields and 20 filters per call, using the usual APIv4 comparisons (=, LIKE, IN, BETWEEN, IS NULL and so on). Pattern matching with REGEXP is not offered.
  • Credentials: fields whose names mark them as credentials (password, API key, hash, token, checksum and similar) cannot be selected, filtered or sorted on, and are left out of civi_describe. Nor can the links to payment processors, saved payment tokens or recurring contributions, or any field reached through them.
  • Long text is cut to 1,000 characters per field.

Narrowing them, and adding more

  • Narrowing. Usually with a permission profile, on screen: it decides who gets each tool and which entities they may read (Setup § 3). A developer can also make a tool need an extra CiviCRM permission, from their own extension (Adding your own tools § Narrowing a core tool).
  • No widening. Neither tool ever reads more than the person's own CiviCRM permissions allow, and the ten entities above are fixed in this extension's code, so no setting or other extension can add one.
  • Adding more. Other extensions add their own tools by listening to an event, a bit like WordPress's Abilities API. A tool can also be backed by a SearchKit display that an administrator builds; today an extension publishes it in code, and choosing displays from an admin screen is on the Roadmap. See Adding your own tools, and Publishing a SearchKit display before you publish one that bypasses ACLs.