> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onosso.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> The four tools, what each one answers, and an example.

The server has four tools, by intent. Each one runs the same operation the app runs, as the person
who owns the token, so it answers exactly what that person sees in the app.

A tool that succeeds answers its result twice: as `structuredContent`, the JSON object, and as one
`text` item holding the same JSON. A tool that refuses answers `isError: true` with one text that says
what to do next (see [Errors](/errors)).

Every call is a JSON-RPC `tools/call` request:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "week", "arguments": { "week": "2026-W43" } }
}
```

Your client builds these requests; the examples below show only `params`. `tools/list` returns each
tool's description, written for the model to read, and its input schema.

## `week`

The household's week, day by day: what happens each day, for whom and with whom, the trips and
vacations that cross it, and the weather forecast.

| Argument | Required | What it is |
| - | - | - |
| `week` | no | An ISO week, such as `2026-W43`. Without it, the current week in São Paulo. |

```json theme={null}
{ "name": "week", "arguments": {} }
```

The result names the household, the week (`id`, its `days`, the `previous` and `next` weeks, and
whether it `isCurrent`), the week's `items` and the `bands` that cross it, such as a trip.

## `questions`

What needs you: the household's questions waiting on the token's owner, nearest deadline first. For
example, who takes a child to an activity that nobody is taking them to.

| Argument | Required | What it is |
| - | - | - |
| `week` | no | An ISO week. With it, only the questions dated in that week. |

```json theme={null}
{ "name": "questions", "arguments": { "week": "2026-W43" } }
```

The result is `questions`: each with its `title`, the `options` to answer it with, and its `date`.

## `list`

The household's shopping list: the open items, grouped by place, and the bought ones, most recent
first.

| Argument | Required | What it is |
| - | - | - |
| `place` | no | A place's id. With it, the open items are grouped by that place's sections. |

```json theme={null}
{ "name": "list", "arguments": {} }
```

The result holds the `open` and `bought` items. Call it without `place` first: the places that have
open items come in the answer with their ids. A place with nothing open to buy is not listed there.

## `tell`

Tells the house something new, in Portuguese, the way you would on WhatsApp ("dentista da Luísa na
sexta às 15h", "me lembra de comprar arroz"), or asks it something. The message is recorded in your
conversation with the house, and the answer comes back in `reply`.

| Argument | Required | What it is |
| - | - | - |
| `clientMessageId` | yes | A new UUID for each message. Sending the same one again returns the first answer instead of telling the house twice. |
| `at` | yes | When you said it, as an ISO 8601 instant in UTC. "Today" is that instant's date in São Paulo. |
| `text` | yes | The message, in Portuguese. |
| `context` | no | What the message is about: `{ "occurrenceId": … }` for one occurrence of an activity, or `{ "personId": … }` for one person. Without it, a message to the house itself. |

```json theme={null}
{
  "name": "tell",
  "arguments": {
    "clientMessageId": "3f2b8c1e-7a4d-4e3b-9c1a-5d6e7f8a9b0c",
    "at": "2026-10-21T13:05:00Z",
    "text": "dentista da Luísa na sexta às 15h"
  }
}
```

The result holds your `message`, its `turnId`, and the house's `reply`, as both appear in the
conversation in the app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.