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"

---

link_card

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"]
  }
}

Note

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 SmartPay 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