Adding New Tools for Gemini

Relevant source files

The following files were used as context for generating this wiki page:

• GITHUB_INTEGRATION_COMPLETE.md
• REACT_LOOP_README.md
• INSIGHTS_DEPLOYMENT_GUIDE.md
• FULL_CONTEXT_MODE_IMPLEMENTATION_COMPLETE.md
• 12-2-todo.md
• INSIGHTS_TOOL_EXECUTION_ENHANCEMENT.md
• GEMINI.md

The BMSview application leverages Google Gemini as an "agentic" AI that can dynamically request data and perform actions using a predefined set of tools. This capability is managed through a ReAct (Reason and Act) loop, which allows Gemini to iterate through thought, action (tool call), and observation cycles to answer complex queries. Adding new tools extends the AI's capabilities, allowing it to access more data sources or perform new actions, such as creating GitHub issues or analyzing usage patterns.

The core principle is that Gemini is the only entity with access to these tools; end-users cannot execute them directly. When analysis requires data from a tool, Gemini must be instructed to call the tool itself and present the findings.

Sources: REACT_LOOP_README.md, INSIGHTS_TOOL_EXECUTION_ENHANCEMENT.md:12-16

Architecture of Tool Execution

The tool execution process is orchestrated by the ReAct loop, which manages the conversation between the user, Gemini, and the system's tools. The loop is designed to handle both synchronous requests for a fast user experience and asynchronous background jobs for more complex, long-running analyses.

Sources: REACT_LOOP_README.md, GEMINI.md:52-56

ReAct Loop Flow

The ReAct loop follows a structured process to enable tool usage. It has a built-in turn limit (e.g., 5 turns for standard insights, 10-20 for custom queries) and a time budget to ensure it completes in a timely manner.

The following diagram illustrates the ReAct loop's logic for handling tool calls.

This diagram shows how a user request initiates the ReAct loop, which continues to call Gemini and execute tools until a final answer is generated.

Sources: REACT_LOOP_README.md, INITIALIZATION_SEQUENCE_IMPLEMENTATION.md:52-57

Sequence of Interactions

The sequence diagram below details the interactions between the client, the Netlify function, the Gemini API, and the tool executor.

This sequence shows a single iteration of the ReAct loop where Gemini requests a tool, the system executes it, and the result is sent back to Gemini to formulate a final answer.

Sources: REACT_LOOP_README.md, INSIGHTS_DEPLOYMENT_GUIDE.md:25-36

Step 1: Defining a New Tool

New tools are defined in a central location, netlify/functions/utils/gemini-tools.cjs, which is then passed to the Gemini API during the initial request. Each tool definition is a structured object that tells Gemini the tool's name, purpose, and required parameters.

Sources: GITHUB_INTEGRATION_COMPLETE.md:29-31

Tool Definition Schema

A tool definition must follow a specific JSON schema.

Property	Type	Description
name	string	The function name that Gemini will call. Must match the handler in the tool executor.
description	string	A clear, detailed description of what the tool does. This is critical for helping Gemini decide when to use it.
parameters	object (JSON Schema)	An object defining the parameters the function accepts, following the JSON Schema specification.
parameters.type	string	Must be "object".
parameters.properties	object	An object where each key is a parameter name and the value is its schema (type, description).
parameters.required	string[]	An array of parameter names that are mandatory for the tool call.

Sources: GITHUB_INTEGRATION_COMPLETE.md:32-37

Example: getCodebaseFile Tool Definition

The getCodebaseFile tool allows Gemini to fetch the contents of a file from the repository. Its definition provides a clear example of the required structure.

{
  "name": "getCodebaseFile",
  "description": "Fetch the contents of a specific file from the codebase to verify implementations. Use this to get context before suggesting code changes. Path must be from the approved list.",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "The full path to the file from the repository root (e.g., 'services/clientService.ts')."
      }
    },
    "required": ["path"]
  }
}

This definition clearly instructs Gemini on how and when to use the tool to retrieve file content.

Sources: GITHUB_INTEGRATION_COMPLETE.md:34-37

Step 2: Implementing the Tool Handler

Once a tool is defined, its corresponding logic must be implemented in the tool-executor.cjs module. This module contains a primary function, executeToolCall(), which acts as a router, directing tool calls from Gemini to the appropriate handler function.

When adding a new tool, you must add a new case to the switch statement within executeToolCall() that matches the tool's name.

Sources: REACT_LOOP_README.md:46-51

Example: submitAppFeedback Tool

The submitAppFeedback tool allows Gemini to create suggestions for improving the application. This is part of the "Full Context Mode" feature. The handler for this tool would be responsible for calling the ai-feedback.cjs Netlify function to store the suggestion.

Sources: FULL_CONTEXT_MODE_IMPLEMENTATION_COMPLETE.md:104-106, 128-133

Available Tools Inventory

The system has a set of defined tools, some of which are fully implemented while others are stubs that return placeholder data.

Tool Name	Status	Purpose
request_bms_data	✅ Implemented	Request specific BMS metrics with time ranges.
getSystemHistory	✅ Implemented	Get historical battery measurements.
submitAppFeedback	✅ Implemented	Submits AI-generated feedback for application improvements.
searchGitHubIssues	✅ Implemented	Search repository issues by query to prevent duplicates.
getCodebaseFile	✅ Implemented	Fetch file contents to verify implementations.
listDirectory	✅ Implemented	Discover files in approved directories.
getWeatherData	🔄 Stub	Get weather data for correlation analysis.
getSolarEstimate	🔄 Stub	Get solar generation forecasts.
getSystemAnalytics	🔄 Stub	Get performance analytics.
predict_battery_trends	🔄 Stub	Use predictive modeling to forecast battery trends.
analyze_usage_patterns	🔄 Stub	Recognize and analyze usage patterns.
calculate_energy_budget	🔄 Stub	Calculate energy budgets based on different scenarios.

Sources: INSIGHTS_DEPLOYMENT_GUIDE.md:65-76, 12-2-todo.md:58-68, GITHUB_INTEGRATION_COMPLETE.md:32-37, FULL_CONTEXT_MODE_IMPLEMENTATION_COMPLETE.md:104-106

Conclusion

Adding new tools to Gemini is a powerful way to extend the capabilities of the BMSview AI Battery Guru. The process involves two main steps: defining the tool's interface in gemini-tools.cjs so Gemini understands how to use it, and implementing the corresponding business logic in tool-executor.cjs. This structured approach allows for a scalable and maintainable "agentic" AI system that can be enhanced over time to perform increasingly complex tasks and analyses.

Sources: REACT_LOOP_README.md