How to Add New Tool

Tool actions define what operation the AI agent can perform using the API.

Steps:

1. Click on Add New Tool
2. Enter the following details:

Field	Description
Action Name	Name of the action (e.g., Reschedule Booking)
Description(Optional)	What the action does
Endpoint URL	API endpoint URL
Request Method	GET, POST, PUT, DELETE
Headers	Required headers from API documentation
Body	Request payload

Tool Name

Definition:
A unique identifier for the tool action. The agent uses this name internally to trigger the correct API call.

Requirements:

• Must be unique
• Use snake_case format
• No spaces allowed

Example:

reschedule_booking

---

Description (Optional)

Definition:
Explains when and why the agent should use this action. This helps the AI understand the correct context for calling the API.

Example:

Use this action to reschedule a Cal.com booking when the user provides a new date and time.

---

HTTP / Request Method

Definition:
Specifies the type of operation to perform on the API.

Supported methods:

• GET → Retrieve data
• POST → Create data
• PUT → Update data
• PATCH → Partially update data
• DELETE → Remove data

Example:

GET

---

Endpoint URL

Definition:
The API endpoint where the request will be sent. You can use input variables to dynamically insert values.

Static example:

https://api.cal.com/v1/bookings

Dynamic example using input variable:

https://api.cal.com/v1/bookings/{{booking_id}}

Here, {{booking_id}} will be dynamically provided by the agent.

---

Headers

Definition:
Headers provide additional information required by the API, such as authentication and content type.

Common headers example:

Key	Value
Content-Type	application/json
Authorization	Bearer access_token

Example configuration:

Content-Type: application/json
Authorization: Bearer {{access_token}}

---

Query Parameters

Definition:
Query parameters allow you to filter or modify the API response. These are appended to the endpoint URL.

Example configuration:

Key	Value
status	booking_status

Final request example:

https://api.cal.com/v1/bookings?status=upcoming

---

Request Body

Definition:
The request body contains the data sent to the API when creating or updating resources.

You can use input variables to dynamically pass values.

Example:

{
  "start": "{{start_time}}",
  "end": "{{end_time}}",
  "eventTypeId": "{{event_type_id}}",
  "reason": "User requested reschedule"
}

---

Input Variables (Dynamic Placeholders)

Input variables are dynamic placeholders written inside double curly braces.

Format:

{{variable_name}}

These placeholders are replaced with real values when the agent executes the API request during a conversation.

The agent determines these values using:

• User input
• Conversation context
• Extracted variables configured in the agent workflow
• Agent configuration

Examples:

{{booking_id}}
{{start_time}}
{{end_time}}
{{event_type_id}}
{{email}}

Input variables can be used in:

• Endpoint URL
• Query Parameters
• Request Body

---

Complete Example: Reschedule Booking (Cal .com)

Action Name

reschedule_booking

Method

POST

Endpoint URL

https://api.cal.com/v1/bookings/{{booking_id}}/reschedule

Headers

Content-Type: application/json
Authorization: Bearer {{access_token}}

How Input Variables Work

Conversation Example:

User: I want to reschedule my appointment for tomorrow at 10 AM.

What SigmaMind AI does:

1. Extracts values from conversation
2. Maps values to variables
3. Replaces variables in the API body
4. Calls the API automatically

Final API Request Sent:

{
  "start": "2026-03-10T10:00:00Z",
  "end": "2026-03-10T10:30:00Z",
  "eventTypeId": "12345",
  "reason": "User requested reschedule"
}

3. Click Submit Action

The action is now available for your agent.

You can add new actions to an existing integration in the App Marketplace in the same way, allowing your AI agent to perform additional operations using the connected app.

How to Test Tool

You can test a tool action to verify that the API works correctly before using it in your agent.

Steps:

1. Go to Tool Library from the Agent Builder
2. Select the tool (for example, Cal.com)
3. In the Tools section, locate the tool you want to test
4. Click the Test button next to the action

This opens the Mock Test API screen.

5. Enter test values for the detected input variables (such as {{start_date}}, {{end_date}}, {{event_type_id}})
6. Click Run Test
7. Review the response to confirm the API is working correctly
   

---

Step 5: Use the Custom Tool in the Agent

After creating and testing your tool actions, you must add them to your agent. This allows the agent to call the tool during conversations and perform real-world operations.

Method 1: Go to your Tools Section

1. Find your tool (like get_available_slots)
2. Click Add to Agent
3. Fill in the Instructions — describe when the AI should invoke this tool
4. Bind placeholders (if required) — see the +Add Mapping section below
5. Click Add to Agent to confirm

Method 2: Via the Agent Builder

1. Open the Agent Builder
2. Click Add Tool
3. Click Add Integration Tool
4. Select the app you created or configured
5. Select the tool you want the agent to use
6. Click Add to Agent

