# 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`: ```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`: ```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: ```bas ' 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: ```bas ' 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`: ```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: ```bas ' 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: ```bas 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: ```bas 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 ```bas ' 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 - [PARAM Declaration](./param-declaration.md) - Parameter types and validation - [GET Keyword Integration](./get-integration.md) - Using GET to call tools - [External APIs](./external-apis.md) - Calling external services