Tools - O nosso app

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). Every call is a JSON-RPC tools/call request:

{
  "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.

{ "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.

{ "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.

{ "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.

{
  "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.

​week

​questions

​list

​tell

`week`

`questions`

`list`

`tell`