Smart Calendars AI

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.

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.

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.

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.

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.

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.

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

Adds substantial context beyond annotations: billing ('Free within feed allowances'), no automatic monitoring enrollment, retry semantics for request_id, and the critical caveat that publication.status is file preparation, not subscription access. Slightly diluted by lengthy URL-handoff presentation rules that concern sharing UI rather than this tool's own execution, and it never states the response shape for the created object.

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?

Purpose and prerequisites are correctly front-loaded, but roughly half the text is a policy block on sharing links (subscription_open_url, subscription_options_url, manage_url, filtered_subscription) that is only tangentially about creating a feed. Several sentences are UI-script instructions rather than tool semantics, which blunts the signal.

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?

No output schema exists, and the description does name the fields an agent will encounter (publication.status, distribution_ready, returned URLs) and warns not to treat unpublished feeds as subscribable. It stops short of describing the actual response payload or failure modes, so it is strong but not fully self-contained for a mutation tool.

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?

With only 40% schema description coverage the description must compensate, and it does so for request_id (opaque, reuse on retries) and implicitly for events ('extract the schedule yourself'). However, 'activate', 'title', and 'description' parameters get no clarification, and the required 'events' array structure is only touched via the extraction instruction rather than explained.

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?

Opens with a specific verb+resource ('Create and activate a subscription calendar from structured events') and adds a key prerequisite ('Extract the schedule yourself first'). It distinguishes itself from reading siblings by pointing to get_feed_status for current availability, though it does not contrast with apply_feed_changes or reactivate_feed, which are the closest alternatives.

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?

Gives explicit negative guidance for unsupported actions ('explain the limitation without reading feeds or substituting an edit') and tells the agent to gather events itself rather than assume monitoring. Clear context, but no explicit statement of when to prefer apply_feed_changes or reactivate_feed over creating a new feed.

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

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 genuine value by clarifying the blast radius: events are preserved and editing windows are not reset, and user confirmation is required before interrupting access. That softens an otherwise alarming destructiveHint. It does not cover auth needs or what the mutation returns, which keeps it from a 5.

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 purpose is front-loaded, but the body is a wall of text dominated by topics irrelevant to deactivating a feed: subscription_open_url handoffs, webcal link preservation, mailbox limitations, and ICS explanations. Every sentence does not earn its place in this tool's definition.

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 three-parameter mutation with full schema coverage and no output schema, the essentials are present (confirmation requirement, side-effect scope, revision safety implied by the schema). However, it omits what the tool returns and how the new status is reported, while spending most of its length on tangential subscription-sharing guidance.

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 all three parameters (feed_id, expected_revision, request_id) are fully documented in the schema, so the baseline is 3. The description adds nothing about parameter usage — no mention of how to obtain feed_id or expected_revision.

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?

Opens with a specific verb+resource ('Deactivate a feed') and immediately distinguishes it from adjacent behaviors ('without deleting events or resetting editing windows'). It also distinguishes it from get_feed_status and publication.status, though it never names its most obvious sibling, reactivate_feed.

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 gives one real usage rule ('Confirm the user wants to interrupt subscription access') and points to get_feed_status for current availability, which is useful. But these are buried in a long paragraph of unrelated mailbox/ICS guidance, and there is no explicit guidance on when to reactivate vs. simply re-fetch.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds substantive behavior beyond that: facets describe the whole published active feed regardless of filters or pagination, and nonempty filters return filtered_subscription with matching_event_count and unmatched_filter_values. It also discloses that filtering never mutates or clones anything. It does not state auth or rate-limit characteristics.

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?

Front-loaded with the core purpose, but the body sprawls across filtering semantics, unsupported mailbox/source-monitoring scenarios, and a long block of chat-UI link-handoff instructions ('Open in calendar app', 'Calendar options', subscription_webcal_url fallbacks) that dilutes the actionable core. Several sentences earn their place; the presentation/URL guidance is disproportionately large relative to the read operation.

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 10 parameters, a nested filter object and no output schema, the description covers return shape reasonably (available_facets, filter_coverage, filtered_subscription, subscription URLs). However it omits date formats for from/to, default/maximum pagination behavior, and what the 'internal revision' value looks like, which an agent needs before calling 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 only 20%, so the description must compensate, and it partially does: 'Event IDs, external keys, dates, removal state and pagination narrow only the read, never the subscription' clarifies the semantics of five parameters at once. But it says nothing about the from/to date format, the limit ceiling of 250, or offset behavior beyond 'pagination', leaving key calling details to the bare 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?

