Calendar tools

Tools that read the stored state of your connected calendars.

These tools read the stored state of your connected calendars. They need the permission integrations:read, which you grant on the Authorize access page when you connect.

This page is generated from the connector’s tool catalogue. It describes 4 tools. Every tool reads or writes only your own account.

Permissions this page needs

• integrations:read: Read your connected calendar sources and their stored connection status

The permissions reference lists every permission you can grant.

calendars.sources.list

Your agent host shows this tool as “List calendar sources”.

List the authenticated student’s stored calendar sources with measured pagination.

Permissions: This tool needs integrations:read, which the Authorize access page describes as “Read your connected calendar sources and their stored connection status”.

Risk: read. This tool only reads your own data. It never changes anything and it never asks for your approval.

Input

Property	Type	Required	Bounds
cursor	string	no	1 to 512 characters; pattern ^[A-Za-z0-9_-]+$
limit	integer	no	from 1 to 20

Example call

calendars.sources.list input

{
  "limit": 10
}

Result

A result is never larger than 16,384 bytes.

A result carries these top-level fields:

Top-level fields

[
  "nextCursor",
  "sources"
]

Errors

A failed call returns one protocol error with no error code, and its text is Tool call failed. every time. This tool looks up no record by id, so it never sends a text that names a record. The error codes page gives every text a read failure can carry.

calendars.sources.get

Your agent host shows this tool as “Get calendar source”.

Read one authenticated student calendar source without credentials, feed URLs, provider messages, or provider calendar identifiers.

Permissions: This tool needs integrations:read, which the Authorize access page describes as “Read your connected calendar sources and their stored connection status”.

Risk: read. This tool only reads your own data. It never changes anything and it never asks for your approval.

Input

Property	Type	Required	Bounds
cursor	string	no	1 to 512 characters; pattern ^[A-Za-z0-9_-]+$
id	string	yes	pattern ^[a-f0-9]{24}$

Example call

calendars.sources.get input

{
  "id": "c0ffeec0ffeec0ffee000008"
}

Result

A result is never larger than 16,384 bytes. If the stored value does not fit, the tool returns a measured fragment and a cursor for the next one.

This tool’s result takes one of these 2 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.

Shape 1

Top-level fields

[
  "source"
]

Shape 2

Top-level fields

[
  "fragment",
  "nextCursor",
  "source"
]

Errors

A failed call returns one protocol error with no error code. Its text is Tool call failed. in every case but one: a call that finds no calendar source of yours says so and tells the agent to call the matching list tool. The error codes page quotes that text in full and lists the eight kinds of record it can name.

calendars.status.get

Your agent host shows this tool as “Get calendar status”.

Read calendar connection status. By default this reads stored values only, so a grant revoked at Google can still read as connected. Set verify to true to check the primary Google calendar with Google now: verification is ok, needs_reconnect, could_not_verify (Google could not be reached, so nothing is known), or not_connected.

Permissions: This tool needs integrations:read, which the Authorize access page describes as “Read your connected calendar sources and their stored connection status”.

Risk: read. This tool only reads your own data. It never changes anything and it never asks for your approval.

Input

Property	Type	Required	Bounds
verify	boolean	no	none stated

Example call

calendars.status.get input

{}

Result

A result is never larger than 16,384 bytes.

A result carries these top-level fields:

Top-level fields

[
  "primary",
  "sources",
  "sourcesTruncated",
  "verification"
]

Errors

A failed call returns one protocol error with no error code, and its text is Tool call failed. every time. This tool looks up no record by id, so it never sends a text that names a record. The error codes page gives every text a read failure can carry.

calendars.selected.list

Your agent host shows this tool as “List selected calendars”.

List the authenticated student’s stored primary-calendar selection flags in stable stored order.

Permissions: This tool needs integrations:read, which the Authorize access page describes as “Read your connected calendar sources and their stored connection status”.

Risk: read. This tool only reads your own data. It never changes anything and it never asks for your approval.

Input

Property	Type	Required	Bounds
cursor	string	no	1 to 512 characters; pattern ^[A-Za-z0-9_-]+$

Example call

calendars.selected.list input

{}

Result

A result is never larger than 16,384 bytes. If the stored value does not fit, the tool returns a measured fragment and a cursor for the next one.

This tool’s result takes one of these 2 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.

Shape 1

Top-level fields

[
  "calendars",
  "nextCursor"
]

Shape 2

Top-level fields

[
  "calendars",
  "fragment",
  "nextCursor"
]

Errors

A failed call returns one protocol error with no error code, and its text is Tool call failed. every time. This tool looks up no record by id, so it never sends a text that names a record. The error codes page gives every text a read failure can carry.