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

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

Field	Description	Example
Name	A descriptive name the agent uses to understand the tool	`check_inventory`
Description	What the tool does — the agent reads this to decide when to use it	`Check product inventory levels by SKU`
Endpoint URL	The API endpoint to call	`https://api.yourstore.com/inventory`
HTTP Method	GET, POST, PUT, PATCH, or DELETE	`GET`
Headers	Custom headers (authentication, content type, etc.)	`Authorization: Bearer xxx`
Parameters	Input parameters the agent will fill in	`sku` (string, required)

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:

Setting	Description
Response Path	JSONPath to extract a specific field (e.g., `data.results`)
Result Description	Help the agent understand what the response contains

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:

In the tool configuration panel, click Test Tool.
Fill in sample parameter values.
Click Run Test to see the actual API response.
Verify the response looks correct.
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

Go to your agent’s Tools section.
Click Add Tool and select MCP Server.
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

Configure authentication if required (API key or bearer token).
Click Discover Tools — thinnestAI will fetch the list of available tools from the server.
Select which tools to enable for your agent.
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:

Field	Value
Name	`check_order_status`
Description	Look up the status of a customer order by order ID. Returns the current status, estimated delivery date, and tracking number if available.
Endpoint	`https://api.yourstore.com/orders/{order_id}/status`
Method	GET
Headers	`Authorization: Bearer sk-store-api-key`

Parameters:

Name	Type	Required	Description
order_id	string	Yes	The order ID (e.g., ORD-12345)

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.

​Custom Tools

​Creating a Custom HTTP Tool

​From the Dashboard

​Writing a Good Description

​Configuring the Request

​URL Parameters

​Request Body

​Authentication

​Response Mapping

​Example: Extracting Nested Data

​Testing Custom Tools

​MCP (Model Context Protocol) Integration

​What is MCP?

​Connecting an MCP Server

​Running Your Own MCP Server

​MCP Use Cases

​Best Practices

​Tool Naming

​Descriptions

​Error Handling

​Security

​Example: Order Status Checker

​Next Steps