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).
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?”
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”
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”
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 }
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 }
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
