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

# Configure Tools

> Connect your agent to external APIs and services for real-time data and actions

Tools let your agent interact with external systems—checking inventory, booking appointments, processing payments, or anything your API can do.

## How Tools Work

When a user asks a question that requires external data, your agent:

1. Recognizes the need to call a tool
2. Extracts relevant parameters from the conversation
3. Calls your API endpoint
4. Interprets the response
5. Replies to the user

<Frame>
  ```mermaid theme={null}
  sequenceDiagram
      participant User
      participant Agent
      participant Tool as External API
      
      User->>Agent: "What's my order status?"
      Agent->>Agent: Identify: need order_lookup tool
      Agent->>Tool: GET /orders/12345
      Tool->>Agent: {"status": "shipped", "eta": "Dec 28"}
      Agent->>User: "Your order has shipped and should arrive by Dec 28!"
  ```
</Frame>

## Types of Tools

<AccordionGroup>
  <Accordion title="API Tools" icon="code">
    Connect to any REST API. You define the endpoint, parameters, and how to interpret responses.

    **Examples:**

    * Order lookup
    * Appointment booking
    * Inventory check
    * CRM updates
  </Accordion>

  <Accordion title="Website Tools" icon="globe">
    Let your agent fetch and read web pages in real-time.

    **Examples:**

    * Check current pricing
    * Read latest blog posts
    * Verify stock on your website
  </Accordion>

  <Accordion title="Image Generation Tools" icon="image">
    Generate images based on user requests using AI.

    **Examples:**

    * Create custom graphics
    * Generate product mockups
  </Accordion>

  <Accordion title="Handoff Tools" icon="arrow-right-arrow-left">
    Transfer the conversation to another agent or human.

    **Examples:**

    * Escalate to support
    * Transfer to sales
    * Route to specialist
  </Accordion>

  <Accordion title="MCP Connectors" icon="server">
    Connect to Model Context Protocol servers for complex integrations.

    **Examples:**

    * Database access
    * File system operations
    * Custom business logic
  </Accordion>
</AccordionGroup>

## Creating an API Tool

