browse, find, use

In a thread, every tool is in a group, and three tools reach them. The groups, one line each, are in browse_tools’s own description, so you always see them.

1. browse_tools with up to 3 group names returns each group’s tools and what each does: { "mail": { "mail.search": "…", "mail.send": "…" } }. More than 3 come back as not_shown; a wrong name as no_such_group, with the groups there are.
2. find_tools with up to 8 tool names returns found, each with its name, what it does and its input, and howTo: each group’s how-to, once. A wrong name comes back in no_such_tool, with that group’s tools.
3. use_tool runs one tool by name with its input, and returns the tool’s result as JSON.

use_tool can also return:

• { "error": "<kind>", "message": "…", "card": "…" } when the tool failed. See errors.
• { "not_done_yet": "…" } or { "refused": "…" } when the check held it back, and nothing ran. See the owner’s yes.
• { "done": true } when the tool returns nothing.

Load tools once per thread; they stay loaded.

Where each is offered

Tool	Roadstar’s chat	An agent’s chat	A thread	A Mac or outside app
browse_tools	—	—	Yes	Yes
find_tools	—	—	Yes	Yes
use_tool	—	—	Yes	Yes

browse_tools

What the agent reads, word for word:

Every tool you have is in one of these groups. Browse up to 3 to see their tools, then load the ones you need with find_tools.

• contacts: the people the business deals with (11)
• companies: the businesses the owner deals with: clients, suppliers, their conversations (11)
• web: search the web and read pages (2)
• pages: research pages (6)
• comments: comments on pages (2)
• projects: projects that hold docs, pages and tables (4)
• tables: research tables (6)
• filings: public companies’ filings (2)
• newsfeed: today’s news (1)
• docs: the business’s docs: proposals, briefs, checklists (5)
• files: the owner’s Drive: files, Google Docs and Sheets (15)
• mail: the owner’s Gmail (4)
• calendar: the owner’s calendar: meetings and time held (2)
• books: invoices and what customers owe, from the owner’s accounting app (2)
• workspace: your own folder: files, spreadsheets and code (5)
• templates: agents, teams, departments and skills shared in the workspace (4)
• help: these docs: how Roadstar works, and every tool (2)
• search: Search (2)
• integrations: the apps the owner has connected or could connect (2)

Input	Type	Required	What it is	Limits
groups	list of text	yes	Group names from the list

find_tools

What the agent reads, word for word:

Load tools by name, as browse_tools lists them, such as “mail.send”: each with its input and how to use its group well. Up to 8 at once.

Input	Type	Required	What it is	Limits
names	list of text	yes	Tool names, such as “contacts.update”

use_tool

What the agent reads, word for word:

Run one tool by its name, with its input. One that sends outside the business, deletes, or changes what’s there is checked first.

Input	Type	Required	What it is	Limits
name	text	yes	The tool’s name, such as “mail.send”
input	object	no