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

With no annotations, the description carries the full burden and does substantial work: recurrence expansion rules, sorting/grouping by day, all-day events not shifted by tz, floating times interpreted in tz, and cancelled events hidden unless include_cancelled=true. The notable omission is the `limit` parameter (default 300) and what happens when the result set exceeds it, which is exactly the kind of silent truncation an agent needs to know about.

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 operation and its most distinctive behavior before any parameter detail, then a compact per-parameter block. Dense but every clause carries real information; the only cost is that the tz sentence packs reading semantics, display semantics, and header output together.

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 formatting need not be explained, and the description adds exactly the right behavioral context for a recurrence-aware agenda tool. The remaining gap is result-set capping via the undocumented `limit` of 300, which matters for an agent querying wide date ranges.

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%, so the description must compensate, and it does for five of six parameters: accepted start/end formats with optional Z or offset, date-only `end` being day-inclusive, tz as IANA zone used both for reading input and rendering output, calendars drawn from calendar_overview with an all-calendars default, and the cancelled flag. Only `limit` is left entirely undefined in both schema and description.

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 with scope: 'Show every event occurrence between start and end, sorted, grouped by day,' plus the key promise that recurring events are 'already expanded (RRULE, EXDATE, RDATE and modified instances applied).' That expansion promise is what separates it from a plain event search, though it never explicitly names siblings like search_events or next_occurrences.

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 rather than stated: the tool is for retrieving a full agenda over a range, and it references calendar_overview as the source of valid calendar names, which is a useful prerequisite hint. However, there is no explicit when-to-use versus search_events, next_occurrences, or export_agenda_markdown, and no exclusions 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?

With no annotations, the description carries the burden of behavioral disclosure. It states that failed files and skipped events are reported with reasons, which is useful transparency beyond a simple listing. It does not discuss permissions or rate limits, but for a zero-parameter read-only overview tool the disclosed behavior is strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two sentences and front-loads the core purpose before giving the critical 'call this first' instruction. It is dense but every clause adds useful information about return content or usage, with no wasted wording.

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 annotations, and an output schema, the description provides everything needed to call it correctly. It explains scope, return contents, error reporting behavior, and ordering relative to other tools, so the agent is not missing required context.

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 parameter semantics are not a major concern and the baseline is 4. The mention of `calendars` and `calendar` parameters in other tools adds useful context about how the output is consumed, even though this tool itself has an empty schema.

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

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

The description uses a specific verb and resource: it lists calendar files visible to the server. It also names the exact fields returned for each file, including event counts, recurring series, date span, and time zones, which clearly distinguishes it from sibling tools like agenda and search_events.

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 explicitly says 'Call this first,' giving a clear ordering instruction. It also explains why: the file names it prints are accepted by the `calendars` and `calendar` parameters of other tools, which directly ties usage to downstream actions.

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?

With no annotations, the description carries the full burden and does so thoroughly: it discloses the default non-destructive write to '<file>.new', the in_place override, dry_run behavior, output_file constraints, and byte-for-byte preservation of unrelated content. It also flags that attendees are recorded but never sent and that no VTIMEZONE block is added.

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?

Dense but well organized, with a labeled SAFETY block and front-loaded core behavior. Every sentence carries information, though the parameter walkthrough is packed tightly enough that it reads as a reference dump rather than prose.

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 15-parameter mutation tool with no annotations, the description covers the write semantics, safety model, and format rules an agent needs. An output schema exists, so return values need not be explained, and nothing critical 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 0%, so the description must compensate, and it explains the non-obvious parameters: calendar naming rules, start format semantics, end inclusivity, tz storage behavior, rrule syntax, status and transp value sets, and the in_place/output_file/dry_run trio. Only summary, location, and description are left to obvious inference.

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 ('Add an event to a calendar file') plus a concrete side effect (UID and DTSTAMP generated). It also points to calendar_overview for the file name, which separates it from the read-only siblings like agenda and search_events.

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: date-only start makes an all-day event, datetime start requires end or duration_minutes, and calendar names come from calendar_overview. It does not explicitly say to use update_event for existing events, but the create-vs-modify split is strongly implied by the sibling set.

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?

No annotations were supplied, so the description carries the full burden and does so well: it states the original file is never modified unless in_place=true, the default output is '<file>.new', output_file must not already exist, dry_run writes nothing and only shows the patch, and all unrelated content (other events, VTIMEZONE, unknown properties) is preserved byte for byte. That is precisely the mutation-safety and side-effect profile an agent cannot infer from the schema.

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 primary action, then a clearly labeled SAFETY block, which is good structure for a destructive tool. A few clauses run long, notably the parenthetical about modified instances and the EXDATE sentence, but no sentence is 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?

