Telegram Calendar MCP

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, and the description adds real behavioral context: timezone is stored as-is and not replaced by the user timezone, and waitSync=true blocks until the external calendar syncs so the response can carry links while false returns immediately with links possibly absent. It omits auth requirements, external-calendar side effects, and rate limits, so not 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?

Front-loaded with the required field and format rules, and roughly 110 words for a 12-parameter tool is proportionate. It is dense but each clause maps to a parameter concern; the parameter list reads as one long run-on rather than scannable structure, keeping it out of 5 territory.

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?

An output schema exists, so return values need not be explained, and annotations cover safety. The description supplies the format/default/sync semantics an agent needs to call it correctly, but it never mentions calendarId or allDay despite them being caller-relevant inputs, leaving a small completeness gap.

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 12 parameters with formats, enums, and defaults. The description largely restates the schema (ISO 8601 formats, title 1–200 chars, status/type values) and adds only marginal nuance, so the baseline 3 is correct.

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 and resource: "Create an event or task for the authenticated user." Combined with sibling tool names (update_event, set_event_status, delete_event, save_note/save_flow), an agent can immediately tell this is the creation path for calendar items as opposed to mutation or deletion.

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?

Usage is only implied. The description never states when to pick this tool over save_flow, save_note, or update_event, and it does not explain the event-vs-task choice beyond naming the two enum values. The one genuine decision aid is the waitSync trade-off ("true waits for the external calendar... false responds immediately and links may be absent"), which tells the agent when to trade latency for links.

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 flag destructive=true and idempotent=true, and the description adds real value on top: it spells out the blast radius of each mode (whole series vs one date vs that date onward) and documents the not-found behavior for missing or non-owned ids, which prevents leaking other users' event existence. It does not discuss auth scopes or recovery/undo.

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 with no filler, front-loading the delete action and ownership scope before the mode semantics and error behavior. Every sentence carries distinct information.

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?

An output schema exists, so return values need no explanation. For a destructive three-parameter tool, the description covers scope, modes, required date semantics and error behavior, leaving no material gap 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not carry: that mode defaults to 'all' and that occurrenceDate is effectively required for occurrence/following. The ISO 8601 format note reinforces the schema's anyOf.

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 verb (delete) plus resource (event) and scopes it to the authenticated user's own events, which separates it cleanly from delete_flow and from the various get_/render_/update_event 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?

Gives clear conditional guidance for the three modes, including which one is the default and which require occurrenceDate, so the agent can pick a mode without guessing. It stops short of explicitly naming alternatives (e.g., set_event_status for cancellation instead of deletion) or stating when not to delete.

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, 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.

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

Annotations already declare the safe-read, idempotent, closed-world profile, so the lower bar applies. The description still adds real behavior: default window of ±31 days, a hard 366-day cap, per-calendar scoping via calendarId, and the touching-endpoint rule that defines what counts as a conflict.

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?

Five dense sentences with no filler; the core purpose leads, and defaults, constraints, and edge-case semantics follow in priority order. Every sentence carries information an agent needs.

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?

An output schema exists, so return values need no explanation. With 5 parameters, 0 required, all described at 100% coverage, and the description adding defaults, caps, and the boundary rule, nothing needed to call this correctly 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 coverage is 100%, so the baseline is 3. The description goes beyond it by restating the ±31-day defaults and the 366-day window constraint inline, and by tying start/end to the pre-create check, giving the parameters workflow meaning the schema alone does not.

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 verb and resource: 'Find overlapping events in the authenticated user calendar.' It also pins down the conflict semantics ('Intervals that only touch at an endpoint are not a conflict'), which lets an agent distinguish this from get_free_slots or search_events without opening a 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?

Gives two concrete usage modes: scanning a from/to window for existing overlaps, and checking a proposed start/end slot 'before create_event.' That routing to create_event is explicit. It stops short of naming when to prefer get_free_slots instead, so no exclusions are stated.

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 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.

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.

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so the bar is lower. The description adds real context beyond them: default window of ±31 days, a hard 366-day limit, and that all slot bounds and dayStart/dayEnd are interpreted in the user's timezone.

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 dense sentences, front-loaded with the purpose before constraints. Nothing is padding, though the parameter sentences are somewhat list-like and could be tightened.

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?

