Calendar bot in Telegram messenger With MCP you can create events/reminders, get your schedule, notes, plans etc
Scored across 19 tools
Each tool has a clear, distinct purpose: event CRUD, status changes, conflict/free-slot checks, holiday lookups, notes, and flow tracking are all separate concerns. Even the render tools are clearly distinguished from data-fetching tools by their explicit 'does not read the calendar store' note.
Most tools follow a consistent verb_noun pattern (create_event, delete_event, get_event, update_event, search_events, save_note, get_notes). Minor deviations exist: render_agenda and render_event are verb_noun but less common, and set_event_status could be update_event_status for full consistency, but the pattern is still predictable.
With 19 tools, the server covers a broad but cohesive domain: events, tasks, notes, holidays, flow tracking, calendar management, and rendering. Each tool serves a clear purpose, and the count is justified for the feature set; it's not bloated or redundant.
The tool surface is comprehensive: event lifecycle (create, read, update, delete, status change, search, list calendars), plus conflict/free-slot utilities and auxiliary features (notes, holidays, flows). The only minor gap is a dedicated 'update_flow' (only save and delete exist), but save_flow with event start/end effectively covers updates, so no significant dead ends.
Create an event or task for the authenticated user. title is required (1–200 characters). start and end are ISO 8601 date-time with offset, or YYYY-MM-DD for an all-day event in the event timezone. timezone is an IANA name (default UTC) and stays the event zone — it is not replaced by the user timezone. rrule is an iCalendar RRULE string. status is active, done, undone, or cancelled. type is event or task. location is a short place name. waitSync defaults to true and waits for the external calendar so the response can include links; false responds immediately and links may be absent.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ISO 8601 date-time with offset, or YYYY-MM-DD for an all-day event in the event timezone | |
| desc | No | Description (up to 1000 characters) | |
| type | No | event is a timed item; task is a to-do without a duration | |
| rrule | No | iCalendar RRULE string for a repeating event | |
| start | No | ISO 8601 date-time with offset, or YYYY-MM-DD for an all-day event in the event timezone | |
| title | Yes | Event or task title (1–200 characters) | |
| allDay | No | True when start and end are calendar dates without a time | |
| status | No | Event status: active, done, undone, or cancelled | |
| location | No | Short place name | |
| timezone | No | IANA timezone of the event; stored as-is, not replaced by the user timezone | |
| waitSync | No | Wait for the external calendar so the response can include links; default true | |
| calendarId | No | Calendar that owns the event; omit for the default calendar |
| Name | Required | Description |
|---|---|---|
| id | Yes | Event id |
| end | No | End in the user timezone (ISO 8601) |
| desc | No | Description |
| type | No | event is a timed item; task is a to-do without a duration |
| links | No | External calendar links when sync has finished |
| rrule | No | iCalendar RRULE string when the event repeats |
| start | No | Start in the user timezone (ISO 8601) |
| title | Yes | Event or task title |
| allDay | No | True when the event is a calendar date without a time |
| status | No | Event status: active, done, undone, or cancelled |
| location | No | Short place name |
| timezone | No | IANA timezone stored on the event |
| createdAt | No | When the event was created (ISO 8601) |
| updatedAt | No | When the event was last changed (ISO 8601) |
| calendarId | No | Calendar that owns the event |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false, destructiveHint=false). The description adds meaningful behavioral context: waitSync controls whether the response includes links, timezone is stored as-is rather than replaced by the user timezone, and all-day events use YYYY-MM-DD. These are non-obvious behaviors that help an agent predict side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose appears in the first sentence, followed by the most important constraints. It covers 12 parameters without becoming a wall of text, though a couple of details (e.g., status enum values) are also present in the schema and could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 12 parameters and an output schema, the description covers the essential decision points: required field, date/time formats, timezone semantics, recurrence, status, type, and waitSync behavior. It does not explain return values, but the output schema exists, so that is not a gap. It could be more explicit about when to omit calendarId, but the schema already says 'omit for the default calendar'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter. The description adds value by clarifying the timezone behavior, the waitSync trade-off, and the all-day date format, which are semantic details beyond the schema's field-level descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create') and resource ('event or task'), and immediately distinguishes the two item types. It also names the required field and key constraints, so an agent can tell this tool from siblings like update_event or set_event_status without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: creating an event or task for the authenticated user, with the required title and optional scheduling fields. It does not explicitly name alternatives or exclusions, but the sibling list and the create/update distinction make the usage context reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an event owned by the authenticated user. mode all removes the whole series (default). occurrence removes one date; following removes that date and later ones. occurrence and following require occurrenceDate as ISO 8601 date or date-time. A missing id and an id owned by someone else both return not found.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Event id owned by the authenticated user; any other id returns not found | |
| mode | No | all removes the series; occurrence one date; following that date and later | |
| occurrenceDate | No | Occurrence date of a repeating event (ISO 8601 date or date-time) |
| Name | Required | Description |
|---|---|---|
| ok | Yes | True when the change was applied |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds important behavioral context: ownership enforcement, not-found behavior for missing/foreign ids, and the mode-dependent scope of deletion. It does not explicitly mention irreversibility, but the destructive annotation plus 'removes' makes that clear. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states the core action first, then mode semantics, then parameter requirements, then edge-case behavior. Every sentence earns its place, and the structure is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, modes, parameter requirements, and error behavior. It does not describe the output schema, but an output schema exists, so that is not required. It could mention that deletion is irreversible, but the destructiveHint annotation already signals this. Overall, it is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the mode semantics and the requirement that occurrenceDate is needed for occurrence/following modes, which is not fully explicit in the schema alone. This goes beyond the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes an event owned by the authenticated user, and distinguishes it from update_event and set_event_status. It also explains the three modes (all, occurrence, following) with precise semantics, so an agent can immediately understand what the tool does and how it differs from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use each mode: 'all removes the whole series (default), occurrence removes one date, following removes that date and later.' It also states that occurrence and following require occurrenceDate, and that a missing id or an id owned by someone else returns not found. This gives clear usage guidance and edge-case behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a menstrual-cycle start or end mark for the authenticated user. date is YYYY-MM-DD. event is flowstart or flowend.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Calendar date (YYYY-MM-DD) | |
| event | Yes | flowstart or flowend |
| Name | Required | Description |
|---|---|---|
| ok | Yes | True when the change was applied |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the destructive nature is covered. The description adds the scoping to 'the authenticated user' and clarifies the date/event format, which is useful context. However, it does not describe side effects beyond deletion (e.g., irreversibility), but annotations cover the core safety profile, keeping this at a baseline acceptable level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler. The primary action and scope are front-loaded, and the parameter details are stated efficiently. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, presence of an output schema, and annotations covering idempotency and destructiveness, the description is sufficient. It communicates the exact action, required parameters, and user scope. Minor omissions like error handling or idempotency behavior are already implied by annotations, so no critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description repeats the parameter formats ('date is YYYY-MM-DD. event is flowstart or flowend') exactly as the schema does. It adds no new meaning beyond what the schema already provides, so the baseline 3 for high coverage applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete') and resource ('menstrual-cycle start or end mark'), and the title reinforces this. It clearly distinguishes from siblings like save_flow (which creates/updates) and delete_event (which targets calendar events). An agent can immediately tell what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clarifies that it operates on the authenticated user's data and specifies the required parameters. It does not explicitly name alternatives or when-not-to-use, but given the sibling tools (save_flow, get_flows), the context is fairly clear. It provides sufficient guidance for correct invocation without ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find overlapping events in the authenticated user calendar. from and to are optional ISO 8601 date or date-time (default ±31 days). The window cannot exceed 366 days. Optional start and end check a proposed slot against existing events before create_event. Optional calendarId limits the search to one calendar. Intervals that only touch at an endpoint are not a conflict.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ISO 8601 date or date-time; default 31 days after now; the window cannot exceed 366 days | |
| end | No | Proposed slot end to check before create_event | |
| from | No | ISO 8601 date or date-time; default 31 days before now; the window cannot exceed 366 days | |
| start | No | Proposed slot start to check before create_event | |
| calendarId | No | Limit results to one calendar id |
| Name | Required | Description |
|---|---|---|
| conflicts | Yes | Connected groups of overlapping events |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral details beyond the annotations: the ±31-day default, the 366-day maximum window, and especially the rule that intervals touching only at an endpoint are not conflicts. These are not obvious from the schema and are important for correct interpretation of results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and each sentence covers a distinct piece of information. It is compact and useful, though a few points are also present in the schema descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with five optional parameters and rich schema/annotation coverage, the description covers the essential operational context: defaults, limits, proposed-slot usage, calendar filtering, and the conflict-boundary rule. It does not specify exact behavior when the window limit is exceeded, but this is a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds extra value by tying start/end to the 'before create_event' workflow and clarifying that the interval boundary rule applies to overlap, which is not fully stated in the parameter schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Find overlapping events in the authenticated user calendar.' It also establishes the time-window scope and the proposed-slot use case, which distinguishes it from sibling tools like search_events or get_free_slots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete when-to-use context: use the optional start/end to validate a proposed slot before calling create_event, and use calendarId to narrow the search. It does not explicitly name alternatives or exclusion conditions, so it has clear context without full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one event owned by the authenticated user by id. A missing id and an id owned by someone else both return not found. Dates use the user timezone.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Event id owned by the authenticated user; any other id returns not found |
| Name | Required | Description |
|---|---|---|
| id | Yes | Event id |
| end | No | End in the user timezone (ISO 8601) |
| desc | No | Description |
| type | No | event is a timed item; task is a to-do without a duration |
| links | No | External calendar links when sync has finished |
| rrule | No | iCalendar RRULE string when the event repeats |
| start | No | Start in the user timezone (ISO 8601) |
| title | Yes | Event or task title |
| allDay | No | True when the event is a calendar date without a time |
| status | No | Event status: active, done, undone, or cancelled |
| location | No | Short place name |
| timezone | No | IANA timezone stored on the event |
| createdAt | No | When the event was created (ISO 8601) |
| updatedAt | No | When the event was last changed (ISO 8601) |
| calendarId | No | Calendar that owns the event |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true associative, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds valuable context: it discloses that a missing id and an id owned by someone else both return not found, preventing the agent from expecting an error or different behavior for 'not found' cases. It also notes that dates use the user timezone, which is useful but not critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each with a clear purpose: identifies the action and ownership, clarifies error behavior, and notes date handling. No wasted words; the key constraint (ownership) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool with a full output schema and safety annotations, the description is largely sufficient. It does not explain the return format, but the output schema exists, so that is covered. It also does not describe pagination or errors in detail, but for a single-event fetch that is not necessary. The ownership scoping is well-covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the schema already describes the id parameter and its semantics (owned by the user, any other id returns not found). The description adds no additional parameter-level detail beyond what the schema provides, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get') and resource ('one event owned by the authenticated user by id'), immediately distinguishing it from siblings like 'search_events' or 'list_calendars' by emphasizing ownership and single-id lookup. It also clarifies the core scope: only events owned by the user are accessible.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: this tool fetches exactly one event by id, and implies it is not for listing or searching (which have dedicated siblings). However, it does not explicitly say when NOT to use it (e.g., for lists or searches) or mention alternatives, though the sibling list and tool naming make the distinction obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get menstrual-cycle periods, settings, and history for the authenticated user. Period bounds use the user timezone. Dates in history are YYYY-MM-DD. Does not include cycle-share links or secrets.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| opts | Yes | Cycle settings without share secrets |
| history | Yes | User-marked cycle starts and ends |
| periods | Yes | Cycle periods |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so safety is well covered. The description adds meaningful behavioral context beyond annotations: period bounds use the user timezone, history dates are formatted YYYY-MM-DD, and secrets are intentionally omitted. This level of additional detail is appropriate for annotations that already cover the operational profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no filler, and the core purpose is front-loaded in the first clause. Every sentence earns its place: what it returns, timezone behavior, date format, and negative scope. This is a model of concise, effective tool documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool with a full output schema and annotations covering safety, the description is complete. It adds the only contextual details an agent might need beyond structured data: timezone semantics, date format, and the absence of secrets. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is vacuously 100%, so there is nothing for the description to add about parameter meaning. The description correctly stays silent on parameters rather than inventing unnecessary detail. Per the baseline for a 0-parameter tool, this is well handled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets menstrual-cycle periods, settings, and history for the authenticated user. This specific verb+resource combination distinguishes it from sibling tools like get_me, get_notes, and get_holidays. The scope is further tightened by the explicit exclusion of cycle-share links and secrets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the read operation for menstrual-cycle data, contrasted with write siblings like save_flow and delete_flow. However, it does not explicitly state when to choose this over alternatives or mention any exclusion conditions. The negative scope hint is useful but does not fully replace explicit when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find unoccupied time windows in the authenticated user calendar. from and to are optional ISO 8601 date or date-time (default ±31 days). The window cannot exceed 366 days. duration is the minimum slot length in minutes (default 30, range 5–1440). Optional dayStart and dayEnd limit the search to a workday in HH:MM (24-hour, user timezone). Slot bounds use the user timezone.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ISO 8601 date or date-time; default 31 days after now; the window cannot exceed 366 days | |
| from | No | ISO 8601 date or date-time; default 31 days before now; the window cannot exceed 366 days | |
| dayEnd | No | Workday end in HH:MM (24-hour, user timezone) | |
| dayStart | No | Workday start in HH:MM (24-hour, user timezone) | |
| duration | No | Minimum slot length in minutes (default 30, range 5–1440) |
| Name | Required | Description |
|---|---|---|
| slots | Yes | Unoccupied windows at least as long as duration |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds substantial behavioral detail: default time window (±31 days), maximum 366-day window, duration range, workday limits via dayStart/dayEnd, and timezone handling. These details go well beyond annotations and clarify edge-case behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it opens with the core purpose, then details parameters in a logical order, and ends with a timezone note. No filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description covers all necessary invocation details: parameter defaults, constraints, workday limits, and timezone behavior. It provides complete context for an agent to call the tool correctly without missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented. The description largely restates these defaults and ranges, adding only a marginal note about slot bounds using the user timezone. It does not introduce significant new meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds unoccupied time windows in the authenticated user calendar, using the verb 'find' with a specific resource. This distinguishes it from siblings like find_conflicts or get_event without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (to discover free time slots) and explains parameter usage with defaults and constraints, but it does not explicitly name alternative tools or state when not to use it. This is clear context without exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get public holidays for a country and year. country is a code from list_holiday_countries. lang is optional (defaults to the user locale, then en). year is optional (defaults to the current year). Dates in the result are YYYY-MM-DD.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language for titles (defaults to the user locale, then en) | |
| year | No | Year (defaults to the current year) | |
| country | Yes | Country code from list_holiday_countries |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral detail beyond annotations: defaulting rules for lang and year and the YYYY-MM-DD date format in results. No hidden side effects or contradictions are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each carrying distinct information: the operation, parameter defaults, and result date format. The main purpose is front-loaded, and there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only lookup with an output schema and fully documented parameters, the description covers everything needed to call it correctly: required country, optional lang/year defaults, country-code source, and date format. No critical context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description largely restates the schema's parameter docs (country code source, lang default, year default). It adds no new parameter semantics beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource statement, 'Get public holidays for a country and year,' which clearly identifies the tool's function and distinguishes it from calendar-event tools like get_event/search_events. Referencing list_holiday_countries as the source of country codes further anchors its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: when a public-holiday lookup is needed, and it directs the agent to list_holiday_countries for valid country codes. It does not explicitly state when not to use the tool, but no competing sibling tool covers public holidays, so this is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Profile of the authenticated user: id, name, username, timezone, locale. The timezone field is the IANA zone in which every date in this API is returned (ISO 8601 with that offset). Full settings are never returned.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| id | Yes | Authenticated user id |
| locale | Yes | UI locale |
| lastname | Yes | Last name |
| timezone | Yes | IANA timezone used for dates in this API |
| username | Yes | Username |
| firstname | Yes | First name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable context: explains the timezone field's meaning (IANA zone, affects all dates in API) and notes that full settings are never returned. This goes beyond the annotations, though there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise two-sentence description; front-loads the purpose and fields, then adds a key clarification about the timezone and a limitation. Every sentence earns its place, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is simple (no parameters), and the output schema exists (so return values are documented), the description is complete. It covers purpose, the critical timezone semantics, and what to expect (and not expect). An agent can call this tool correctly without further information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has zero parametersaine, so there is nothing for the description to explain about parameters. The description effectively lists the output fields, which is relevant even though they are not parameters. Since there are no parameters, a baseline 4 is appropriate; the description adds value by listing fields, even though the output schema is present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear and specific: states it returns the authenticated user's profile, listing the exact fields (id, name, username, timezone, locale). This unambiguously distinguishes it from siblings like get_event or get_flows, which are about other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage: since it's the only tool with no parameters and returns the user profile, it's likely used to get the authentication contextcule. However, it doesn't explicitly state when to use it vs. alternatives, but the purpose is clear enough that an agent can infer it's for the current user's info. No exclusions are mentioned, but none are needed as it's a simple getter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List daily notes of the authenticated user in a time window. from and to are optional ISO 8601 date or date-time (default ±31 days). The window cannot exceed 366 days. Dates in the result are YYYY-MM-DD.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ISO 8601 date or date-time; default 31 days after now; the window cannot exceed 366 days | |
| from | No | ISO 8601 date or date-time; default 31 days before now; the window cannot exceed 366 days |
| Name | Required | Description |
|---|---|---|
| notes | Yes | Daily notes in the requested window |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful constraints beyond annotations: the default ±31-day window, the 366-day maximum, and the YYYY-MM-DD result format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no filler: purpose, parameter behavior, and result format. The most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with two optional parameters and an output schema, the description covers defaults, constraints, user scope, and result date format. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already documented thoroughly. The description largely restates the same defaults and limit, adding little new meaning for the parameters themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List daily notes of the authenticated user in a time window.' This clearly distinguishes the tool from calendar/event siblings and states its exact scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is clear from the description: retrieve daily notes over a time window with optional bounds. It does not explicitly name alternatives or exclusion criteria, but the context is strong enough that an agent can decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List calendars owned by the authenticated user. Returns id, name, description, image id, and whether the calendar is shared. Does not include calendars of other users.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| calendars | Yes | Calendars owned by the authenticated user |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds the ownership scope and the list of returned fields, which is useful. However, it doesn't mention pagination, ordering, or whether deleted calendars are included, though these are not critical for a simple list tool with no parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. The purpose is stated first, followed by return fields and an exclusion note. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema in the prompt (though context says it exists), and annotations cover safety, the description is nearly complete. It names return fields and scope. Minor gaps like pagination or sorting exist, but for a simple list operation, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (empty properties). The description compensates beautifully by listing the exact fields returned (id, name, description, image id, shared status), giving the agent full clarity on output semantics. Since there are no params, the baseline is 4, and the description exceeds it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists calendars owned by the authenticated usercars, enumerates the returned fields (id, name, description, image id, shared status), and explicitly excludes other users' calendars. This is specific and distinguishes it from any tool that might list all calendars.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies an ownership scope ('owned by the authenticated user') and states what it does not include ('does not include calendars of other users'). While it doesn't name alternative tools or conditions, given the sibling list includes many event-related tools, this tool is clearly for calendar listing and the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List country codes that have public-holiday data. Use a code as country in get_holidays.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| countries | Yes | Country codes that have holiday data |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond that: it specifies that only countries with public-holiday data are included, and it clarifies the data's intended downstream use with get_holidays. This adds value without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The primary purpose is stated first, followed by a direct and actionable link to the sibling tool. Every word earns its place; no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only listing tool with an output schema (indicated by 'Has output schema: true'), the description fully covers what an agent needs: what the tool returns (country codes) and how to use the result (in get_holidays). Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially complete. The description has no need to elaborate on parameters and doesn't attempt to. The baseline of 4 for zero-parameter tools is appropriate, as there is nothing more to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('country codes that have public-holiday data'), making the purpose immediately clear. It also distinguishes itself from siblings by explicitly referencing get_holidays, which is the only other holiday-related tool, so an agent can easily tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (to obtain country codes) and even instructs the agent to use the resulting code as the 'country' parameter in get_holidays. It doesn't explicitly state when NOT to use it, but the use case is so unambiguous that no exclusion is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a week or month agenda in the chat. First call search_events with the same from and to, then pass view plus that window and events here. This tool only renders; it does not read the calendar store.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | ISO 8601 date or date-time; end of the agenda window | |
| from | Yes | ISO 8601 date or date-time; start of the agenda window | |
| view | Yes | week or month agenda | |
| events | Yes | Events already loaded for this window | |
| timezone | No | IANA timezone for the agenda |
| Name | Required | Description |
|---|---|---|
| to | Yes | Window end (ISO 8601 date or date-time) |
| from | Yes | Window start (ISO 8601 date or date-time) |
| view | Yes | Agenda range shown in the chat |
| events | Yes | Events already loaded for this window |
| timezone | No | IANA timezone for the agenda |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=trueainer and idempotentHint=true, indicating no side effects. The description adds value by explicitly stating it does not read the calendar store, which is a key behavioral trait beyond the annotations. It also implies it requires pre-fetched events, adding necessary context for correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two sentences. The purpose is front-loaded, then usage instructions are given, and a warning about side effects is included. No filler words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so the description need not explain return values. It provides the essential pipeline (search then render) and clarifies its read-only naturesame. Given the rich input schema and output schema, this is complete enough for an agent to execute correctly. A tiny gap is not explicitly saying the 'timezone' parameter is required, but the schema marks it required, so that's acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents all parameters. The description adds some semantic context by specifying that 'from' and 'to' define the window and that 'events' must be pre-loaded, but it does not elaborate on the format or constraints beyond what the schema provides. Thus a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Show[s] a week or month agenda in the chat' with a specific verb and resource. It distinguishes itself from sibling render_event by focusing on week/month agendas, and implies it is distinct from data-fetching tools by noting it only renders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage instructions: 'First call search_events with the same from and to, then pass view plus that window and events here.' This tells the agent the prerequisite call and exactly how to construct arguments, distinguishing it from search_events. It also states a boundary: 'This tool only renders; it does not read the calendar store,' preventing misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show an event card in the chat. First call get_event or search_events, then pass that PublicEvent here. This tool only renders; it does not read the calendar store.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Event id | |
| end | No | End in the user timezone (ISO 8601) | |
| desc | No | Description | |
| type | No | event is a timed item; task is a to-do without a duration | |
| links | No | External calendar links when sync has finished | |
| rrule | No | iCalendar RRULE string when the event repeats | |
| start | No | Start in the user timezone (ISO 8601) | |
| title | Yes | Event or task title | |
| allDay | No | True when the event is a calendar date without a time | |
| status | No | Event status: active, done, undone, or cancelled | |
| location | No | Short place name | |
| timezone | No | IANA timezone stored on the event | |
| createdAt | No | When the event was created (ISO 8601) | |
| updatedAt | No | When the event was last changed (ISO 8601) | |
| calendarId | No | Calendar that owns the event |
| Name | Required | Description |
|---|---|---|
| id | Yes | Event id |
| end | No | End in the user timezone (ISO 8601) |
| desc | No | Description |
| type | No | event is a timed item; task is a to-do without a duration |
| links | No | External calendar links when sync has finished |
| rrule | No | iCalendar RRULE string when the event repeats |
| start | No | Start in the user timezone (ISO 8601) |
| title | Yes | Event or task title |
| allDay | No | True when the event is a calendar date without a time |
| status | No | Event status: active, done, undone, or cancelled |
| location | No | Short place name |
| timezone | No | IANA timezone stored on the event |
| createdAt | No | When the event was created (ISO 8601) |
| updatedAt | No | When the event was last changed (ISO 8601) |
| calendarId | No | Calendar that owns the event |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful context: 'This tool only renders; it does not read the calendar store.' This clarifies the data source and side-effect profile beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the primary purpose and followed by workflow and behavioral caveats. No filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what to pass and where it comes from, the tool has a rich output schema, and annotations cover safety. For a rendering-only tool, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter. The description adds the high-level guidance to pass a PublicEvent from a prior call, but no additional per-parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Show an event card in the chat.' It also distinguishes itself from data-fetching siblings like get_event and search_events by positioning them as prior steps, and from render_agenda through the focus on a single event card.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit ordering guidance: 'First call get_event or search_events, then pass that PublicEvent here.' It does not explicitly mention when not to use it or name render_agenda as an alternative, but the intended workflow is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a menstrual-cycle start or end for the authenticated user. date is YYYY-MM-DD. event is flowstart or flowend.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Calendar date (YYYY-MM-DD) | |
| event | Yes | flowstart or flowend |
| Name | Required | Description |
|---|---|---|
| ok | Yes | True when the change was applied |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds only the authenticated-user scope and the allowed event values, which are already present in the schema. It does not explain whether marking an existing date overwrites a prior flow or how repeated calls behave, though the idempotent hint partially mitigates this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the core action is front-loaded, followed by a compact parameter summary. It contains no filler and each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description plus schema fully cover the two required parameters, and annotations/output schema cover safety and return values. The only meaningful gap is a brief note on how a new flowstart/flowend relates to an existing flow record, but this is a nuance rather than a blocker for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description simply restates 'date is YYYY-MM-DD' and 'event is flowstart or flowend.' No additional parameter semantics, constraints, or examples are provided beyond what the schema already declares.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a concrete verb ('Mark'), names the resource ('menstrual-cycle start or end'), and scopes it to the authenticated user. It clearly differentiates from sibling tools like create_event (generic calendar event) and delete_flow/get_flows (flow lifecycle operations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for recording flow boundaries and correctly restricts event values to flowstart/flowend. However, it does not explicitly say when to choose this over create_event/update_event or state what not to use it for, leaving usage largely inferred from the title and sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or replace a daily note for the authenticated user. date is YYYY-MM-DD. text is the note body (up to 1000 characters). emoji is an optional list of emoji strings. append true adds text to the existing note instead of replacing it. Clearing the text deletes the note and still returns an empty note for that date.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Calendar date (YYYY-MM-DD) | |
| text | No | Note body (up to 1000 characters) | |
| emoji | No | Emoji strings attached to the note | |
| append | No | True adds text to the existing note instead of replacing it |
| Name | Required | Description |
|---|---|---|
| date | Yes | Note date (YYYY-MM-DD) |
| text | Yes | Note body |
| emoji | Yes | Emoji attached to the note |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the provided annotations. It says append=true adds to an existing note, making repeated identical calls non-idempotent despite idempotentHint=true, and says clearing text deletes the note despite destructiveHint=false. Per the rubric, any contradiction scores 1.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The main operation is front-loaded and the parameter explanations are short. A little redundancy with the schema exists (e.g., restating emoji and append), but every sentence communicates something relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers create/replace/append/delete modes and return behavior, but it does not clarify behavior when optional text is omitted (only date is required) or the default for append. Combined with the annotation contradictions, an agent cannot reliably predict the tool's side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents date, text, emoji, and append. The description adds value by spelling out that clearing text deletes the note and emoji is optional, but it leaves ambiguity about whether omitting text is the same as clearing it and what the default for append is.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action and resource: create or replace a daily note for the authenticated user. It clearly distinguishes itself from sibling tools like get_notes (read) and save_flow (flow-specific). The title and first sentence make the tool's scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this is the write path for daily notes, so an agent can infer when to choose it over read siblings. It does not explicitly name alternatives or state exclusions, but the intended context is not ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List events in a time window for the authenticated user, including items from subscribed or shared calendars. from and to are optional ISO 8601 date or date-time (default ±31 days). The window cannot exceed 366 days. Optional calendarId filters one calendar; optional q matches title or description (case-insensitive). Dates in the result use the user timezone.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Case-insensitive substring match on title or description | |
| to | No | ISO 8601 date or date-time; default 31 days after now; the window cannot exceed 366 days | |
| from | No | ISO 8601 date or date-time; default 31 days before now; the window cannot exceed 366 days | |
| calendarId | No | Limit results to one calendar id |
| Name | Required | Description |
|---|---|---|
| events | Yes | Events in the requested window |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal read-only and non-destructive behavior. The description adds useful operational context: authenticated-user scope, subscribed/shared calendar inclusion, default ±31 days, maximum 366-day window, and result datetime timezone. No mention of pagination or sort order, so slightly less than full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences: purpose and scope first, then defaults, limits, and filters. No fluff, no redundancy beyond schema-required grounding, and the most decision-relevant information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a read-only annotation and an output schema present, the description covers scope, constraints, timezone behavior, and filter options well. It does not mention pagination or result limits, but that gap is minor given the schema richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptionsants. The description largely restates them, though it adds useful context like the default time window and max span. Baseline 3 is appropriate since the schema carries most parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource—'List events in a time window'—which immediately conveys the core action and distinguishes it from write tools like create_event. It also clarifies the data scope ('for the authenticated user', including subscribed/shared calendars), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys when to use it: listing events within a time window, with optional filters. However, it does not explicitly compare against siblings like get_event or get_free_slots, so an agent must infer the differentiation rather than being told.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set status of an event owned by the authenticated user. status is active, done, undone, or cancelled. For a repeating task pass occurrenceDate as ISO 8601 date or date-time so only that day changes. A missing id and an id owned by someone else both return not found.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Event id owned by the authenticated user; any other id returns not found | |
| status | Yes | Event status: active, done, undone, or cancelled | |
| occurrenceDate | No | Occurrence date of a repeating event (ISO 8601 date or date-time) |
| Name | Required | Description |
|---|---|---|
| id | Yes | Event id |
| end | No | End in the user timezone (ISO 8601) |
| desc | No | Description |
| type | No | event is a timed item; task is a to-do without a duration |
| links | No | External calendar links when sync has finished |
| rrule | No | iCalendar RRULE string when the event repeats |
| start | No | Start in the user timezone (ISO 8601) |
| title | Yes | Event or task title |
| allDay | No | True when the event is a calendar date without a time |
| status | No | Event status: active, done, undone, or cancelled |
| location | No | Short place name |
| timezone | No | IANA timezone stored on the event |
| createdAt | No | When the event was created (ISO 8601) |
| updatedAt | No | When the event was last changed (ISO 8601) |
| calendarId | No | Calendar that owns the event |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral traits beyond annotations: it states that a missing id and an id owned by someone else both return not found, which clarifies error behavior. It also explains the effect of occurrenceDate on repeating tasksholistically. While annotations already declare idempotentHint and destructiveHint, the description adds valuable context about ownership and not-found semantics, enhancing the agent's understanding of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, at three sentences, with the most critical information (purpose and status values) front-loaded. It avoids repetition of schema details and includes only essential behavioral notes. Every sentence adds value, and the structure is clean and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for its complexity: it explains the purpose, the parameters' usage, and special behaviors (repeating events and not-found handling). The output schema exists, so return values are likely covered elsewhere, and the annotations provide safety hints. Nothing critical is missing for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all three parameters with 100% coverage, including the allowed enum values and the ISO 8601 format for occurrenceDate. The description adds meaning by explaining that 'status' maps to the enum and that occurrenceDate is specifically for repeating events to isolate a single day. This goes beyond the schema's basic descriptions, so it earns above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource ('Set status of an event owned by the authenticated user'), which defines the tool's purpose well. It also distinguishes from sibling tools like update_event by focusing solely on status changes. The allowed statuses are enumerated, leaving no ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly specifies when to use this tool (to change status) and provides a key conditional: 'For a repeating task pass occurrenceDate... so only that day changes.' It also implies when not to use it by focusing on status only, differentiating it from update_event for other fields. This is direct guidance that aids selection without needing to inspect siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an event owned by the authenticated user. Pass id plus any fields to change. start and end are ISO 8601 date-time with offset, or YYYY-MM-DD for an all-day event in the event timezone. A missing id and an id owned by someone else both return not found. waitSync defaults to true and waits for the external calendar so the response can include links; false responds immediately and links may be absent.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Event id owned by the authenticated user; any other id returns not found | |
| end | No | ISO 8601 date-time with offset, or YYYY-MM-DD for an all-day event in the event timezone | |
| desc | No | Description (up to 1000 characters) | |
| type | No | event is a timed item; task is a to-do without a duration | |
| rrule | No | iCalendar RRULE string for a repeating event | |
| start | No | ISO 8601 date-time with offset, or YYYY-MM-DD for an all-day event in the event timezone | |
| title | No | Event or task title (1–200 characters) | |
| allDay | No | True when start and end are calendar dates without a time | |
| status | No | Event status: active, done, undone, or cancelled | |
| location | No | Short place name | |
| timezone | No | IANA timezone of the event; stored as-is, not replaced by the user timezone | |
| waitSync | No | Wait for the external calendar so the response can include links; default true | |
| calendarId | No | Calendar that owns the event; omit for the default calendar |
| Name | Required | Description |
|---|---|---|
| id | Yes | Event id |
| end | No | End in the user timezone (ISO 8601) |
| desc | No | Description |
| type | No | event is a timed item; task is a to-do without a duration |
| links | No | External calendar links when sync has finished |
| rrule | No | iCalendar RRULE string when the event repeats |
| start | No | Start in the user timezone (ISO 8601) |
| title | Yes | Event or task title |
| allDay | No | True when the event is a calendar date without a time |
| status | No | Event status: active, done, undone, or cancelled |
| location | No | Short place name |
| timezone | No | IANA timezone stored on the event |
| createdAt | No | When the event was created (ISO 8601) |
| updatedAt | No | When the event was last changed (ISO 8601) |
| calendarId | No | Calendar that owns the event |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as a mutating, idempotent, non-destructive call. The description adds meaningful behavior beyond that: missing/foreign ids return not found, waitSync controls waiting for the external calendar and whether links are present, and date-time formats for all-day events. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four compact sentences, front-loaded with the core action, followed by the most decision-relevant details (date formats, error behavior, sync default). No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter mutation tool, the description covers the essential call contract: ownership restriction, patch semantics, date formats, not-found errors, and waitSync behavior. The output schema exists, so return-value details are not required here, and the parameter schema documents the remaining fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds the partial-update semantics ('Pass id plus any fields to change') and re-emphasizes the start/end ISO/all-day constraint and waitSync consequence, which adds some meaning beyond the schema even though much is duplicated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation ('Update'), a specific resource ('an event owned by the authenticated user'), and a clear contract ('Pass id plus any fields to change'). This is distinct from create_event, delete_event, and set_event_status because it scopes to owned events and field-level modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: to modify an existing event the caller owns. However, it never states alternatives or exclusions, such as choosing set_event_status for a status-only change or create_event for new events, leaving sibling routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
create_eventdelete_eventdelete_flowfind_conflictsget_eventget_flowsget_free_slotsget_holidaysget_meget_noteslist_calendarslist_holiday_countriesrender_agendarender_eventsave_flowsave_notesearch_eventsset_event_statusupdate_eventClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity – fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge – works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge – works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
