# Ferramentas · Reservas e Agendamento

> Ferramentas MCP das Reservas (salas, mesas e estações) e do Agendamento (horários de pessoas): buscar o que está livre, reservar com custo em créditos, remarcar, cancelar, ausência, convite de calendário, salas, bloqueios, faixas de preço e aprovação de agendas. Papel mínimo e receitas.

O módulo [Reservas](/espacos/reservas) e o [Agendamento](/espacos/agendamento) pelo assistente: buscar salas e horários livres (com o custo em [créditos](/monetizacao/creditos) e o seu saldo), reservar, remarcar, cancelar, marcar ausência, baixar o convite de calendário, cadastrar salas e mesas, bloquear horários, definir preços e aprovar agendas de membros. Os dois módulos usam as mesmas ferramentas de reserva; as de **Agendamento** são as cinco últimas.

Cada ferramenta traz um selo: <span class="tool-kind tool-kind-read">Só consulta</span> não muda nada, <span class="tool-kind tool-kind-write">Altera</span> cria ou muda algo na hora, e <span class="tool-kind tool-kind-confirm">Pede confirmação</span> só age depois do seu sim a um resumo. Ver [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao).

## Em resumo

| Ferramenta | O que faz | Papel mínimo | Tipo |
|---|---|---|---|
| [`search_booking_rooms`](#search-booking-rooms) | Acha o que atende ao pedido, com custo e saldo | Qualquer que veja o espaço | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`check_availability`](#check-availability) | Os horários livres e ocupados de um dia | Qualquer que veja o espaço | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`list_booking_resources`](#list-booking-resources) | As salas, mesas, estações e agendas | Qualquer que veja o espaço | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`list_booking_amenities`](#list-booking-amenities) | O catálogo de comodidades | Qualquer | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`get_booking_resource`](#get-booking-resource) | Uma sala com as regras já resolvidas | Qualquer que veja o espaço | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`create_booking`](#create-booking) | Reserva para você e debita os seus créditos | Qualquer | <span class="tool-kind tool-kind-write">Altera</span> |
| [`create_booking_for_member`](#create-booking-for-member) | Reserva em nome de um membro, debitando os créditos dele | Moderador (ou financeiro) | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`list_my_bookings`](#list-my-bookings) | As suas reservas (ou as que marcaram com você) | Qualquer | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`list_bookings`](#list-bookings) | Todas as reservas da comunidade | Moderador (ou financeiro) | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`get_booking`](#get-booking) | Uma reserva | Dono, anfitrião e equipe | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`cancel_booking`](#cancel-booking) | Cancela e estorna conforme a regra | Dono, anfitrião e equipe | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`reschedule_booking`](#reschedule-booking) | Muda o horário e acerta os créditos | Dono, anfitrião e equipe | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`mark_booking_no_show`](#mark-booking-no-show) | Marca a ausência | Equipe e anfitrião | <span class="tool-kind tool-kind-write">Altera</span> |
| [`get_booking_ics`](#get-booking-ics) | O convite de calendário (`.ics`) | Dono, anfitrião e equipe | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`create_booking_resource`](#create-booking-resource) | Cria uma sala, mesa ou agenda | Administrador (salas) | <span class="tool-kind tool-kind-write">Altera</span> |
| [`update_booking_resource`](#update-booking-resource) | Edita, troca ou remove a foto | Administrador (salas) | <span class="tool-kind tool-kind-write">Altera</span> |
| [`delete_booking_resource`](#delete-booking-resource) | Exclui (cancelando as reservas futuras) | Administrador | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`list_availability_exceptions`](#list-availability-exceptions) | Bloqueios e horários extras | Qualquer que veja o espaço | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`create_availability_exception`](#create-availability-exception) | Bloqueia ou abre um período | Equipe (salas) | <span class="tool-kind tool-kind-write">Altera</span> |
| [`cancel_bookings_for_closure`](#cancel-bookings-for-closure) | Bloqueia cancelando as reservas do período | Equipe (salas) | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`delete_availability_exception`](#delete-availability-exception) | Remove um bloqueio ou horário extra | Equipe (salas) | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`list_price_rules`](#list-price-rules) | As faixas de preço de uma sala | Administrador | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`create_price_rule`](#create-price-rule) | Cria uma faixa de preço | Administrador | <span class="tool-kind tool-kind-write">Altera</span> |
| [`update_price_rule`](#update-price-rule) | Edita uma faixa | Administrador | <span class="tool-kind tool-kind-write">Altera</span> |
| [`delete_price_rule`](#delete-price-rule) | Remove uma faixa | Administrador | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`get_scheduling_config`](#get-scheduling-config) | As regras do Agendamento e as suas agendas | Qualquer que veja o espaço | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`search_scheduling_hosts`](#search-scheduling-hosts) | Pessoas com horário livre | Qualquer que veja o espaço | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`get_scheduling_host`](#get-scheduling-host) | A página de uma pessoa, com a grade | Qualquer que veja o espaço | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`list_pending_scheduling_offers`](#list-pending-scheduling-offers) | Agendas esperando aprovação | Administrador | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`set_booking_resource_listing`](#set-booking-resource-listing) | Aprova ou retira uma agenda | Administrador | <span class="tool-kind tool-kind-write">Altera</span> |

"Equipe" é o proprietário, o administrador, o moderador e o financeiro. Os papéis são os das rotas: o assistente nunca faz mais do que a pessoa conectada faria na tela.

Os espaços se criam com [`create_space`](/mcp/ferramentas-comunidade#create-space) e `module: "bookings"` ou `"scheduling"`; [`update_space`](/mcp/ferramentas-comunidade#update-space) muda só o que você mandar. O argumento `bookings` leva os padrões de toda sala (`slot_minutes`, `min_duration_minutes`, `max_duration_minutes`, `min_notice_minutes`, `max_advance_days`, `show_booker_name` e `opening_hours`, com as chaves `mon` a `sun` e períodos `HH:MM`); o `scheduling` leva os mesmos e mais `offerers` (`ADMINS`, `TEAM` ou `MEMBERS`), `allow_paid_slots` e `require_listing_approval`.

**Horários.** Os horários que você manda são sempre do **relógio da comunidade** (`"2026-11-03T14:00"`, sem sufixo). **Custos.** Reservar, remarcar e cancelar **mexem nos créditos**: o assistente diz o custo e o saldo antes de reservar. Sem créditos suficientes, a resposta traz `required`, `balance` e `shortfall`; com o horário ocupado, traz os próximos horários livres.

## Buscar e consultar

### `search_booking_rooms`

<span class="tool-kind tool-kind-read">Só consulta</span>

**O que atende ao pedido.** Dê um início exato (`starts_at`) ou uma janela do dia (`date` com `from` e `to`), mais duração, capacidade e comodidades. Devolve só os recursos que atendem, com os horários de início livres, o **custo em créditos**, `canAfford` e o seu saldo, ordenados pelo mais cedo e depois pela menor capacidade; quando nada serve, `next_slots` lista os próximos horários para o mesmo pedido.

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Sim | O espaço Reservas ou Agendamento |
| `starts_at` | data e hora | Não | Início exato, hora local |
| `date`, `from`, `to` | dia `AAAA-MM-DD`, `HH:MM` | Não | A janela de uma busca |
| `duration_minutes` | número, 5 ou mais | Não | Duração |
| `capacity` | número | Não | Quantas pessoas devem caber |
| `amenities` | lista de chaves | Não | Todas são exigidas (de `list_booking_amenities`) |
| `kind` | `ROOM`, `DESK`, `STATION`, `OTHER` ou `PERSON` | Não | O tipo |
| `host_profile_id` | id | Não | Só as agendas desta pessoa |

**Peça assim:** *"Preciso de uma sala para 6 pessoas amanhã das 14h às 16h, com projetor."*

### `check_availability`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Livre e ocupado.** Os horários de um dia (ou de até 7), calculados do horário semanal, dos bloqueios e das reservas, cada livre com `creditCost` e `canAfford`. Nunca diz quem reservou, a menos que o espaço mostre o nome.

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Sim | |
| `date` | `AAAA-MM-DD` | Não | O dia (padrão: hoje) |
| `days` | 1 a 7 | Não | Quantos dias |
| `resource_id`, `host_profile_id` | id | Não | Uma sala só, ou uma pessoa só |
| `duration_minutes` | número | Não | Padrão: a menor reserva |

### `list_booking_resources`

<span class="tool-kind tool-kind-read">Só consulta</span>

**As salas.** Salas, mesas, estações e agendas do espaço. O membro vê só as listadas, ativas e abertas para reserva; a equipe vê todas. Parâmetros: `space` (obrigatório), `kind`, `host_profile_id`, `page`, `limit`.

### `list_booking_amenities`

<span class="tool-kind tool-kind-read">Só consulta</span>

**O catálogo de comodidades** que a comunidade aceita (projetor, TV, quadro branco, Wi-Fi…). Uma chave fora do catálogo é recusada. Sem parâmetros.

### `get_booking_resource`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Uma sala** com as regras efetivas já combinadas com os padrões do espaço (horário, intervalo, limites de duração, antecedência, janela de cancelamento). Parâmetro: `resource_id`.

## Reservar

### `create_booking`

<span class="tool-kind tool-kind-write">Altera</span>

**Reservar para você.** Reserva na hora (já **confirmada**) e **debita os seus créditos** no mesmo passo. Antes, o assistente diz o custo e o saldo. Para reservar em nome de outro membro, use [`create_booking_for_member`](#create-booking-for-member). A **cortesia** (`waive_credits` com `waive_reason`) é só do proprietário e do administrador. O e-mail de confirmação com o convite de calendário entra na fila. Devolve `creditCost` e `balanceAfter`.

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `resource_id` | id | Sim | De `list_booking_resources` ou da busca |
| `starts_at` | data e hora | Sim | Hora local, ex. `2026-11-03T14:00` |
| `ends_at` ou `duration_minutes` | data e hora ou número | Um dos dois | Padrão: a menor reserva |
| `attendee_count` | número | Não | Quantas pessoas |
| `title`, `notes` | texto | Não | Para quê e observações |
| `waive_credits`, `waive_reason` | verdadeiro ou falso, texto | Não | Cortesia, só proprietário e administrador |

**Peça assim:** *"Reserve a Sala 2 amanhã das 14h às 16h para 6 pessoas."*

### `create_booking_for_member`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Reservar em nome de um membro.** Debita os créditos **dele** (ou sai grátis como cortesia, só proprietário e administrador, com `waive_reason`) e ele recebe o e-mail com o convite. Antes de agir, mostra um resumo com o membro e o **saldo dele** e só repete a chamada depois do seu sim. Mesmos parâmetros e mesmas respostas de `create_booking`, mais `profile_id`. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `profile_id` | id | Sim | O membro (`list_members`) |

**Peça assim:** *"Reserve a Sala 1 na sexta, às 10h, em nome da Maria."*

### `list_my_bookings`

<span class="tool-kind tool-kind-read">Só consulta</span>

**As suas reservas**, ou, com `as_host`, as que as pessoas fizeram na agenda que você oferece. Filtros: `space`, `resource_id`, `status` (lista, ex. `CONFIRMED,NO_SHOW`), `from`, `to`, `order`, `page`, `limit`. Cada uma traz `canCancel`.

### `list_bookings`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Todas as reservas da comunidade**, com os mesmos filtros. *Papel mínimo: moderador (ou financeiro).*

### `get_booking`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Uma reserva**: sala, pessoa, horários, situação, custo em créditos, se foi cortesia ou cancelamento tardio e o que quem pergunta pode fazer. Só o dono, o anfitrião e a equipe; outra pessoa recebe `404`. Parâmetro: `booking_id`.

## Mudar uma reserva

### `cancel_booking`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Cancelar.** O dono que cancela **depois da janela** (24 h por padrão) tem o cancelamento marcado como **tardio** e pode perder os créditos; dentro da janela, ou quando a equipe ou o anfitrião cancela, o estorno é por inteiro. A pessoa recebe o e-mail e o evento é cancelado na agenda dela. Uma reserva que já começou não se cancela (use a ausência). Mostra um resumo e só age depois do seu sim.

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `booking_id` | id | Sim | |
| `reason` | texto | Não | Vai no e-mail |

### `reschedule_booking`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Remarcar.** Muda o horário na mesma sala (o que você não mandar fica, e a duração se mantém). **Mexe nos créditos**: um horário mais caro debita a diferença (sem saldo, a resposta traz `shortfall`), um mais barato estorna, uma cortesia não toca no livro. O convite é atualizado e a pessoa recebe um e-mail. Mostra o resumo e devolve `charged`, `refunded` e `balanceAfter`.

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `booking_id` | id | Sim | |
| `starts_at`, `ends_at`, `duration_minutes` | data e hora, número | Não | O novo horário |
| `attendee_count` | número | Não | |

### `mark_booking_no_show`

<span class="tool-kind tool-kind-write">Altera</span>

**Marcar a ausência.** Só para reserva confirmada que já começou. A comunidade decide se os créditos se perdem; a resposta diz quantos foram devolvidos. *Equipe e anfitrião.* Parâmetro: `booking_id`.

### `get_booking_ics`

<span class="tool-kind tool-kind-read">Só consulta</span>

**O convite de calendário**, o mesmo arquivo do e-mail de confirmação, devolvido como texto em `ics` com o nome do arquivo (uma reserva cancelada devolve o cancelamento). Parâmetro: `booking_id`.

## Salas, bloqueios e preços

### `create_booking_resource`

<span class="tool-kind tool-kind-write">Altera</span>

**Criar uma sala, mesa ou agenda.** `kind` é `ROOM`, `DESK`, `STATION` ou `OTHER` (proprietário e administrador); no Agendamento, `PERSON`: quem pode criar a agenda de uma pessoa é decidido pelo `offerers` do espaço (um membro cria só a sua). O tipo não muda depois. Sem faixa de preço, é grátis.

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Sim | |
| `kind` | tipo | Sim | |
| `name` | texto | Sim | Como os membros veem |
| `description`, `capacity`, `units`, `amenities` | | Não | `units`: reservas simultâneas (1 = exclusiva) |
| `bookable`, `active`, `listed` | verdadeiro ou falso | Não | `listed` só proprietário e administrador |
| `meeting_url` | link | Não | Link de videochamada |
| `opening_hours` | horário semanal | Não | Chaves `mon` a `sun`, períodos `HH:MM` |
| `slot_minutes`, `min_duration_minutes`, `max_duration_minutes`, `buffer_minutes`, `min_notice_minutes`, `max_advance_days`, `cancellation_window_hours` | número | Não | Em branco, segue o espaço |
| `image_url` ou `image_base64` | | Não | A foto |
| `owner_profile_id` | id | Não | Agendamento, proprietário e administrador: de quem é a agenda |

### `update_booking_resource`

<span class="tool-kind tool-kind-write">Altera</span>

**Editar.** Muda só o que você mandar; troca a foto com `image_url` ou `image_base64` e remove com `remove_image`. As reservas existentes **mantêm o preço**. Parâmetro `resource_id` mais os campos acima. No Agendamento, quem oferece edita a própria agenda, menos `listed`.

### `delete_booking_resource`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Excluir.** Com reservas futuras ativas, a resposta é `409` listando-as; com `cancel_bookings: true`, cancela todas (estorno por inteiro e e-mail para cada pessoa) e exclui. *Proprietário ou administrador.*

### `list_availability_exceptions`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Bloqueios (`CLOSED`) e horários extras (`OPEN`)** de uma sala daqui para frente. Parâmetros: `resource_id`, `from`.

### `create_availability_exception`

<span class="tool-kind tool-kind-write">Altera</span>

**Bloquear ou abrir um período.** `kind` é `CLOSED` (padrão: manutenção, feriado) ou `OPEN` (extra). Um bloqueio com reservas ativas é recusado com `409` listando-as: para cancelá-las, use `cancel_bookings_for_closure`. Salas: a equipe; agendas de pessoas: quem oferece e o proprietário e o administrador.

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `resource_id` | id | Sim | |
| `starts_at`, `ends_at` | data e hora | Sim | Hora local |
| `kind` | `CLOSED` ou `OPEN` | Não | Padrão `CLOSED` |
| `reason` | texto | Não | Aparece para quem tem a reserva cancelada |

### `cancel_bookings_for_closure`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Bloquear cancelando.** Bloqueia o período **e cancela** toda reserva ativa dentro dele: cada uma é estornada por inteiro, cada pessoa recebe o e-mail e o evento é cancelado na agenda. Diz quantas foram canceladas. Use depois que `create_availability_exception` respondeu `409` e a pessoa concordou. Parâmetros: `resource_id`, `starts_at`, `ends_at`, `reason`.

### `delete_availability_exception`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Remover** um bloqueio ou horário extra. As reservas que o bloqueio já cancelou **não voltam**. Parâmetros: `resource_id`, `exception_id`.

### `list_price_rules`

<span class="tool-kind tool-kind-read">Só consulta</span>

**As faixas de preço** de uma sala (a única fonte de preço; sem faixa, é grátis). Vale a primeira que se encaixa: data específica, depois dia da semana, depois o padrão; o custo é por bloco, e cada bloco usa a faixa em que começa. *Proprietário ou administrador.* Parâmetro: `resource_id`.

### `create_price_rule`

<span class="tool-kind tool-kind-write">Altera</span>

**Criar uma faixa.** Por exemplo, 3 créditos a cada 30 minutos. Um horário oferecido por membro é sempre grátis; no Agendamento, uma faixa paga precisa de **Permitir horários pagos** no espaço (`409`). Cobrança em dinheiro ainda não é feita.

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `resource_id` | id | Sim | |
| `mode` | `FREE` ou `CREDITS` | Sim | |
| `block_minutes` | 5 a 1440 | Com `CREDITS` | O tamanho do bloco |
| `credits` | inteiro | Com `CREDITS` | Créditos por bloco |
| `weekday` | 0 (domingo) a 6 | Não | Em branco, todos os dias |
| `specific_date` | `AAAA-MM-DD` | Não | Vale mais que o dia da semana |
| `from_time`, `to_time` | `HH:MM` | Não | O trecho do dia |

### `update_price_rule`

<span class="tool-kind tool-kind-write">Altera</span>

**Editar** uma faixa (`resource_id`, `rule_id`, e só o que mudar). As reservas já feitas mantêm o preço.

### `delete_price_rule`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Remover** uma faixa. Sem nenhuma, a sala fica grátis; as reservas já feitas mantêm o preço. Parâmetros: `resource_id`, `rule_id`.

## Agendamento

### `get_scheduling_config`

<span class="tool-kind tool-kind-read">Só consulta</span>

**As regras do espaço**: quem oferece (`offerers`), `allowPaidSlots`, `requireListingApproval`, se você pode oferecer agora, as suas agendas e, para o proprietário e o administrador, quantas ofertas esperam aprovação. O horário de membro é sempre grátis. Parâmetro: `space`.

### `search_scheduling_hosts`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Pessoas com horário livre.** Cada uma vem com as agendas, quantos horários livres tem e os próximos 3 (grátis ou o custo em créditos, com `canAfford`) e o seu saldo. Quando ninguém tem horário, sugere os mais próximos. Para marcar, use [`create_booking`](#create-booking).

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Sim | |
| `q` | texto | Não | Parte do nome |
| `date`, `from`, `to` | | Não | O dia e a janela; sem dia, os próximos 14 |
| `duration_minutes`, `host_profile_id`, `page`, `limit` | | Não | |

### `get_scheduling_host`

<span class="tool-kind tool-kind-read">Só consulta</span>

**A página de uma pessoa**, com a grade de horários livres por dia (1 a 7 dias). Uma pessoa sem agenda listada, que perdeu o papel ou de outra comunidade responde `404`. Parâmetros: `space`, `profile_id`, `date`, `days`, `duration_minutes`.

### `list_pending_scheduling_offers`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Agendas esperando aprovação**, cada uma com o dono e se ele ainda cumpre a regra de quem oferece. *Proprietário ou administrador.* Parâmetro: `space`.

### `set_booking_resource_listing`

<span class="tool-kind tool-kind-write">Altera</span>

**Aprovar ou retirar uma agenda.** `listed: true` aprova (a agenda aparece aos membros); `false` retira (não cancela nenhuma reserva já feita, só impede as novas). Reversível, sem confirmação. *Proprietário ou administrador.* Parâmetros: `resource_id`, `listed`.

## Relacionados

- [Reservas](/espacos/reservas)
- [Agendamento](/espacos/agendamento)
- [Ferramentas · Créditos](/mcp/ferramentas-creditos)
- [Ferramentas](/mcp/ferramentas)
- [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao)
- [Receitas](/mcp/receitas)