An output schema exists, so return format need not be described. All five parameters, their defaults, the window cap, and the timezone model are covered, leaving only the absence of routing guidance to siblings as a gap.

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 every parameter including defaults, ranges, and inclusive-date semantics. The description largely restates those (ISO 8601, default 30, range 5–1440) and adds only the timezone framing, so baseline 3 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?

States a specific verb and resource: 'Find unoccupied time windows in the authenticated user calendar.' This is clearly distinct from search_events or find_conflicts by implication, but the description never names those siblings explicitly to reinforce the distinction.

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 defaults (±31 days, duration 30) and the 366-day cap imply when the tool is applicable, but there is no explicit when-to-use/when-not guidance or reference to alternatives such as find_conflicts. Usage is inferable rather than stated.

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 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.

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.

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds genuine behavioral context beyond that: the default ±31-day window, the hard 366-day cap, and the output date format. It does not discuss pagination or result-size limits.

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 tight sentences with no filler: the purpose and scope come first, followed by defaults/limits and the output date format. Every sentence carries actionable information.

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 an output schema present, the description need not explain return values, yet it still states the result date format as a convenience. Combined with annotations covering safety and a fully documented 2-parameter schema, nothing needed to call the tool correctly 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 both parameters are fully documented in the schema, so the baseline is 3. The description restates the ISO 8601 format, defaults and the 366-day constraint that the schema already specifies, adding only the summarized result date format (YYYY-MM-DD).

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") and scopes it to the authenticated user within a time window, so the agent can distinguish it from calendar tools like get_event or find_conflicts. It does not explicitly name its write counterpart save_note, so differentiation is by category rather than by direct sibling reference.

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?

