---
title: browse, find, use
description: browse_tools, find_tools and use_tool, how a thread reaches every tool group.
tools: [browse_tools, find_tools, use_tool]
source: [packages/agents/src/tools/catalog.ts, packages/agents/src/tools/feature.ts]
generated: true
---

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

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](/reference/errors/).
- `{ "not_done_yet": "…" }` or `{ "refused": "…" }` when the check held it back, and nothing ran. See [the owner's yes](/how-it-works/the-owners-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](#browse_tools) | — | — | Yes | Yes |
| [find_tools](#find_tools) | — | — | Yes | Yes |
| [use_tool](#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 |  |  |