> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inboxmate.psquared.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools & Integrations

> Extend your chatbot with tools — connect APIs, use marketplace integrations, or build custom tools.

Tools give your chatbot the ability to **take actions** — not just answer questions. With tools, your agent can look up data, send emails, create tickets, or connect to any API.

## How tools work

When a visitor asks a question that requires live data (e.g., "What's the status of my order?"), the agent calls the appropriate tool, fetches the data, and responds with the result.

Tools are called automatically based on the conversation context. You define **when** a tool should be used by writing a clear description.

<Note>
  Custom tools and MCP servers are available on the **Pro plan** and above. Some marketplace tools are available on all plans.
</Note>

## Built-in tools

These tools are automatically available when configured:

### Knowledge search

When your agent has a **vector bucket** assigned, a `search_knowledge` tool is automatically added. The agent calls it before answering any question about your business.

The search uses **multi-query semantic search** — the AI sends 2-3 short keyword queries in parallel to maximize recall from your knowledge base. Results are merged and deduplicated before being used as context.

<Tip>
  If your agent's knowledge search returns poor results, check that your vector bucket items are properly indexed (status: "Indexed" with chunk count > 0). Short, focused content chunks work better than large blocks of text.
</Tip>

### Web search

The Web Search tool allows your agent to search the internet when knowledge base results are insufficient. Configure it from **Tools & Integrations** → **Marketplace**.

You can configure **tool progress messages** (e.g., "Searching knowledge base..." or "Running web search...") that are shown to visitors while the tool runs. Configure these in your agent's **Widget** settings under **Tool Messages**.

## Types of tools

### Marketplace tools

Pre-built integrations you can activate with a few clicks. Go to **Tools & Integrations** in the sidebar and click **Marketplace**.

**Currently available:**

| Category          | Tools                                                                                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------- |
| **Productivity**  | Jira Scrum Bundle (create issues, manage sprints, search epics), Twenty CRM Suite (companies, contacts, notes)  |
| **Communication** | Gmail Suite (search, read, send emails) — Beta                                                                  |
| **AI Management** | Agent Management, Contact Management, Knowledge Management, Memory Management, Scheduled Tasks, Tool Management |
| **Research**      | Web Search (no API key required)                                                                                |

<Tip>
  Want an integration we don't have yet? Send us a feature request via **Help & Support** in the app menu, or email [office@psquared.dev](mailto:office@psquared.dev).
</Tip>

### Custom API tools

Build your own tools by connecting any REST API endpoint.

<Steps>
  <Step title="Create a new tool">
    Go to **Tools & Integrations** → click **New tool**.
  </Step>

  <Step title="Configure the endpoint">
    Set the HTTP method (GET, POST, etc.) and the URL. Use curly braces for dynamic parameters:

    ```
    https://api.example.com/orders/{orderId}
    ```
  </Step>

  <Step title="Add authentication">
    Choose from: API Key (header or query), Bearer Token, or Basic Auth. Credentials are stored securely.
  </Step>

  <Step title="Define parameters">
    Add query parameters, headers, or a JSON payload. Mark parameters as **required** or optional.

    ```json theme={null}
    {
      "orderId": "{{orderId}}",
      "includeDetails": true
    }
    ```

    Parameters wrapped in `{{ }}` are filled dynamically by the agent based on the conversation.
  </Step>

  <Step title="Write a clear description">
    The description tells the agent **when** to use this tool. Be specific:

    ```text theme={null}
    Use this tool when a customer asks about their order status,
    delivery tracking, or shipment details. Requires the order ID.
    ```
  </Step>

  <Step title="Test it">
    Use the **Test** button to send a sample request and verify the response.
  </Step>
</Steps>

### MCP tools (Model Context Protocol)

Connect to external MCP servers that expose tools via the standardized MCP protocol. This is the most flexible option for complex integrations.

<Info>
  MCP tools are available on the **Business plan**.
</Info>

To add an MCP server:

1. Go to **Tools & Integrations** → **New tool** → select **MCP Server**
2. Enter the server URL and authentication details
3. InboxMate will auto-discover all available tools from the server

## Tool output processing

After a tool returns data, you can configure how the agent processes it:

* **Response filtering** — extract only the fields you need
* **Transformation** — rename or restructure the data
* **Error handling** — define fallback messages when the API fails

## Best practices

* **One tool per action** — don't build a Swiss army knife. Create focused tools that do one thing well.
* **Clear descriptions** — the agent decides which tool to call based on the description. Vague descriptions lead to wrong calls.
* **Test with real data** — always test your tool with realistic inputs before publishing.
* **Handle errors gracefully** — configure fallback messages so the agent doesn't say "tool failed" to visitors.