Custom Tools

When built-in tools don't cover your use case, you can create custom tools that call any HTTP endpoint. This lets your agent interact with your own APIs, internal services, or any third-party system.

Creating a Custom HTTP Tool

From the Dashboard

1. Go to your agent's Tools section.
2. Click Add Tool and select Custom Tool (API).
3. Configure the tool:

Writing a Good Description

The description is critical — it's how the agent decides when to use your tool. Be specific:

Good:  "Look up the current inventory count for a product by its SKU code.
        Returns the quantity available, warehouse location, and restock date."

Bad:   "Inventory tool"

Configuring the Request

URL Parameters

For GET requests, define query parameters:

# The agent will call:
# GET https://api.yourstore.com/inventory?sku=ABC-123

Endpoint: https://api.yourstore.com/inventory
Method: GET
Parameters:
  - name: sku
    type: string
    required: true
    description: "The product SKU code"

Request Body

For POST/PUT requests, define the JSON body schema:

# The agent will send:
# POST https://api.yourstore.com/orders
# { "customer_id": "cust_123", "items": [...] }

Endpoint: https://api.yourstore.com/orders
Method: POST
Parameters:
  - name: customer_id
    type: string
    required: true
    description: "The customer's unique ID"
  - name: items
    type: array
    required: true
    description: "List of items to order, each with sku and quantity"

Authentication

Configure authentication in the Headers section:

# API Key auth
Authorization: Bearer sk-your-api-key

# Basic auth
Authorization: Basic base64encodedcredentials

# Custom header
X-API-Key: your-api-key

Response Mapping

By default, the agent receives the full JSON response from your API. You can optionally configure response mapping to extract specific fields:

Example: Extracting Nested Data

If your API returns:

{
  "status": "ok",
  "data": {
    "inventory": {
      "sku": "ABC-123",
      "quantity": 42,
      "warehouse": "US-WEST"
    }
  }
}

Set the response path to data.inventory so the agent receives just the inventory object.

Testing Custom Tools

Before deploying, test your custom tool:

1. In the tool configuration panel, click Test Tool.
2. Fill in sample parameter values.
3. Click Run Test to see the actual API response.
4. Verify the response looks correct.
5. Save the tool configuration.

You can also test by chatting with the agent directly. Ask it a question that should trigger the tool and verify it works as expected.

MCP (Model Context Protocol) Integration

MCP lets you connect external tool servers to your agents. An MCP server exposes a set of tools over a standardized protocol, so your agent can discover and use them automatically.

What is MCP?

MCP is an open protocol that standardizes how AI agents communicate with tool servers. Instead of configuring each tool individually, you point your agent at an MCP server and it automatically discovers all available tools.

Connecting an MCP Server

1. Go to your agent's Tools section.
2. Click Add Tool and select MCP Server.
3. Enter the MCP server URL:

# Example MCP server endpoints
MCP_SERVER_URL=https://your-mcp-server.com/mcp
MCP_SERVER_URL=http://localhost:3001/mcp

4. Configure authentication if required (API key or bearer token).
5. Click Discover Tools — thinnestAI will fetch the list of available tools from the server.
6. Select which tools to enable for your agent.
7. Save.

Running Your Own MCP Server

You can build an MCP server to expose your internal tools and APIs:

# Install an MCP server framework
npm install @modelcontextprotocol/server

# Or use Python
pip install mcp

Your MCP server defines tools with schemas, and thinnestAI agents can call them just like built-in tools.

MCP Use Cases

• Internal APIs — Expose company-specific tools without building custom integrations for each one.
• Shared tool servers — One MCP server can serve tools to multiple agents.
• Third-party MCP servers — Connect to the growing ecosystem of public MCP servers.

Best Practices

Tool Naming

• Use snake_case names: check_inventory, create_order, get_user_info.
• Make names action-oriented: the agent should understand what the tool does.

Descriptions

• Describe inputs and outputs clearly.
• Mention edge cases: "Returns null if the user is not found."
• Include example values when helpful.

Error Handling

• Your API should return meaningful error messages.
• The agent will read error responses and can explain them to the user or retry.
• Use standard HTTP status codes (400 for bad input, 404 for not found, etc.).

Security

• Use HTTPS for all production endpoints.
• Rotate API keys regularly.
• Limit tool permissions to only what the agent needs (read-only if possible).
• Consider rate limiting on your API to prevent excessive calls.

Example: Order Status Checker

Here's a complete example of a custom tool that checks order status:

Tool Configuration:

Parameters:

Agent conversation:

User:    "Where's my order ORD-78901?"
Agent:   [calls check_order_status with order_id="ORD-78901"]
Agent:   "Your order ORD-78901 is currently in transit. It's expected to
          arrive by March 8th. Your tracking number is 1Z999AA10123456784."

Next Steps

• CRM & Webhooks — Connect to CRMs and send data to external systems.
• Built-in Tools — Browse all pre-built tools available.