canvas_calendar_events

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real behavioral context beyond that: both range endpoints are inclusive, reading is scoped to the personal calendar by default, and raw mode returns Canvas's unmodified JSON with UTC times and HTML. It does not mention paging or result size limits, though the schema's page field covers that partially.

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 short sentences, front-loaded with the resource and date format, then mode selection, then scoping default, then the sibling alternative. No sentence repeats another and nothing is padding.

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 read-only list tool with full schema coverage and clear annotations, the description covers purpose, modes, scoping, and the alternative tool. The one gap is that with no output schema it never describes the shape of returned entries (the raw option hints at it but the default shape is undescribed).

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 a baseline of 3 is warranted; the description earns a point by explaining the default scoping consequence of omitting context_codes and by clarifying that both start and end days are included. It does not add syntax or format detail for 'page' or 'raw' beyond what the schema already 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 first sentence names the resource and scope precisely ('Calendar entries for a date range'), and the follow-up splits the two modes (event vs. assignment) with concrete examples such as lectures and office hours. It also names a sibling, canvas_planner, for the broader use case, so an agent can distinguish it without opening any 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?

It gives explicit selection rules: use type 'event' for lectures/office hours, 'assignment' for deadlines, omit context_codes for personal-only, and pass course_<id> codes for course entries. It also names an alternative (canvas_planner) and the condition that selects it ('everything due across all courses').

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