Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tool Definition

In BotServer, a tool is simply a .bas file. That’s it!

How It Works

  1. Create a .bas file in your .gbdialog/ folder
  2. The LLM automatically discovers it and can call it when needed
  3. No manual registration required - it just works!

Tool Discovery and Execution Flow

LLM Tool Discovery and Execution Pipeline "Send an email to John about the meeting" LLM Analyzes "Need email tool" Tool Discovery Scan .gbdialog/ • send-email.bas ✓ • create-task.bas • get-weather.bas Parameter Collection to → "John" subject → "Meeting" body → (generated) Execute Tool send-email.bas Return Result "Email sent!"

Simple Example

Create get-weather.bas:

' This tool gets weather information
' The LLM will call this when users ask about weather

TALK "Let me check the weather for you..."
weather = GET "/api/weather/San Francisco"
TALK "The weather is: " + weather

That’s a tool! The LLM now knows it can call this when users ask about weather.

Tool with Parameters

Create send-email.bas:

' Send an email to someone
PARAM to AS STRING
PARAM subject AS STRING
PARAM body AS STRING

GET "/email/send" WITH to, subject, body
TALK "Email sent to " + to

The PARAM declarations tell the LLM what parameters this tool accepts.

Making Tools Available

Method 1: Automatic Discovery (Default)

All .bas files in your .gbdialog/ folder are automatically available.

mybot.gbai/
  mybot.gbdialog/
    start.bas           ← Entry point
    get-weather.bas     ← Tool (auto-discovered)
    send-email.bas      ← Tool (auto-discovered)
    create-task.bas     ← Tool (auto-discovered)

Method 2: Manual Registration

In your start.bas, explicitly add tools:

' Register tools for this conversation
USE TOOL "get-weather"
USE TOOL "send-email"
USE TOOL "create-task"

TALK "Hello! I can help with weather, email, and tasks."

Method 3: LLM-Driven Tool Selection

Let the LLM decide which tools to use naturally:

' In start.bas
' Load all available tools - LLM decides when to use them
USE TOOL "weather"
USE TOOL "email"
USE TOOL "enrollment"

TALK "I can help with various tasks. What do you need?"
' The LLM will automatically call the right tool based on user intent

Tool Format Conversion

BotServer automatically converts your .bas tools to:

  • MCP (Model Context Protocol) format
  • Groq/OpenAI-compatible function calling format
  • Other LLM provider formats

You never write these formats manually - just write .bas files!

Conversion Pipeline

Tool Format Conversion Pipeline send-email.bas BASIC Parser • Extract PARAM • Parse DESCRIPTION • Analyze code MCP Format OpenAI Function Claude Tool Local Model LLM Provider Receives Native Format

Complete Example

Here’s a real tool from the codebase - enrollment.bas:

PARAM name AS string          LIKE "Abreu Silva"                DESCRIPTION "Required full name of the individual."
PARAM birthday AS date        LIKE "23/09/2001"                 DESCRIPTION "Required birth date of the individual in DD/MM/YYYY format."
PARAM email AS string         LIKE "abreu.silva@example.com"    DESCRIPTION "Required email address for contact purposes."
PARAM personalid AS integer   LIKE "12345678900"                DESCRIPTION "Required Personal ID number of the individual (only numbers)."
PARAM address AS string       LIKE "Rua das Flores, 123 - SP"   DESCRIPTION "Required full address of the individual."

DESCRIPTION  "This is the enrollment process, called when the user wants to enroll. Once all information is collected, confirm the details and inform them that their enrollment request has been successfully submitted."

' The actual tool logic is simple
SAVE "enrollments.csv", id, name, birthday, email, personalid, address
TALK "Successfully enrolled " + name + "!"

' That's it! The LLM handles:
' - Natural conversation to collect parameters
' - Validation and error handling  
' - Confirming details with the user
' - All the complex interaction flow

That’s It!

To create a tool:

  1. ✅ Create a .bas file
  2. ✅ Add PARAM declarations if you need parameters
  3. ✅ Write your logic using TALK, HEAR, CALL, etc.
  4. ✅ Done!

The LLM will automatically:

  • Discover your tool
  • Understand what it does (from comments and code)
  • Know when to call it
  • Pass the right parameters

No JSON schemas, no manual registration, no complex configuration. Just write BASIC!

Best Practices

1. Add Comments

The LLM reads your comments to understand the tool:

' This tool books a meeting room
' It checks availability and sends calendar invites
PARAM room_name AS STRING
PARAM date AS STRING
PARAM attendees AS ARRAY

2. Validate Parameters

Always validate input:

IF room_name IS NULL THEN
    TALK "Please specify which room you want to book."
    RETURN
ENDIF

3. Provide Feedback

Let users know what’s happening:

TALK "Checking room availability..."
available = GET "/calendar/check" WITH room_name, date

IF available THEN
    TALK "Great! Booking the room now..."
    GET "/calendar/book" WITH room_name, date, attendees
    TALK "Meeting room booked successfully!"
ELSE
    TALK "Sorry, that room is not available on " + date
ENDIF

Tool Discovery

The LLM discovers tools by:

  1. Reading .bas files in your .gbdialog/ folder
  2. Extracting comments to understand purpose
  3. Parsing PARAM declarations to understand parameters
  4. Building a function signature automatically

Example tool discovery from send-email.bas:

Function: send-email
Description: Send an email to someone
Parameters:
  - to: STRING (required)
  - subject: STRING (required)  
  - body: STRING (required)

This is generated automatically from your .bas file!

Removing Tools

Dynamic Tool Management

' Remove a specific tool
REMOVE TOOL "send-email"

' Clear all tools
CLEAR TOOLS

' List active tools
tools = LIST TOOLS
TALK "Available tools: " + tools

Next Steps