Ferramenta: list_events
Lista os eventos de uma determinada agenda que atendem às condições especificadas.
Principais recursos:
- Qualquer ID de agenda, que pode ser a agenda principal do usuário ou outras.
- Filtragem por período.
- Recupera TODOS os eventos que correspondem às restrições de tempo.
Se disponível, use a ferramenta search_events para pesquisas na agenda principal do usuário se:
- Você está consultando eventos que correspondem a um tópico, categoria ou objetivo específico (por exemplo, "reuniões de almoço", "sincronizações de projeto").
- Você precisa encontrar os eventos mais relevantes (K principais) em vez de todos os eventos que atendem às restrições.
- Você precisa de recursos de pesquisa semântica ou por palavra-chave.
Use essa ferramenta para consultas como:
- O que tem na minha agenda amanhã?
- O que tem na minha agenda para 14 de julho de 2025?
- Quais são minhas reuniões na semana que vem?
- Tenho algum conflito de horário hoje à tarde?
Quais reuniões o João tem amanhã?
Exemplo:
list_events(
startTime='2024-09-17T06:00:00',
endTime='2024-09-17T12:00:00',
pageSize=10
)
# Returns up to 10 calendar events between 6:00 AM and 12:00 PM on September 17, 2024 from the user's primary calendar.
O exemplo a seguir demonstra como usar curl para invocar a ferramenta list_events MCP.
| Solicitação curl |
|---|
curl --location 'https://calendarmcp.googleapis.com/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "list_events", "arguments": { // provide these details according to the tool MCP specification } }, "jsonrpc": "2.0", "id": 1 }' |
Esquema de entrada
ListEventsRequest
| Representação JSON |
|---|
{ "eventTypeFilter": [ string ], "calendarId": string "pageSize": integer "pageToken": string "startTime": string "endTime": string "timeZone": string "orderBy": string "fullText": string } |
| Campos | |
|---|---|
eventTypeFilter[] |
Opcional. Os tipos de evento a serem retornados. Os valores possíveis são:
Se estiver vazio, somente os seguintes tipos de eventos serão retornados: |
Campo de união
|
|
calendarId |
Opcional. O ID da agenda para listar eventos. O padrão é a agenda principal do usuário. |
Campo de união
|
|
pageSize |
Opcional. Número máximo de eventos retornados em uma página de resultados. O número de eventos na página resultante pode ser menor que esse valor ou nenhum, mesmo que haja mais eventos correspondentes à consulta. As páginas incompletas podem ser detectadas por um campo |
Campo de união
|
|
pageToken |
Opcional. Token que especifica qual página de resultados retornar. |
Campo de união
|
|
startTime |
Opcional. Limite inferior (exclusivo) para o horário de término de um evento. Somente eventos que terminam estritamente depois desse horário são retornados (ou seja, o início do período de pesquisa). O padrão é o horário atual se nem |
Campo de união
|
|
endTime |
Opcional. Limite superior (exclusivo) para o horário de início de um evento. Somente eventos que começam estritamente antes desse horário são retornados (ou seja, o fim do período de pesquisa). Se especificado, precisa ser maior ou igual a |
Campo de união
|
|
timeZone |
Opcional. Fuso horário usado na resposta e para resolver datas sem fuso horário na solicitação (formatado como um nome do banco de dados de fusos horários da IANA, por exemplo, |
Campo de união
|
|
orderBy |
Opcional. A ordem em que os eventos devem ser retornados. Os valores possíveis são:
|
Campo de união
|
|
fullText |
Opcional. Consulta de pesquisa de formato livre para pesquisar em título, descrição, local e participantes. |
Esquema de saída
ListEventsResponse
| Representação JSON |
|---|
{ "summary": string, "description": string, "updated": string, "timeZone": string, "accessRole": string, "defaultReminders": [ { object ( |
| Campos | |
|---|---|
summary |
Título da agenda. |
description |
Descrição da agenda. |
updated |
Horário da última modificação do calendário (como um carimbo de data/hora ISO 8601). |
timeZone |
O fuso horário da agenda. |
accessRole |
A função de acesso do usuário para essa agenda. Somente leitura. Os valores possíveis são:
|
defaultReminders[] |
Os lembretes padrão na agenda do usuário autenticado. Esses lembretes são válidos para todos os eventos da agenda que não os substituem explicitamente (ou seja, não preenchem override_reminders). |
events[] |
Lista de eventos na agenda. |
Campo de união
|
|
nextPageToken |
Token usado para acessar a próxima página deste resultado. Omitido se não houver mais resultados disponíveis. |
Lembrete
| Representação JSON |
|---|
{ "method": string "minutes": integer } |
| Campos | |
|---|---|
Campo de união
|
|
method |
Obrigatório. Como o lembrete é entregue ao usuário. Os valores possíveis são:
|
Campo de união
|
|
minutes |
Obrigatório. Número de minutos antes do lembrete ser enviado. |
Evento
| Representação JSON |
|---|
{ "id": string, "status": string, "htmlLink": string, "created": string, "updated": string, "summary": string, "description": string, "location": string, "creator": { object ( |
| Campos | |
|---|---|
id |
Identificador opaco do evento. Ao criar eventos únicos ou recorrentes, você pode especificar os IDs deles. Os IDs fornecidos precisam seguir estas regras:
Devido à natureza distribuída globalmente do sistema, não podemos garantir que colisões de ID serão detectadas no momento da criação do evento. Para minimizar o risco de colisões, recomendamos usar um algoritmo UUID estabelecido, como o descrito na RFC4122. Se você não especificar um ID, ele será gerado automaticamente pelo servidor. O icalUID e o ID não são idênticos, e apenas um deles deve ser fornecido no momento da criação do evento. Uma diferença na semântica é que, em eventos recorrentes, todas as ocorrências de um evento têm IDs diferentes, mas compartilham os mesmos icalUIDs. |
status |
Status do evento. Opcional. Os valores possíveis são:
Um status cancelado representa dois estados diferentes, dependendo do tipo de evento:
Na agenda do organizador, os eventos cancelados continuam mostrando os detalhes (resumo, local etc.) para que possam ser restaurados (recuperados). Da mesma forma, os eventos para os quais o usuário foi convidado e que ele removeu manualmente continuam fornecendo detalhes. No entanto, as solicitações de sincronização incremental com "showDeleted" definido como "false" não vão retornar esses detalhes. Se um evento mudar de organizador (por exemplo, usando a operação de movimentação) e o organizador original não estiver na lista de participantes, um evento cancelado será deixado para trás, em que apenas o campo "id" terá preenchimento garantido. |
htmlLink |
Um link absoluto para esse evento na interface da Web do Google Agenda. Somente leitura. |
created |
Hora de criação do evento (como um carimbo de data/hora formatado em ISO 8601). Somente leitura. |
updated |
Horário da última modificação dos dados de eventos principais (como um carimbo de data/hora formatado em ISO 8601). Atualizar os lembretes de eventos não vai mudar isso. Somente leitura. |
summary |
Título do evento. |
description |
É a descrição do evento. Pode conter HTML. Opcional. |
location |
Localização geográfica do evento como texto livre. Opcional. |
creator |
O criador do evento. Somente leitura. |
organizer |
O organizador do evento. Se o organizador também for um participante, isso será indicado com uma entrada separada em "participantes" com o campo "organizador" definido como "True". Somente leitura. |
start |
O horário de início do evento (inclusivo). Para um evento recorrente, esse é o horário de início da primeira instância. |
end |
O horário de término (exclusivo) do evento. Para um evento recorrente, esse é o horário de término da primeira instância. |
recurrence[] |
Lista de linhas RRULE, EXRULE, RDATE e EXDATE para um evento recorrente, conforme especificado na RFC5545. As linhas DTSTART e DTEND não são permitidas nesse campo. Os horários de início e término do evento são especificados nos campos "Início" e "Término". Esse campo é omitido para eventos únicos ou instâncias de eventos recorrentes. |
recurringEventId |
Para uma instância de um evento recorrente, é o ID do evento recorrente a que essa instância pertence. Imutável. |
originalStartTime |
Para uma instância de um evento recorrente, é o horário em que esse evento começaria de acordo com os dados de recorrência no evento recorrente identificado por recurringEventId. Ele identifica de forma exclusiva a instância na série de eventos recorrentes, mesmo que ela tenha sido movida para outro horário. Imutável. |
transparency |
Se o evento bloqueia um horário na agenda. Opcional. Os valores possíveis são:
|
visibility |
Visibilidade do evento. Opcional. Os valores possíveis são:
|
attendees[] |
Os participantes do evento. |
eventType |
Tipo específico do evento. Isso não pode ser modificado depois da criação do evento. Os valores possíveis são:
|
conferenceUrl |
O link do Google Meet para o evento. |
colorId |
ID da cor do evento (string
No Google Agenda, as cores dos eventos funcionam como categorias, que podem ser definidas por evento ou por série. Os usuários podem atribuir rótulos personalizados a cores na interface da Web (por exemplo, |
overrideReminders[] |
Lembretes definidos para este evento, substituindo os lembretes padrão da agenda. Se não for definido, os lembretes padrão do calendário serão usados. |
Principal
| Representação JSON |
|---|
{ "email": string, "displayName": string, "self": boolean } |
| Campos | |
|---|---|
email |
Endereço de e-mail do principal (agenda). |
displayName |
O nome do principal, se disponível. |
self |
Se esse principal corresponde à agenda em que essa cópia do evento aparece. Somente leitura. O valor padrão é falso. |
DateOrDateTime
| Representação JSON |
|---|
{ "date": string, "dateTime": string, "timeZone": string } |
| Campos | |
|---|---|
date |
Uma data formatada no padrão ISO 8601 à meia-noite UTC, como |
dateTime |
Um carimbo de data/hora formatado em ISO 8601, como |
timeZone |
Nome do fuso horário TZDB, se disponível. |
Convidado
| Representação JSON |
|---|
{ "id": string, "email": string, "displayName": string, "organizer": boolean, "self": boolean, "resource": boolean, "optionalAttendee": boolean, "responseStatus": string, "comment": string, "additionalGuests": integer } |
| Campos | |
|---|---|
id |
O ID do perfil do participante, se disponível. |
email |
O endereço de e-mail do participante, se disponível. Esse campo precisa estar presente ao adicionar um participante. Ele precisa ser um endereço de e-mail válido, de acordo com a RFC5322. Obrigatório ao adicionar um participante. |
displayName |
O nome do participante, se disponível. Opcional. |
organizer |
Se o participante é o organizador do evento. Somente leitura. O valor padrão é falso. |
self |
Se esta entrada representa a agenda em que esta cópia do evento aparece. Somente leitura. O valor padrão é falso. |
resource |
Se o participante é um recurso. Só pode ser definido quando o participante é adicionado ao evento pela primeira vez. Modificações subsequentes são ignoradas. Opcional. O valor padrão é falso. |
optionalAttendee |
Indica se o participante é opcional. Opcional. O valor padrão é falso. |
responseStatus |
O status da resposta do participante. Os valores possíveis são:
|
comment |
O comentário de resposta do participante. Opcional. |
additionalGuests |
Número de hóspedes extras. Opcional. O padrão é 0. |
Anotações de ferramentas
Dica destrutiva: ❌ | Dica idempotente: ✅ | Dica somente leitura: ✅ | Dica de mundo aberto: ❌