bulk_reminders

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

No annotations exist, so the description carries the full burden and does well: it discloses the dry-run default, the batch cap, and the implicit skipping of completed reminders. It stops short of stating whether delete is reversible, whether any permission/auth constraint applies, or how partial failures are reported.

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-loads the most important fact (SAFE BY DEFAULT preview behavior) before the action list and filter syntax. It is dense but every clause carries operational information; a minor redundancy is the trailing 'set_priority needs set_priority', which reads as awkward phrasing rather than waste.

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, no-annotation, no-output-schema mutation tool, the description covers selection, action-specific requirements, limits, and the commit/preview model. It omits what the preview response contains and whether ids can be combined with filters to narrow a set, which are the main remaining gaps.

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

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

Schema description coverage is 0% and there are 15 parameters, so the description must compensate entirely — and it does: it documents the action enum values, priority enum values, date formats (YYYY-MM-DD inclusive), shift_days semantics ('keeps the time'), title_contains, include_completed, and the filter-vs-ids relationship.

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

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

Opens with a specific verb+resource ('Change many reminders at once') and enumerates all eight supported actions, which cleanly separates it from the single-reminder siblings (update_reminder, complete_reminder, delete_reminder) 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?

Explicitly states the safe-by-default workflow (apply=False previews, apply=True commits), how to select targets (ids exact vs filters), and the guardrails: at least one selector required, max 50 per call, completed items skipped unless include_completed=True. Also names per-action prerequisites (move needs to_list, reschedule needs exactly one of shift_days/new_due).

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