For a destructive mutation with no annotations and seven parameters, the description supplies the safety model, default output path, overwrite constraint and preservation guarantee; with an output schema present it need not describe the return value. Only the undocumented 'calendar' parameter keeps it from being flawless.

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%, so the description must compensate, and it does for six of the seven parameters: event_uid, occurrence (with format and all-day variant), tz as the zone used to read the occurrence, dry_run, in_place and output_file. The 'calendar' parameter is never mentioned at all, and tz's role beyond occurrence parsing is not spelled out, leaving a real 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?

States a specific verb and resource (delete an event, addressed by UID) and immediately disambiguates the two deletion modes: whole recurring series with its modified instances vs. a single occurrence converted to an EXDATE. That distinction is exactly what an agent needs to pick the right behavior, and it separates the tool cleanly from update_event/create_event in the sibling list.

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 concrete when-to guidance for the ambiguous case: pass occurrence='2026-03-09T09:00' with a start value read in tz, or a bare date for an all-day event, and an EXDATE is added instead of removing the series. It also explains when to set in_place, output_file and dry_run. It stops short of naming a sibling alternative (e.g. update_event for property edits), so routing guidance is implied rather than explicit.

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?

With no annotations, the description carries the full burden and does well: it discloses the return value, that output_file writes a new .md file under the server directory, and critically that an existing file is never overwritten. It omits what happens when calendars is left unset, any permission or size limits, and whether behaviour varies with tz beyond labelling.

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, front-loaded with what is rendered and in what shape, then the return, then the optional side effect. No restatement of the name 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?

For a simple four-parameter export tool with an output schema covering the return shape, the description is nearly sufficient. The one real gap is the undocumented calendars parameter, which an agent cannot reason about from schema alone at 0% coverage.

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%, so the description must compensate, and it does for three of four parameters: week_start gets a concrete date example and a scope (seven days from it), output_file gets a location constraint and a non-destructive guarantee, and tz is linked to how times are labelled. The calendars parameter receives no explanation at all, which keeps this from a 5.

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 (render) and a precise resource (seven days starting at week_start) plus the output format (Markdown with one heading per day and a bullet per event). This makes it distinguishable from siblings like agenda or calendar_overview by output format, though it never explicitly names or contrasts those 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?

Usage is implied rather than stated: the Markdown framing suggests use when a formatted export is wanted instead of a conversational listing, but there is no explicit when-to-use vs. when-not guidance or reference to the sibling tools that overlap with this capability.

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?

With no annotations provided, the description carries the behavioral burden and does well by disclosing non-obvious semantics: back-to-back events are not conflicts, cancelled events are ignored, and all-day/free events are excluded unless flags are set. It does not cover read-only safety, limit/pagination behavior, or ordering, leaving some behavioral gaps.

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 tightly written and front-loads the core purpose before giving edge-case rules. Every sentence adds useful conflict-detection context, with no redundant wording or unnecessary preamble.

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 output schema exists, so return values need not be described, and the description covers key conflict-detection behavior well. However, for a 7-parameter tool with 0% schema description coverage and no annotations, important parameter semantics such as calendars and limit remain unaddressed, leaving the definition only minimally complete.

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%, so the description must compensate for parameter meaning. It explains include_all_day and include_transparent behavior and implies start/end range filtering, but it only says 'start/end/tz as in agenda,' which is not self-contained, and it leaves limit and calendars semantics unexplained.

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: list pairs of events whose times overlap in a range, including across calendars. This is clearly distinct from sibling tools such as agenda, search_events, and find_free_time, so an agent can identify the tool's role without opening the schema.

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

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

The description implies when the tool is useful by defining conflict pairs and edge cases, but it does not explicitly say when to use this tool versus alternatives like find_free_time or agenda. The inclusion and exclusion rules provide context, but there is no direct when-to-use or when-not-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?

With no annotations, the description carries the behavioral burden and does well: it explains maximal free blocks, buffer padding, busy-event semantics, all-day and transparent event handling, and DST-safe working hours. It does not cover authentication, rate limits, or pagination behavior, 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 description is dense and front-loaded, with the core behavior stated first and parameter semantics following. Every sentence adds useful information, though the long paragraph could be structured more scannably.

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 an 11-parameter tool with no annotations and an output schema, the description covers the essential scheduling semantics and return-block behavior. It still omits details for calendars and limit, and does not mention operational constraints such as auth or rate limits.

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%, so the description must compensate, and it explains most parameters: start/end/tz, working_hours format, days, buffer_minutes, duration_minutes, include_all_day, and include_transparent. It leaves calendars and limit under-explained, so it is strong but not complete.

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: find free slots across calendars, with a clear scope of working hours and duration. It does not explicitly differentiate itself from sibling tools such as find_conflicts or agenda, 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?

