Skip to main content

​
Agent-TS Tools Reference

The Agent uses OpenAI function calling with 20 tools organized into 5 categories.

​
Tool Categories

CategoryToolsPurpose
Registration2User registration and status
KYC2Document upload and verification
Wallet6Balance, transfers, statements
Cards6Card management operations
Agent4Agent/merchant operations

​
Registration Tools

​
check_user_registration

Check if a phone number is registered as subscriber or agent. 
{
  name: "check_user_registration",
  parameters: {
    phoneE164: string  // E.164 format phone number
  }
}
Returns: Registration status, user type, KYC level

​
register_subscriber

Register a new subscriber account. 
{
  name: "register_subscriber",
  parameters: {
    phoneE164: string,   // Phone number
    firstName: string,   // First name
    lastName: string,    // Last name
    pin: string          // 4-digit PIN
  }
}

​
KYC Tools

​
upload_kyc_image

Upload and validate a KYC document image. 
{
  name: "upload_kyc_image",
  parameters: {
    phoneE164: string,  // User phone
    side: "front" | "back"  // ID side
  }
}
Image data is passed via message context, not as a parameter.

​
upgrade_kyc

Complete KYC upgrade after both ID sides are validated. 
{
  name: "upgrade_kyc",
  parameters: {
    phoneE164: string,
    confirm: boolean  // User confirmation
  }
}

​
Wallet Tools

​
check_balance

Check wallet balance. Requires PIN. 
{
  name: "check_balance",
  parameters: {
    phoneE164: string,  // User phone
    pin: string         // 4-digit PIN (REQUIRED)
  }
}
Returns: { balance: number, currency: string }

​
get_transactions

Get transaction history. Requires PIN. 
{
  name: "get_transactions",
  parameters: {
    phoneE164: string,
    pin: string,
    limit?: number  // Default: 10
  }
}

​
initiate_transfer

P2P transfer to another user’s card. Requires PIN. 
{
  name: "initiate_transfer",
  parameters: {
    senderPhoneE164: string,     // Sender phone
    recipientCardSerial: string, // Recipient card (e.g., "CARD0005")
    amount: number,              // Amount in SLE
    pin: string                  // Sender's PIN
  }
}

​
get_account_limits

Get transaction limits based on KYC level. 
{
  name: "get_account_limits",
  parameters: {
    phoneE164: string
  }
}
Returns: Single transaction, daily, monthly limits

​
change_subscriber_pin

Change subscriber’s PIN. Requires old PIN. 
{
  name: "change_subscriber_pin",
  parameters: {
    phoneE164: string,
    oldPin: string,  // Current PIN
    newPin: string   // New PIN
  }
}

​
request_account_statement

Generate and send PDF account statement. 
{
  name: "request_account_statement",
  parameters: {
    phoneE164: string,
    startDate: string,  // YYYY-MM-DD
    endDate: string     // YYYY-MM-DD
  }
}

​
Card Tools

​
get_user_cards

List all cards linked to user. 
{
  name: "get_user_cards",
  parameters: {
    phoneE164: string
  }
}
Link a new card to account. 
{
  name: "link_card",
  parameters: {
    phoneE164: string,
    cardSerial: string,
    pin: string
  }
}

​
create_child_card

Create a child card with spending limits. 
{
  name: "create_child_card",
  parameters: {
    phoneE164: string,
    parentCardSerial: string,
    childCardSerial: string,
    childName: string,
    dailyLimit: number,
    parentPin: string,
    childPin: string
  }
}

​
change_child_card_pin

Change PIN for a child card. 
{
  name: "change_child_card_pin",
  parameters: {
    phoneE164: string,
    cardSerial: string,
    parentPin: string,
    newChildPin: string
  }
}

​
block_card

Block a card. 
{
  name: "block_card",
  parameters: {
    phoneE164: string,
    cardSerial: string,
    pin: string,
    reason?: string
  }
}

​
unblock_card

Unblock a blocked card. 
{
  name: "unblock_card",
  parameters: {
    phoneE164: string,
    cardSerial: string,
    pin: string
  }
}

​
Agent Tools

​
check_agent_balance

Check agent float balance. Requires PIN. 
{
  name: "check_agent_balance",
  parameters: {
    phoneE164: string,
    pin: string
  }
}

​
agent_cash_in

Perform cash-in for a subscriber. Requires PIN. 
{
  name: "agent_cash_in",
  parameters: {
    agentPhoneE164: string,
    subscriberPhoneE164: string,
    amount: number,
    pin: string
  }
}

​
transfer_to_sub_agent

Transfer float to sub-agent. Requires PIN. 
{
  name: "transfer_to_sub_agent",
  parameters: {
    fromAgentPhone: string,
    toAgentPhone: string,
    amount: number,
    pin: string
  }
}

​
change_agent_pin

Change agent’s PIN. Requires old PIN. 
{
  name: "change_agent_pin",
  parameters: {
    phoneE164: string,
    oldPin: string,
    newPin: string
  }
}

​
Security Notes

PIN Requirements: Most financial operations require the user’s 4-digit PIN. The agent is instructed to always ask for PIN before calling these functions.
Phone Validation: The phoneE164 parameter must match the texting user’s phone number. The agent will not accept requests to operate on different phone numbers.

​
Next Steps

API Endpoints

REST endpoint documentation

KYC Validation

Document validation details