Skip to main content
Glama

Smart Calendars AI

Save a calendar revision

apply_feed_changes
DestructiveIdempotent

Save one revision to one existing calendar feed owned by the connected account. Submit one fixed-schema change set with up to 250 event changes and/or a feed title or description change; all stored calendar changes commit together in one transaction, or none are saved. The input schema declares every supported change: add creates an event; update changes selected fields or uses reset_fields to restore saved field baselines; delete marks an existing event canceled without permanently erasing it; restore reinstates that same event and may update selected fields; feed_patch changes only the calendar title or description. No dynamic operation discovery, fetched schemas, arbitrary commands or arbitrary endpoints are supported. First use dry_run=true to validate and preview the change set without saving, advancing the revision or spending credits. Show the returned before/after changes and any billing quote, not an invented summary. Obtain approval for a proposed schedule revision before saving it with dry_run=false. Save with the returned preview_receipt and the identical feed_id, expected_revision, request_id, operations and feed_patch. The receipt binds that validated preview, not user consent. Changed proposals or expired previews require a new preview and approval; revision conflicts require reading the feed again before preparing a new preview. Preserve omitted events/fields. For revised PDFs/documents, read the complete unfiltered feed before cancellations, preserve unrelated events and manual fields, and ask when an event match is uncertain. Update matched event IDs; a duplicate add is not an update. Use set with null to clear nullable fields; reset_fields restores saved baselines, not empty values. Use the last read expected_revision to prevent overwriting concurrent changes. On uncertain save retry the identical request_id and payload, including the original preview_receipt, never a new one. Subscribers save without billing prompts. If billing requires one credit, show the deduction and balance and obtain explicit user authorization before setting confirm_credit_charge=true; this explicit authorization may be added after preview. Default automations must not authorize credit spending. publication.status reports calendar-file preparation, not subscription access. Check distribution_ready for access at the reported revision; use get_feed_status for current availability. Preview proposals are recoverable for up to one hour; expired drafts are removed automatically. Previewing does not write calendar events or advance their revision. Display the returned feed_id and request_id alongside the preview summary so this exact proposal can be recovered. If the receipt or exact proposal was lost, call this same tool with only feed_id, the original request_id, dry_run=true and recover_preview=true. Do not reconstruct missing changes from memory, guess a key or choose a latest preview. Recovery returns the original unexpired preview and exact save_arguments without extending its expiry, saving or spending credits. Show that recovered preview and obtain fresh approval before submitting its save_arguments unchanged; confirm_credit_charge remains false unless the user explicitly authorizes the current quoted charge. Recovery is not consent. If recovery returns saved=true, those changes were already saved: report that result and stop; do not submit a new save. If no recoverable preview remains, read the feed, prepare a new preview with a new request_id and obtain approval. Never silently substitute a changed proposal. These tools manage Smart Calendars feeds only; they cannot access mailboxes or start source monitoring, scheduled PDF checks or document refreshes. For requests solely for those unsupported actions, explain the limitation without reading feeds or substituting an edit. For unsupported mailbox requests, offer to work with schedule content the user chooses to provide instead. General ICS explanations need no account access. When sharing a feed or filtered_subscription with distribution_ready=true, offer "Open in calendar app" using that object’s HTTPS subscription_open_url (it redirects to webcal), and "Calendar options" using its subscription_options_url for Apple/default, Google, Outlook and copy-link choices. Retain subscription_url as a copyable HTTPS fallback. Prefer these HTTPS handoff links over putting subscription_webcal_url directly in chat, because some clients do not preserve clickable webcal links. If a handoff URL is absent, use the HTTPS subscription_url and dashboard subscription controls instead. Offer "View or edit" using the feed’s manage_url. For a filtered selection use the nested filtered_subscription links, not the unfiltered feed links. Use the returned URLs exactly; never invent or rewrite their host, path or token. Opening a link does not confirm a subscription; the user must confirm in their calendar app. Do not present inactive or unpublished feeds as ready to subscribe.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
dry_runNo
feed_idYesFeed identity returned by a previous feed tool; used to address the selected calendar only.
feed_patchNo
operationsNo
request_idYesGenerate an opaque key for this save and reuse it unchanged for retries, to prevent duplicate changes. Not a user identifier, chat/session ID, or telemetry. Do not include personal data.
preview_receiptNoOpaque receipt returned by a successful dry_run=true preview. Required when saving with dry_run=false. Return it unchanged with the same feed, revision, request_id and proposed changes. It is not user approval.
recover_previewNoRead the exact temporarily stored preview after losing its receipt or proposal. Requires dry_run=true and only feed_id and the original request_id; omit all other arguments. Does not save, extend expiry or authorize a charge. Show the recovered preview and obtain fresh approval before saving. Never guess a request ID or select a latest preview.
expected_revisionNoLast read feed revision; prevents overwriting concurrent edits.
confirm_credit_chargeNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses transactional all-or-none commit behavior, that delete marks events canceled rather than permanently erasing them, idempotency via request_id, preview receipt semantics, billing credit authorization requirements, revision-conflict handling, and preview expiry/recovery behavior. The destructiveHint=true annotation is consistent with the described update/delete/mutation behavior, so 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.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and schema behavior, but it becomes an extremely long, dense wall of procedural instructions with repeated approval/recovery warnings. It also includes tangential subscription-link guidance that may be relevant to feed sharing generally but is not tightly focused on saving a revision, making the text harder to scan than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex mutation tool with no output schema, the description covers the critical operational context: transactional saving, preview/approval flow, credit charging, revision conflicts, retry idempotency, preview recovery, and unsupported-action handling. An agent has enough information to invoke it safely and correctly in normal and edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 56%, the description adds substantial meaning: it explains that operations supports add/update/delete/restore, that update changes only supplied fields, that reset_fields restores saved baselines rather than clearing fields, that null clears nullable fields, that duplicate add is not an update, and how request_id, preview_receipt, recover_preview, expected_revision, and confirm_credit_charge are used. This compensates well for schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: "Save one revision to one existing calendar feed owned by the connected account." It clearly scopes the tool to existing feeds and revision saving, implicitly distinguishing it from create_feed and other siblings, and later reiterates that these tools manage Smart Calendars feeds only.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance: first call with dry_run=true to validate and preview, obtain approval before dry_run=false, use recovery only when receipt or proposal is lost, and retry identical payload on uncertain save. It also names unsupported actions and tells the agent not to read feeds or substitute edits for those requests.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources