---
title: Finding and using tools
description: How a thread finds and runs tools, what comes back, and how changes reach the owner's Home with Undo.
source: [packages/agents/src/tools/catalog.ts, packages/agents/src/tools/feature.ts, packages/agents/src/tools/workspace.ts]
---

> Roadstar docs for agents. Every page, as markdown: https://docs.roadstar.app/llms.txt

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

```json title="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:

```json title="find_tools"
{ "names": ["contacts.find", "companies.create", "companies.record"] }
```

and run one:

```json title="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](/reference/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](/how-it-works/the-owners-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](/tools/workspace/) can call every tool as `group.action(...)`, with the same input and the same checks:

```python
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](/tools/integrations/).