Opens with a specific verb+resource: read events and the internal revision for a feed, with the stated motivation of reading before editing. It implicitly separates this read tool from the mutating siblings (apply_feed_changes, deactivate_feed) but never names them, so sibling differentiation is by inference rather than explicit statement.

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?

Gives real when-to-use guidance: request include_facets first; before proposing cancellations from a revised PDF, read every page of the unfiltered feed. It also states when NOT to use the tool ('For requests solely for those unsupported actions, explain the limitation without reading feeds'), though it never contrasts against get_feed_status or list_feeds.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds critical behavioral context: the call does not refresh or charge, cannot access mailboxes or start monitoring, and must never invent or rewrite returned URLs. It also warns that opening a link does not confirm a subscription and that inactive feeds must not be presented as ready.

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 purpose is front-loaded, but the description is long and includes extensive subscription-link handoff instructions that are only tangentially related to reading status. Many sentences are useful, but the overall length is disproportionate for a one-parameter read tool.

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 compensates well for the lack of an output schema by naming returned fields and URL properties, and it thoroughly covers scope limitations and behavioral constraints. The main gap is the undocumented feed_id parameter, which prevents a 5.

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 single parameter feed_id has no description in the schema (0% coverage), and the tool description never explains what feed_id is, how to obtain it, or that it is a UUID. Referencing 'the feed's' is insufficient to compensate for the schema gap.

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 first sentence gives a specific verb ('Read') and enumerates the exact status fields returned: last update, subscription availability, editing access, and monitoring status. It does not explicitly differentiate from the sibling get_feed tool, so it falls short of a 5.

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 states when not to use the tool: it cannot access mailboxes or start monitoring, and unsupported requests should be handled with an explanation rather than by reading feeds. It also gives explicit instructions for offering subscription handoff links. It lacks guidance on when to use get_feed instead, which prevents a 5.

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

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

The description adds substantial behavior beyond the read-only annotations: only counted feeds use a slot, page length is not account usage, deactivation interrupts subscription access, and the returned URLs must be used exactly. It also explains link-handling behavior, subscription confirmation, and inactive/unpublished feed caveats.

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 purpose is front-loaded, but the description runs far beyond what is needed for a simple two-parameter list tool. Large portions about unsupported mailbox requests, general ICS explanations, and link presentation are verbose and better handled in broader instructions.

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?

There is no output schema, so the description usefully covers return-object semantics such as subscription URLs, manage_url, filtered_subscription links, and inactive-feed warnings. It remains incomplete on pagination parameters, but otherwise gives an agent enough context to use the listing output 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 0%, and the description never explains the limit or offset parameters. It mentions that page length is not account usage, which hints at pagination, but gives no parameter-level meaning, defaults, or constraints.

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: list the connected account's feeds, management links, and active-feed allowance. It also clarifies the Smart Calendars scope. However, it does not explicitly distinguish this tool from sibling feed-retrieval tools such as get_feed.

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 strong when-to-use and when-not-to-use guidance, including unsupported mailbox and monitoring requests and the need to ask before deactivating a counted feed. It does not, however, mention when to prefer get_feed or other sibling tools for feed-level retrieval.

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

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

Beyond the annotations, the description discloses important behavior: reactivation is free within account allowances, does not reset the original editing window or modify events, and publication.status reflects calendar-file preparation rather than subscription access. It also adds caution that opening a link does not confirm a subscription and that inactive feeds should not be presented as ready.

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 purpose is front-loaded in the first sentence, but the description runs long and includes extensive sharing-link handoff guidance that is only tangentially related to reactivating a feed. For a three-parameter mutation tool, many sentences do not earn their place in this specific definition.

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 key context an agent needs: purpose, side-effect boundaries, status-field caveats, unsupported actions, and subscription readiness warnings. With annotations and a fully described schema, it is mostly complete, though it does not clearly describe what a successful reactivate_feed call returns.

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 feed_id, request_id, and expected_revision are already well documented in the schema. The description does not add meaningful parameter-level semantics beyond a vague reference to 'the reported revision', 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 first sentence names a specific verb and resource: reactivating an existing feed, with a scope note about account allowances. It is reasonably distinguishable from deactivate_feed by the word reactivate, but it does not explicitly contrast itself with apply_feed_changes or create_feed.

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 routing guidance, including using get_feed_status for current availability and checking distribution_ready at the reported revision. It also explicitly excludes unsupported mailbox and source-monitoring requests, though it does not state when to prefer reactivate_feed over apply_feed_changes or deactivate_feed.

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