Guide

Custom Tools

Define your own API endpoints for agents to call. Specify the URL, parameters, and authentication — the agent decides when to use it.

Find it in

What Are Custom Tools?

Custom tools let your agent make HTTP requests to any external API. You define the endpoint and parameters — the agent decides when to call it based on your instructions.

📝

Name

Unique identifier

get_weather

📖

Description

When to use this tool

Get current weather for a city

🔗

Method

HTTP method

GET, POST, PUT

🌐

URL

Endpoint URL

https://api.example.com/v1/data

Headers

Add headers for authentication and content type:

Header	Example Value
`Authorization`	`Bearer your-api-key`
`Content-Type`	`application/json`
`X-API-Key`	`your-api-key`

Parameters

Define parameters the agent can provide when calling the tool:

Field	Description
Name	Parameter name (e.g., `user_id`)
Type	string, number, boolean, or object
Required	Whether agent must provide this
Description	Helps agent understand what to provide
Default	Optional default value
Location	Where parameter goes (see below)

Parameter Locations

path

URL path segment

/users/{user_id}

query

Query string parameter

?city=tokyo

body

Request body (JSON)

{ "title": "..." }

header

HTTP header

X-Custom-Header: value

Example Configurations

🌤️

Weather API

Name: get_weather
Description: Get current weather for a city
Method: GET
URL: https://api.weatherapi.com/v1/current.json

Headers:
  X-API-Key: your-weather-api-key

Parameters:
  - name: q
    type: string
    required: true
    description: City name or coordinates
    location: query
  - name: units
    type: string
    default: metric
    location: query

🎫

Create Ticket API

Name: create_ticket
Description: Create a support ticket
Method: POST
URL: https://api.helpdesk.com/v1/tickets

Headers:
  Authorization: Bearer your-token
  Content-Type: application/json

Parameters:
  - name: title
    type: string
    required: true
    location: body
  - name: description
    type: string
    required: true
    location: body
  - name: priority
    type: string
    default: medium
    location: body

Security Best Practices

Use read-only endpoints when possible

If agent only needs data, don't give write access

Scope API keys narrowly

Create keys with minimal permissions for MoiAgent

Don't expose sensitive data

Agent sees all response data — be careful what APIs return

Rate limit externally

Apply limits on your API side to prevent abuse

Response Handling

When a tool is called, MoiAgent:

1Makes HTTP request with agent-provided parameters

2Receives API response

3Sanitizes large responses (~20KB limit)

4Returns result to agent for processing

Large responses?

Consider creating separate list and detail tools. List returns minimal data, detail returns full info.

Debugging Tools

Use --debug to see detailed tool execution:

Terminal

$moi --debug my-workspace/weather-agent What's the weather in Tokyo?

You'll see tool calls, parameters, and responses in the output.

Next Steps

Tools

Use pre-built GitHub and Slack tools

Agents

Best practices for agent instructions

← Tools CLI