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

# Tools Reference

> Complete reference for all Agent-TS tool definitions

# Agent-TS Tools Reference

Tools are OpenAI-callable functions that allow the agent to perform wallet operations. Each tool has a definition (schema) and a handler (implementation).

## Wallet Tools

### check\_balance

Get the user's current wallet balance.

```typescript theme={null}
{
  name: "check_balance",
  description: "Get the user's current wallet balance",
  parameters: {
    type: "object",
    properties: {
      currency: {
        type: "string",
        enum: ["SLE", "USD"],
        description: "Currency to check (default: SLE)"
      }
    }
  }
}
```

**Example Usage:**

* "What is my balance?"
* "Check my USD balance"
* "How much money do I have?"

***

### get\_transactions

View recent transaction history.

```typescript theme={null}
{
  name: "get_transactions",
  description: "Get the user's recent transaction history",
  parameters: {
    type: "object",
    properties: {
      limit: {
        type: "integer",
        description: "Number of transactions (default: 10, max: 50)"
      },
      currency: {
        type: "string",
        enum: ["SLE", "USD"]
      }
    }
  }
}
```

**Example Usage:**

* "Show my recent transactions"
* "What are my last 5 transactions?"
* "Transaction history"

***

### initiate\_transfer

Send money to another user or card.

```typescript theme={null}
{
  name: "initiate_transfer",
  description: "Send money to another user or card serial",
  parameters: {
    type: "object",
    properties: {
      recipient: {
        type: "string",
        description: "Phone number or card serial"
      },
      amount: {
        type: "number",
        description: "Amount to send"
      },
      currency: {
        type: "string",
        enum: ["SLE", "USD"],
        default: "SLE"
      },
      memo: {
        type: "string",
        description: "Optional transfer note"
      }
    },
    required: ["recipient", "amount"]
  }
}
```

**Example Usage:**

* "Send 5000 to +23279123456"
* "Transfer 1000 SLE to CARD0001"
* "Pay 500 to 079123456"

***

### get\_account\_limits

Check transaction and spending limits.

```typescript theme={null}
{
  name: "get_account_limits",
  description: "Get the user's account limits and usage",
  parameters: {
    type: "object",
    properties: {
      currency: {
        type: "string",
        enum: ["SLE", "USD"]
      }
    }
  }
}
```

**Example Usage:**

* "What are my limits?"
* "Check my daily limit"
* "How much can I send?"

***

## Card Tools

### get\_user\_cards

List all cards linked to the user's account.

```typescript theme={null}
{
  name: "get_user_cards",
  description: "Get list of user's linked NFC cards",
  parameters: {
    type: "object",
    properties: {}
  }
}
```

**Example Usage:**

* "Show my cards"
* "What cards do I have?"
* "List my linked cards"

***

### link\_card

Activate and link a new NFC card.

```typescript theme={null}
{
  name: "link_card",
  description: "Link a new NFC card to the user's account",
  parameters: {
    type: "object",
    properties: {
      card_serial: {
        type: "string",
        description: "Card serial number (e.g., CARD0001)"
      },
      pin: {
        type: "string",
        description: "4-digit PIN for the card"
      }
    },
    required: ["card_serial", "pin"]
  }
}
```

**Example Usage:**

* "Link card CARD0001 with PIN 1234"
* "Activate my new card"
* "Add card CARD0002"

***

### block\_card

Block/freeze a card.

```typescript theme={null}
{
  name: "block_card",
  description: "Block a card to prevent transactions",
  parameters: {
    type: "object",
    properties: {
      card_serial: {
        type: "string",
        description: "Card serial number to block"
      },
      reason: {
        type: "string",
        description: "Reason for blocking"
      }
    },
    required: ["card_serial"]
  }
}
```

**Example Usage:**

* "Block my card CARD0001"
* "Freeze card CARD0002"

***

### unblock\_card

Unblock/reactivate a blocked card.

```typescript theme={null}
{
  name: "unblock_card",
  description: "Unblock a previously blocked card",
  parameters: {
    type: "object",
    properties: {
      card_serial: {
        type: "string",
        description: "Card serial number to unblock"
      }
    },
    required: ["card_serial"]
  }
}
```

**Example Usage:**

* "Unblock card CARD0001"
* "Reactivate my card"

***

## KYC Tools

### upload\_kyc\_image

Upload a single KYC document image.

```typescript theme={null}
{
  name: "upload_kyc_image",
  description: "Upload and validate a KYC document image",
  parameters: {
    type: "object",
    properties: {
      side: {
        type: "string",
        enum: ["front", "back"],
        description: "Which side of the ID"
      }
    },
    required: ["side"]
  }
}
```

<Note>
  This tool uses the image from the message context, not a parameter.
</Note>

**Example Usage:**

* \[User sends image] "This is the front of my ID"
* \[User sends image] "Here's my ID back"

***

### upgrade\_kyc

Complete KYC upgrade with both ID sides verified.

```typescript theme={null}
{
  name: "upgrade_kyc",
  description: "Complete KYC upgrade after both sides are uploaded",
  parameters: {
    type: "object",
    properties: {
      confirm: {
        type: "boolean",
        description: "User confirmation to proceed"
      }
    },
    required: ["confirm"]
  }
}
```

**Example Usage:**

* "Complete my KYC verification"
* "Upgrade my account"

***

## Registration Tools

### register\_subscriber

Register a new subscriber account.

```typescript theme={null}
{
  name: "register_subscriber",
  description: "Register a new OLIVE wallet subscriber",
  parameters: {
    type: "object",
    properties: {
      first_name: {
        type: "string",
        description: "First name"
      },
      last_name: {
        type: "string",
        description: "Last name"
      },
      pin: {
        type: "string",
        description: "4-digit PIN"
      }
    },
    required: ["first_name", "last_name", "pin"]
  }
}
```

**Example Usage:**

* "Register me as John Doe with PIN 1234"
* "Create my account"

***

## Tool Context

Every tool handler receives a context object:

```typescript theme={null}
interface ToolContext {
  userId: string;          // Subscriber ID (from phone lookup)
  phoneE164: string;       // Phone in E.164 format
  sessionId: string;       // Conversation session ID
  mediaData?: string;      // Base64 image data (if present)
  mediaMimetype?: string;  // Image MIME type
}
```

## Tool Result Format

All tool handlers return a consistent result format:

```typescript theme={null}
interface ToolResult {
  success: boolean;
  data?: any;              // Structured data for OpenAI
  message?: string;        // Human-readable summary
  error?: string;          // Error message (if failed)
  userMessage?: string;    // Message to show to user
}
```

## Adding Custom Tools

See the [Architecture](/agent-ts/architecture#adding-a-new-tool) page for step-by-step instructions on adding new tools.

## Next Steps

<CardGroup cols={2}>
  <Card title="KYC Validation" icon="shield-check" href="/agent-ts/kyc-validation">
    OCR and fraud detection details
  </Card>

  <Card title="Webhooks" icon="webhook" href="/agent-ts/webhooks">
    WhatsApp integration
  </Card>
</CardGroup>