---
title: Search
description: "One search over the copy of the owner's mail, files and meetings, and the workspace's own docs, tables and contacts. 2 tools, where search is on."
group: search
tools: [search.search, search.read]
source: [packages/agents/src/tools/search.ts, packages/integrations/src/sync]
generated: true
---

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

Where the workspace's owners turn search on, Roadstar keeps a copy of the accounts they choose, and agents get this group. Search is literal and fast, costs the owner's accounts nothing, and gives exact totals and counts, such as who the owner writes to most.

Its how-to lists, for the agent reading it, which accounts are in search and since when. The one below is for a workspace with none, so it names only the workspace's own content.

Search several times with different words, then `read` what you'll rely on. Mail and files keep their own live search for what the copy doesn't hold yet.

## How to use it

What `find_tools` sends with these tools, word for word:

> Search and read the owner's mail, files and meetings as copied for Roadstar, and the workspace's own content. In search: the workspace's docs, tables, contacts and projects. Search is literal and fast and costs the owner's accounts nothing: search several times, with words in query and people, dates, folders, labels, sent or received as fields; identifiers as written. Totals and counts are exact over every match: counts.people shows who the owner writes with most. Results are one per thread; thread: its id lists every message. Read before you answer.

## Tools

| Tool | What it does | Owner's yes |
| --- | --- | --- |
| [search.search](#search) | One list with the exact total, how names and dates were understood, counts by type, source, year, direction and sender, each source's state, and next for the following page. Results with related: true matched by meaning, not by the words | No |
| [search.read](#read) | A result in full, 30,000 characters at a time: a message with sender, recipients, date and its attachments' ids; a whole thread by an id gmail:{account}:t:{thread}; an attachment's or file's text; a meeting. With next, read again from that offset | No |

## search

`search.search` · One list with the exact total, how names and dates were understood, counts by type, source, year, direction and sender, each source's state, and next for the following page. Results with related: true matched by meaning, not by the words.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `query` | text | no | Words; "PO 4471", an invoice number or an email address match exactly | up to 300 characters |
| `from` | list of text | no | Sender, author or organizer: names, addresses or a company | up to 10 items, each 1–200 characters |
| `to` | list of text | no | To, cc or guests | up to 10 items, each 1–200 characters |
| `with` | list of text | no | Anyone on it, or everyone at a company | up to 10 items, each 1–200 characters |
| `after` | text | no | "2026-09-01" or "last week" | up to 40 characters |
| `before` | text | no |  | up to 40 characters |
| `type` | list of one of `email`, `doc`, `sheet`, `slides`, `pdf`, `image`, `file`, `meeting`, `page`, `table`, `contact`, `project` | no |  | up to 8 items |
| `in` | list of text | no | A folder ("Clients › Juniper Dental") or a mail label ("label:Clients", "label:STARRED") | up to 5 items, each 1–200 characters |
| `has` | list of one of `attachment`, `star` | no |  | up to 2 items |
| `dir` | one of `sent`, `received` | no | Mail the owner sent, or mail they received |  |
| `bulk` | true or false | no | false: mail from people only; true: newsletters and automated mail only |  |
| `waiting` | one of `me`, `them` | no | Threads where a person wrote last and the owner hasn't answered (me), or the reverse |  |
| `thread` | text | no | Every message of one thread, by its thread id | up to 200 characters |
| `sort` | one of `relevance`, `newest`, `oldest` | no |  |  |
| `limit` | whole number | no |  | 1–50, default 10 |
| `cursor` | text | no |  | up to 400 characters |

Returns:

```ts
{
  hint?: string;
  results: {
    addedBy?: string;
    related?: boolean;
    text?: string;
    moreInThread?: number;
    thread?: string;
    money?: string[];
    attachments?: string;
    where: string;
    match: string;
    dir?: string;
    to?: string;
    from?: string;
    id: string;
    type: string;
    title: string;
    date: string;
  }[];
  counts: {
    type: Record<string, number>;
    source: Record<string, number>;
    year: Record<string, number>;
    dir: Record<string, number>;
    people: Record<string, number>;
  };
  sources: Record<string, string>;
  next: string | null;
  understood?: Record<string, string>;
  words?: string;
  related?: number;
  total: string | number;
}
```

## read

`search.read` · A result in full, 30,000 characters at a time: a message with sender, recipients, date and its attachments' ids; a whole thread by an id gmail:{account}:t:{thread}; an attachment's or file's text; a meeting. With next, read again from that offset.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `id` | text | yes | 3–500 characters |
| `offset` | whole number | no | 0 or more |

Returns:

```ts
ItemRead
```

## Types

Named types in the results above.

```ts
type ItemRead = {
  title: string;
  url: string;
  text: string;
  source: string;
  nextOffset?: number;
  attachments?: {
    id: string;
    name: string;
    quality: string;
  }[];
}
```