Usage is implied by the resource and scope (fetching the user's own daily notes over a range), and the defaults/limits give practical context. However, there is no explicit when-to-use or when-not-to-use statement, and no routing to alternatives such as search_events or save_note.

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 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.

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.

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.

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.

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

Annotations already declare readOnly=false, openWorld=false, idempotent=true and destructive=true, so the safety profile is covered structurally. The description adds only the scoping fact that the mark applies to the authenticated user; it says nothing about what destructiveHint actually destroys here (e.g. overwriting an existing mark for that date), so it adds some but not rich behavioral context.

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, front-loaded sentences with zero filler: the action and scope come first, followed by the two argument formats. Nothing is redundant or padded.

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 two-parameter mutation tool with a full schema, complete annotations, and an output schema (so return values need not be described), the description is close to sufficient. The only material gap is that a destructive-marking operation never explains what an existing entry for the same date would be replaced by.

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 both parameters are already documented, and the description merely restates them ('date is YYYY-MM-DD', 'event is flowstart or flowend'). No syntax, mutex, or dating-rule semantics are added beyond the schema, so the baseline 3 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?

States a specific verb and resource: 'Mark a menstrual-cycle start or end for the authenticated user', which is unambiguous about what the tool writes. It does not, however, differentiate itself from the related siblings delete_flow or get_flows, so an agent must infer the boundary from names alone.

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?

There is no when-to-use guidance, no prerequisite or ordering information (e.g. whether a start must precede an end, or how this interacts with get_flows), and no named alternative. The description is purely declarative.

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 flag destructiveHint=true and readOnlyHint=false, and the description earns credit by disclosing the actual destructive path (clearing text deletes the note) plus the surprising return behavior (an empty note is still returned for that date). This is real context beyond the annotation flags, though it does not cover permission requirements or rate limits.

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 action, then one compact sentence per parameter, with the destructive edge case saved for last. A couple of phrases duplicate the schema descriptions, so it is efficient but not flawless.

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 mutation tool with an output schema and safety annotations, the description covers everything an agent needs: required date format, size limit, append semantics, and the destructive empty-text path. Return-value explanation is correctly omitted since the output schema exists.

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 four parameters, and the description mostly restates them verbatim (date format, 1000-char limit, emoji, append). The only genuinely additive semantics is the deletion side effect of an empty text value, which supports the baseline 3 rather than more.

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 verb+resource ('Create or replace a daily note') and scopes it to 'the authenticated user', which is enough to separate it from read-only siblings like get_notes. It never names an alternative tool explicitly, so it stops short of the top band.

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 explains the replace-vs-append mode and the delete-by-clearing case, which implies usage, but it never says when to prefer this over get_notes or another note tool. No explicit when/when-not guidance or prerequisites are given.

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 readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds real behavioral detail beyond them: the hard 366-day window limit, the ±31-day default, and that result dates are rendered in the user timezone. It omits auth/permission and pagination behavior, so not 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?

Four dense sentences, front-loaded with the core list operation before qualification details. Slight overlap with the schema on defaults and the 366-day cap, but nothing is wasted.

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 an output schema present, rich annotations, and 100% schema coverage, the description only needs to add operational context — and it does: window limits, defaults, filter behavior, and timezone semantics. Nothing essential to correct invocation 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 coverage is 100%, so both the defaults, ISO-8601 handling, and case-insensitive substring match are already documented per-parameter. The description largely restates the schema, adding only the result-timezone note, which earns the baseline 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?

States a specific verb+resource (list events) plus scope: time window, authenticated user, and inclusion of subscribed/shared calendars. That scope clause distinguishes it from get_event (single event) and makes the listing intent 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 supplies useful operating context (defaults ±31 days, 366-day cap, filter semantics) but never says when to prefer this over siblings such as find_conflicts, get_free_slots, or render_agenda. Usage is implied rather than routed.

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, so the safety profile is covered. The description adds genuinely new context: the authenticated-ownership requirement and the fact that both a missing id and a foreign-owned id collapse to the same 'not found' response, which is valuable for error handling.

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, front-loaded with purpose, then the status vocabulary, the repeating-event rule, and error semantics. No filler, though the status values repeat the schema enum and could be dropped.

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?

An output schema exists, so return values need not be described. Combined with annotations covering the mutation profile, the description covers ownership/auth scope, the conditional occurrence parameter, and error behavior — everything an agent needs to invoke it 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 coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining the effect of occurrenceDate ('so only that day changes') rather than merely restating its type. The status enum is duplicated from the schema, which adds no new information.

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 verb (Set status) and resource (event owned by the authenticated user), plus the exact enum of resulting states. It is clear what it does, though it never contrasts itself with sibling update_event, which could plausibly also alter status.

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 conditional guidance for the optional parameter: pass occurrenceDate for a repeating task so only that day changes. It also scopes usage to events owned by the caller. It stops short of naming an alternative (e.g. update_event) or stating when this tool should not be used.

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 destructive=true, idempotent=true, and openWorld=false, so the safety profile is covered. The description adds real context beyond that: the not-found behavior for missing or non-owned ids, and the waitSync latency/response tradeoff (false responds immediately and links may be absent).

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, front-loaded with purpose and partial-update usage, then date formatting, error behavior, and the sync flag. No repetition of the title and no filler.

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?

An output schema exists, so return values need not be explained. For a 13-parameter mutation tool with destructive/idempotent annotations, the description covers the ownership constraint, the not-found failure mode, and the blocking-vs-immediate sync behavior; only replacement-vs-merge semantics for omitted fields are left implicit.

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 baseline is 3. The description largely restates schema content (start/end ISO 8601 format, waitSync default), though it does sharpen waitSync by stating the immediate-response case may lack links; it says nothing about calendarId, timezone, or rrule semantics.

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 verb and resource ('Update an event') and adds the ownership scope ('owned by the authenticated user'), which is the key differentiator from siblings like create_event or get_event. It stops short of naming an alternative tool outright, but the resource is 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?

'Pass id plus any fields to change' establishes partial-update usage, which is genuinely useful guidance. However, it never addresses when to use this versus set_event_status (which overlaps on the status field) or delete_event, and gives no prerequisites or exclusions.

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