agenda

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.