Skip to main content

​
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. 
{
  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. 
{
  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. 
{
  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. 
{
  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. 
{
  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”
Activate and link a new NFC card. 
{
  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. 
{
  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. 
{
  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. 
{
  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"]
  }
}
This tool uses the image from the message context, not a parameter.
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. 
{
  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. 
{
  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: 
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: 
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 page for step-by-step instructions on adding new tools.

​
Next Steps

KYC Validation

OCR and fraud detection details

Webhooks

WhatsApp integration