Finding and using tools

In a thread, every tool is in a group: contacts, mail, files and the rest. You hold three tools that reach them all, and you always see the list of groups, one line each.

Browse, find, use

browse_tools

{ "groups": ["contacts", "companies"] }

returns each group’s tools and what each does. Then load the ones you need, with their inputs and each group’s how-to:

find_tools

{ "names": ["contacts.find", "companies.create", "companies.record"] }

and run one:

use_tool

{ "name": "contacts.find", "input": { "email": "dana@juniperdental.test" } }

Browse up to 3 groups at a time and load up to 8 tools at a time. Tools stay loaded for the rest of the thread. The how-to find_tools sends with each group is on that group’s page here, word for word, under “How to use it”.

What comes back

use_tool returns the tool’s result as JSON. Each tool’s page shows its result type. A tool that returns nothing returns { "done": true }.

Instead of a result, use_tool can return:

Returned	What happened	Next
{ "error": "<kind>", "message": "…" }	The tool failed	See errors
… "card": "…" } with an error	A card asks the owner to connect or reconnect an app	Say in a line what it lets you do, and carry on with the rest
{ "not_done_yet": "…" }	The check wants the owner’s yes. Nothing ran.	Ask in your reply. See the owner’s yes
{ "refused": "…" }	The check stopped it. Nothing ran.	Tell the owner, and don’t try another way

Your work and Undo

Every tool that changes something leaves a record on the owner’s Home, under Your work: what it did, in a sentence, and Undo where the tool has one. Each tool’s page says which. Some changes show where they happen instead, such as a note on a contact’s log.

An email from mail.send waits two minutes on Home before it goes, with Undo.

Tools from code

Code you run in the workspace can call every tool as group.action(...), with the same input and the same checks:

from roadstar import contacts
dana = contacts.find(email="dana@juniperdental.test")

A call the check holds back returns not_done_yet or refused, and the code carries on. Ask the owner in your reply once the run is done.

Connected apps

Each app the owner connects adds a group named after it, with the app’s own tools. Browse it like any group. See connected apps.