Skip to Content
Add a tool

Add a tool

Tools are registered on the device’s MCP server and offered to Gemini automatically as function declarations; you do not touch the protocol code.

Do you need C++ at all? A fixed script for the model is an app (data only). Calling your own service is a webhook declared in the web settings, reached through extension.call.

1. Register it

In assistant::RegisterTools() (firmware/src/assistant/assistant_tools.cc):

mcp.AddTool("vn.fuel_price", "Xem giá xăng dầu bán lẻ hôm nay tại Việt Nam (RON 95, E5, dầu DO). Dùng khi người " "dùng hỏi giá xăng.", PropertyList({Property("kind", kPropertyTypeString, std::string(""))}), [](const PropertyList& p) -> ToolResult { auto body = HttpGet("https://example.vn/fuel.json"); if (!body) return std::unexpected(body.error()); // ... parse with cJSON, build a short spoken answer ... return std::string("Xăng RON 95 hôm nay 21.000 đồng một lít."); });
PieceNotes
NameEnglish group.action, lowercase ASCII (vn.weather, timer.set). Dots become _ for Gemini, so names must stay unique after that and within 64 characters.
DescriptionOne or two sentences saying when to use it, with phrases users actually say. It is all the model sees.
Property(name, kPropertyTypeString)Required string
Property(name, kPropertyTypeString, std::string(""))Optional string with a default
Property(name, kPropertyTypeInteger, min, max)Required integer in a range
Property(name, kPropertyTypeInteger, default, min, max)Optional integer
Property(name, kPropertyTypeBoolean, false)Optional boolean
ReturnReturnValue (string, bool, int or cJSON*) or ToolResult; return std::unexpected("message") on errors

Helpers: HttpGet(url) (TLS session reuse, one retry), UrlEncode(), Between(), CleanXmlText(), Now(&tm) (false until the clock is synced), ListItems()/StoreItems() for small persistent lists, LoadConfig() for the user’s city.

Guidelines

  • Return short, speakable text: it is read aloud.
  • Keep network calls under ~10 s; schedule anything later through the scheduler.
  • No secrets in code. Use public endpoints or keys stored in NVS.
  • Tools only the web UI should trigger: mcp.AddUserOnlyTool(...).
  • Keep descriptions concise; the tool list is sent with every session.

2. Test

python3 firmware/scripts/validate_data.py # also checks tool names mentioned in prompts firmware/build.sh && firmware/ota.sh bap-xxxx.local curl -s -X POST http://bap-xxxx.local/api/tool -H 'X-Bap: 1' -H 'Content-Type: application/json' \ -d '{"name":"vn.fuel_price","arguments":{"kind":"RON 95"}}'

Then ask naturally and look for Tool call: vn_fuel_price in the serial log.