---

+Add Mapping: Binding Response Values as Dynamic Variables

The +Add Mapping feature lets you extract specific fields from a tool’s response and save them as named variables. These variables can then be referenced in subsequent prompts or tool inputs using the {{variable_name}} syntax.

Understanding the Sample Response

Click View sample response (from last run) to expand a live preview of the JSON returned by the tool. This helps you identify the exact field names to use when configuring mappings.

For example, the get_customer_list tool returns a structure like this:

{
  "contacts": [
    {
      "vid": 3285518502114,
      "addedAt": 1763618783287,
      "portal-id": 244418020,
      "is-contact": true,
      "properties": {
        "company": {
          "value": "HubSpot"
        }
      }
    }
  ]
}

Use the Copy JSON button inside the sample response panel to copy the full response and inspect nested fields before setting up your mappings.

To map a nested field like company.value, you would enter contacts.0.properties.company.value as the field path in the left input.

---

How to Configure a Mapping

1. In the tool configuration panel, scroll to Store response values as dynamic variable
2. Confirm the Root path — this is auto-populated based on the tool name (e.g., hubspot_get_customer_info)
3. In the left field, enter the field name from the API response (e.g., user_id)
4. In the right field, the full variable path is auto-generated (e.g., hubspot_get_customer_info.user_id)
5. Click +Add Mapping to add more fields as needed
6. Use the 🗑 delete icon to remove any unwanted mappings

Example Mappings for get_customer_list

Based on the actual sample response, here are useful field mappings you can configure:

Field Path	Mapped Variable	Reference in Prompts
contacts.0.vid	hubspot_get_customer_list.vid	{{vid}}
contacts.0.addedAt	hubspot_get_customer_list.addedAt	{{addedAt}}
contacts.0.portal-id	hubspot_get_customer_list.portal_id	{{portal_id}}
contacts.0.is-contact	hubspot_get_customer_list.is_contact	{{is_contact}}
contacts.0.properties.company.value	hubspot_get_customer_list.company	{{company}}

Using Variables in Subsequent Steps

Once mapped, reference these variables anywhere in your agent flow:

Send an email to {{email}} with a personalized greeting.
Look up account for user ID: {{user_id}}
Pass {{company}} to the CRM update tool input field.

Reference these variables as {{variable_name}} in any subsequent prompt or tool input field.

---

Tips & Best Practices

Preview sample response before mapping

Click View sample response (from last run) before adding mappings to confirm exact field names returned by the API. If no sample is available, run the tool once from the Test panel first.

Map only what you need

Only map fields you’ll actually use in downstream steps. Unused variables add clutter without any benefit.

Variable names are case-sensitive

Ensure consistency between the mapped name and how you reference it in prompts. {{Email}} and {{email}} are treated as different variables.

Root path prefix is automatic

The root path prefix (e.g., hubspot_get_customer_info.) is automatically prepended. You only need to type the leaf field name (e.g., user_id) in the left input field.

---

2. Using the API

If you prefer programmatic control, use the Integration Tools API to create a tool.

Field descriptions

Field	Required	Description
name	required	Unique name for the tool within this integration (e.g. get-customer)
description	required	Natural language description of what the tool does — agents use this to decide when to invoke it
method	required	HTTP method: GET, POST, PATCH, PUT, or DELETE
url	required	Full endpoint URL the tool will call (e.g. https://api.stripe.com/v1/customers/{id})
queryParams	optional	Array of query parameter definitions — each with key, value, and description
bodyParams	optional	Object describing the request body schema — used for POST / PATCH / PUT requests
headers	optional	Array of custom headers to include with every call from this tool, each with key and value

Add New Tool

curl --request POST \
  --url https://api.sigmamind.ai/v1/integrations/{integrationId}/tools \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "name": "get-customer",
  "description": "Retrieves a customer record by ID from Stripe",
  "method": "GET",
  "url": "https://api.stripe.com/v1/customers/{customerId}",
  "queryParams": [
    {
      "key": "expand[]",
      "value": "subscriptions",
      "description": "Expand nested subscription data"
    }
  ],
  "headers": [
    {
      "key": "Stripe-Version",
      "value": "2023-10-16"
    }
  ]
}'

Example Agent Workflow

1. User: I want to reschedule my appointment
2. Agent collects the required information
3. Agent calls Reschedule Booking action
4. API processes the request
5. Agent confirms the reschedule

Authentication failing: Verify credentials and authentication type

API request failing: Test API action and verify endpoint and headers

---

Best Practices

• Always follow the API documentation of the external app
• Use clear variable names
• Test actions before enabling
• Configure authentication properly
• Use descriptive action names