<Steps>
  <Step title="Open Your Agent">
    Go to your agent and navigate to the **Tools** section.
  </Step>

  <Step title="Add New Tool">
    Click **Add Tool** and select **API Tool**.
  </Step>

  <Step title="Define the Tool">
    Fill in the tool configuration:

    | Field           | Description                                | Example                                                       |
    | --------------- | ------------------------------------------ | ------------------------------------------------------------- |
    | **Name**        | A clear, descriptive name                  | `check_order_status`                                          |
    | **Description** | When should the agent use this tool?       | "Use this tool when a customer asks about their order status" |
    | **API Schema**  | OpenAPI-style schema defining the endpoint | See below                                                     |
  </Step>

  <Step title="Configure the Schema">
    Define your API endpoint using a JSON schema:

    ```json theme={null}
    {
      "type": "object",
      "properties": {
        "endpoint": {
          "type": "string",
          "const": "https://api.yourstore.com/orders/{order_id}"
        },
        "method": {
          "type": "string",
          "const": "GET"
        },
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string",
              "description": "The customer's order number"
            }
          },
          "required": ["order_id"]
        },
        "headers": {
          "type": "object",
          "properties": {
            "Authorization": {
              "type": "string",
              "const": "Bearer your-api-key"
            }
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Test the Tool">
    Use the test panel to verify the tool works:

    1. Enter sample parameter values
    2. Click **Test**
    3. Review the API response
  </Step>

  <Step title="Save and Enable">
    Toggle the tool to **Active** and save your agent.
  </Step>
</Steps>

## Tool Best Practices

<AccordionGroup>
  <Accordion title="Write Clear Descriptions" icon="pencil">
    The description tells the AI when to use the tool. Be specific:

    **Good:**

    > "Use this tool when the customer wants to know the status of their order. Requires an order number in format ORD-XXXXX."

    **Less effective:**

    > "Order lookup"
  </Accordion>

  <Accordion title="Handle Errors Gracefully" icon="triangle-exclamation">
    Your API should return clear error messages. In your system prompt, add instructions for handling failures:

    > "If an order lookup fails, apologize and ask the customer to verify their order number. If it fails again, offer to connect them with support."
  </Accordion>

  <Accordion title="Secure Your API" icon="lock">
    * Use API keys or OAuth tokens
    * Implement rate limiting
    * Validate input parameters
    * Never expose sensitive data in responses
  </Accordion>

  <Accordion title="Keep Responses Simple" icon="compress">
    Return only what the agent needs. Large, complex responses slow down the conversation and may confuse the AI.

    **Good response:**

    ```json theme={null}
    {
      "order_id": "ORD-12345",
      "status": "shipped",
      "eta": "2024-12-28",
      "tracking_url": "https://..."
    }
    ```
  </Accordion>
</AccordionGroup>

## Creating a Website Tool

Website tools let your agent read web pages in real-time:

<Steps>
  <Step title="Add Website Tool">
    In the **Tools** section, click **Add Tool** → **Website Tool**.
  </Step>

  <Step title="Configure the Tool">
    | Field      | Description                      |
    | ---------- | -------------------------------- |
    | **URL**    | The page to fetch                |
    | **Prompt** | Instructions for what to extract |
  </Step>

  <Step title="Example Configuration">
    ```
    URL: https://yourstore.com/products/widget

    Prompt: Extract the current price, availability status, 
    and key features from this product page.
    ```
  </Step>
</Steps>

## Creating an Image Generation Tool

<Steps>
  <Step title="Add Image Tool">
    Click **Add Tool** → **Image Generation**.
  </Step>

  <Step title="Configure the Tool">
    | Field               | Description                      |
    | ------------------- | -------------------------------- |
    | **Name**            | Tool name (e.g., `create_logo`)  |
    | **Description**     | When to use it                   |
    | **Prompt Template** | Base prompt for image generation |
    | **Credit Cost**     | How many credits this uses       |
  </Step>
</Steps>

## Creating a Handoff Tool

Transfer conversations to other agents or humans:

<Steps>
  <Step title="Add Handoff Tool">
    Click **Add Tool** → **Handoff**.
  </Step>

  <Step title="Configure the Tool">
    | Field           | Description                  |
    | --------------- | ---------------------------- |
    | **Child Agent** | The agent to transfer to     |
    | **Description** | When to initiate the handoff |
  </Step>

  <Step title="Example Use Cases">
    * General agent → Billing specialist
    * Sales agent → Technical support
    * Bot → Human operator
  </Step>
</Steps>

## Connecting MCP Servers

For advanced integrations, connect Model Context Protocol servers:

<Steps>
  <Step title="Add Connector">
    Go to **Settings** → **Integrations** → **Add Connector**.
  </Step>

  <Step title="Enter Server URL">
    Provide the MCP server URL:

    ```
    https://your-mcp-server.com
    ```
  </Step>

  <Step title="Authenticate (if required)">
    Some MCP servers require authentication. Complete any OAuth flow or enter credentials.
  </Step>

  <Step title="Add to Agent">
    In your agent's **Tools** section:

    1. Click **Add Tool** → **MCP Connector**
    2. Select the connector
    3. Choose which tools to enable (whitelist)
  </Step>
</Steps>

## Tool Credits

Some tools cost credits to use:

| Field           | Purpose                            |
| --------------- | ---------------------------------- |
| **Credit Cost** | Credits deducted when tool is used |

Configure credit costs per tool in the tool settings. Users with monetization enabled will have credits deducted automatically.

## SDK Alternative

Manage tools programmatically:

```typescript theme={null}
// Update agent with tools
const updatedAgent = await client.agents.update(agentId, {
  tools: [
    {
      name: 'check_order_status',
      description: 'Look up order status by order number',
      apiSchema: {
        type: 'object',
        properties: {
          endpoint: {
            type: 'string',
            const: 'https://api.yourstore.com/orders/{order_id}'
          },
          method: { type: 'string', const: 'GET' },
          parameters: {
            type: 'object',
            properties: {
              order_id: { type: 'string', description: 'Order number' }
            },
            required: ['order_id']
          }
        }
      },
      active: true,
      creditCost: 0
    }
  ]
});
```

## What's Next

<CardGroup cols={2}>
  <Card title="Set Up Monetization" icon="dollar-sign" href="/guides/monetization">
    Charge credits for tool usage.
  </Card>

  <Card title="View Analytics" icon="chart-line" href="/guides/analytics">
    Monitor tool usage and performance.
  </Card>
</CardGroup>