Skip to main content
At the end of this page, your agent calls a toolkit action from a tool gambit, either through an AI Agent gambit or as a flow step.

​
Before you start

Before you start, sign in to the dashboard and select the organization you want to work in. Actions matter in two places. The toolkit detail page holds the organization-wide switch for each action. The tool gambit editor in the builder decides which actions one gambit offers to an AI Agent gambit, or which single action a flow step runs.

​
The Subtools panel

Open Tools, then select Open from a connected toolkit’s More actions menu. The toolkit detail page opens with the connection cards on the left and the Subtools panel on the right. The connection cards are covered in Connect a toolkit. The panel heading shows how many actions are enabled out of the total. Actions start disabled when you connect a toolkit. Expand an action row to read its Description, its Input Properties, and its Output Properties. On this page they are read only. You edit them per gambit in the builder, in the Sub-tools section. If the toolkit has several accounts, the account picker at the top of the page selects which connection you are editing. The Tool Info card on the left labels the selected connection. Edit Name or Description, then select Save. The Account picker in the tool gambit editor and the card on the Connected tab both show the display name.

​
Enable actions for a toolkit

Every switch in the panel is disabled unless the selected connection is active and your role can manage resources. Repair the connection from the Authorization card first.
1

Open Tools, then use the toolkit’s More actions menu and select Open

Pick the right account in the account picker if the toolkit has several.
2

Find the action in the Subtools panel

Search the list, or narrow it with the quick filters and the Enabled and Disabled chips.
3

Turn on the action's switch

Use Toggle all to switch the whole filtered set at once.
4

Select Save

Changes apply only after saving. Discard drops unsaved edits.
A Changes saved message confirms, and the enabled count in the heading updates.

​
Add a tool gambit in the builder

A tool gambit is the flow’s handle on one toolkit connection. There are two ways to add one.
1

Open the Tools tab in the gambit palette

The tab lists Connected tools first, including Knowledge Retrieval, CodeKit, and Component. Custom Tools, Featured, and the toolkit categories follow.
2

Drag a toolkit onto the builder

A tool gambit appears with the toolkit’s name and logo. Select it to open its editor.
Or start from the AI Agent gambit that will call the tool:
1

Select the AI Agent gambit, then Manage tools in its editor

The popover has Connect tools and Add tools tabs.
2

Pick a tool on the Add tools tab

Built-in Tools includes Knowledge Retrieval, Component, and CodeKit. Third-party toolkits appear under Integrations, and your CodeKit toolkits appear under Custom Tools. The new tool gambit is linked to the agent at once.
3

Or pick an existing tool gambit on the Connect tools tab

Select a compatible gambit already on the flow to link it to the agent.
You can also drag from the handle on the right of a tool gambit to the tool handle on the left of the AI Agent gambit. Connected tool gambits appear as badges in the agent’s Tools & Capabilities region. See AI Agent gambit.

​
The tool gambit editor

Select a tool gambit to open its editor on the right. The header shows the toolkit’s name and logo, and the sections below change with the mode.

​
Workflow Mode

The Workflow Mode switch sits at the top of the editor. It appears for a third-party toolkit, and for a CodeKit tool gambit once you pick a CodeKit toolkit. For a third-party toolkit, the switch is disabled until you select an account. Turning it on removes the link to the AI Agent gambit. Turning it off clears the success and failure routes.

​
Tool Selection

The connection buttons are shown only to members who can manage resources. See Change the connected account. If the toolkit has no connection yet, the section shows Not connected and a Connect button that starts authorization in a new browser tab.

​
Sub-tools

This section appears in agent mode. Its badge counts how many actions this gambit includes. The selection belongs to this gambit alone, so two tool gambits on the same toolkit can offer different actions.
Actions you include here are offered to the AI Agent gambit even if their switch on the toolkit detail page is off.
Until you select an account, the section reads Select an account to load its sub-tools. While the account is not active, every switch is disabled. A tooltip on each switch explains why. Expand an included action row to shape how the agent sees it: Clear descriptions matter. The AI Agent gambit reads the action description and the input descriptions to decide when to call the action and what to send. For a third-party toolkit, the gambit cannot be saved until every included action and every edited input property has a description.

​
Analytics purpose