Usage is implied by the tool name and description: use it to locate free time blocks. However, there is no explicit when-to-use guidance, no when-not-to-use guidance, and no named alternatives among the sibling tools.

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?

With no annotations, the description carries the burden and does disclose meaningful behavior: modified instances and removed dates are applied, and `after` defaults to now. It does not state error behavior for unknown UIDs or how timezone conversion interacts with the results, which keeps it short of 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?

Three tight sentences, front-loaded with the core behavior, then the use case, then the disambiguation note. No filler and nothing repeated from the schema.

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 the description covers the recurrence-expansion semantics and UID sourcing well. The only real gap is the unexplained `tz` parameter, which matters for a date-producing 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?

Schema description coverage is 0%, so the description must compensate, and it does for most parameters: n (the count), after (default now), calendar (file name, only needed when the UID exists in several files), and event_uid (sourced from agenda/search_events). The `tz` parameter is never mentioned, leaving one of five undocumented.

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: the next n occurrences of one event identified by UID, at or after a given point. It also distinguishes itself from the sibling list tools (agenda, search_events) by being the recurrence-expansion tool rather than a listing tool.

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 a clear use case ('check what a recurrence rule really produces, e.g. last Friday of the month') and tells the agent where UIDs come from (agenda and search_events). It lacks an explicit when-not or a named alternative for the case where the agent just wants a plain listing, but the context is otherwise unambiguous.

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?

With no annotations, the description carries the burden well: it discloses the AND-across-filters rule, case-insensitivity, which fields query/regex scan, and that ^/$ anchor to each field rather than the whole string. It also discloses a real output-shape difference between the two date modes. Undocumented: pagination/limit behavior, the calendars filter, and confirmation that this is a read-only operation.

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 AND rule, then a compact per-parameter glossary, then the mode distinction — no filler sentences. The parameter prose runs together in dense fragments without separators, which costs a little scannability but wastes no words.

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 9-param search tool with an output schema (so return values need not be described), the definition covers the query language, filter fields, timezone handling, and result-shape switching adequately. The gap is the unexplained `limit` and `calendars` parameters, which an agent cannot safely set from this text alone.

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 0%, so the description must compensate, and it does for 7 of 9 params — query, attendee ("part of an attendee/organizer email or name"), location, regex, start, end, and tz all get real semantics beyond their bare names. `limit` and `calendars` receive no explanation anywhere, keeping it below a 5.

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?

Opening sentence gives a specific verb+resource ("Find events by text") and the AND-filter semantics. It implicitly contrasts with the agenda sibling ("expanded, like agenda"), but never explicitly names which sibling to choose for which lookup, so it stops 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 splits two operating modes — bare listing of events/series without start/end vs expanded occurrences when both are supplied — which is genuine conditional guidance. However it never says when to prefer this over next_occurrences or calendar_overview, and offers no exclusions or prerequisites.

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?

With no annotations, the description carries the full burden and does so: it states the original file is never modified unless in_place=true, that output_file must not exist yet, that dry_run writes nothing, and that unrelated content is preserved byte for byte. It also discloses side effects beyond the requested change (DTSTAMP refresh, SEQUENCE increment) — exactly the kind of hidden mutation an agent needs to know before calling.

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 dense paragraphs split cleanly between semantics and safety, with the mutation-scope rule front-loaded. Every sentence carries distinct information — field update rules, side effects, file-write guarantees — and there is no restatement of the tool name or 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-value explanation is not required, and the description covers the risky parts (file writes, dry run, series scope) thoroughly. The remaining gaps are the undocumented duration_minutes parameter and the accepted values for status/transp/rrule, which an agent must guess.

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 0%, so the description must compensate and largely does: it defines the empty-string removal convention, the replace-not-merge semantics of attendees, the start-without-end behavior, the tz default, and the roles of in_place, output_file, dry_run, and calendar. It leaves duration_minutes entirely unmentioned and gives no value hints for status, transp, or rrule format, so some of the 16 parameters remain opaque.

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 ('Change fields of one event') and immediately scopes it ('the whole series if it recurs'), which distinguishes it from create_event and delete_event. The sibling set contains no other mutator of an existing event, so no further differentiation is needed.

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 usage rules: only passed fields change, empty strings remove fields, attendees replaces the list, and single-instance modification 'is not supported', which routes the agent away from an unsupported case. It also defers to create_event for all-day conventions. It stops short of naming alternatives for the unsupported case or stating prerequisites such as needing the file to be writable.

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