The Analytics purpose dropdown appears on each included action in agent mode, and once per gambit in Workflow Mode. It has three options: Notification, Data sync, and Other. Other is the default.

​
Response Filtering

The Response Filtering control shows whether filtering is on. With filtering off, the full response is returned. Select Configure to open the Response Filtering dialog.
The Response Filtering dialog for a Gmail action, with the messages array expanded into its nested fields and three of them checked, 3 of 18 selected beside Select all fields, and the Done button
Check the fields the agent should receive. Checking a field also returns everything nested inside it. Select all fields checks every top-level field. With nothing checked, the full response is returned unfiltered. Select Done to close the dialog. The control then reads Active · of fields, and only those fields reach the agent.

​
Configure Action

This section appears in Workflow Mode. Action opens a searchable list of the toolkit’s actions. Only actions enabled on the toolkit page can be selected. An action that is switched off shows an Enable button that turns it on for the toolkit without leaving the builder. The selected action’s description appears under the dropdown. Members who cannot manage resources see Not enabled in place of the Enable button. A CodeKit action that is not live carries a Not deployed, Deploying, or Deploy failed badge. Its Enable button stays disabled, with the tooltip Deploy this action before enabling it. See Save and deploy. A CodeKit action in Workflow Mode needs the object type for data in its output schema. Without it, a warning under the dropdown links to Configure the action schema.

​
Input Parameters

The subsection lists the action’s inputs, with required ones marked with an asterisk. Each input shows its name and type, and an info icon with its description. Enter a fixed value, or type @ to insert a flow variable from an earlier step. Number and boolean inputs offer a toggle to switch between a direct value and a variable. Object and array inputs open a JSON editor, and the value must be valid JSON of the input type. A variable inside the JSON is sent as one text value, even when it contains line breaks or quotes. See Variables. When the whole input is one variable, Tars sends the variable value as data. If that variable is empty, the input uses its default value. With no default, Tars leaves the input out. If the input is not valid JSON, or is the wrong type, the step fails with INVALID_WORKFLOW_INPUT before the action runs. The conversation then follows the On Failure route.

​
Response

The full response is captured under the gambit’s name in the api scope, for example {{api.GambitName.field}}. Response Filtering works here as in agent mode. See Response Filtering.
Test & map for Get order status with a successful sample call for ORD-1042 and its status field mapped to the flow variable order_status
Test & map runs the action once with sample values, so you can map response fields to flow variables. A badge beside it shows how many fields the last test returned, or Not tested yet, and how many fields are mapped.
Run test executes the connected action. A write action can send messages, create records, or delete data in the connected service. Recording it as a test run does not simulate or undo those effects. Choose a read-only action or a safe test connection before continuing.
1

Select Test & map

The Test & map dialog opens with a Sample inputs field for each input.
2

Enter sample values and select Run test

The test makes a real call, recorded as a test run. Your step inputs stay unchanged.
3

Pick a field under Result

Result shows Succeeded or Failed. Search the fields with Search fields.
4

Map the field to a flow variable

Select Map, or Map list for a list. Enter a name in lowercase letters, digits, and underscores, starting with a letter.
5

Select Done, then Save in the gambit editor

Later steps read the mapped value through the @ menu, in the flow scope.
Inside a list, a field offers Item 0 only for one entry, or Every item for that field across the whole list. The index follows the entry you picked. Saving the gambit keeps response field paths, array paths, and mappings with the step, not the full test result. Reopen the dialog to use the saved field structure and mappings. Sample values are not stored. Run the action again to view them, with the same real-action precautions. The Flow variables list below the response shows each mapping as a Response field and its Flow variable. Select Add to enter a response field path and a variable name by hand, for example before you test the action. A warning icon marks a mapped field that Response Filtering removes from the response.

​
Settings

​
Routing

Shown only in Workflow Mode. On Success and On Failure each open a Jump to… dropdown of gambits. Point On Success at the step that continues with the result. Point On Failure at a recovery step, such as a message that offers a retry or a handoff. The tool gambit shows the two routes as Success and Failure handles.

​
Verify

In Workflow Mode, Test & map checks one call on its own. To test the whole flow, select Test in the toolbar and run the flow into the tool gambit. In agent mode, the AI Agent gambit calls the action when the conversation needs it. In Workflow Mode, the call runs and the conversation follows the On Success route. See Test your agent for the test run.