Upcoming deadlines

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

With no annotations, the description carries full burden and it does a thorough job: it discloses the default 14-day window, the role-filter semantics, that personal/site events are always kept, the exact return fields, the timezone (Taipei time), the sort order (soonest first), and that credentials come from MCP settings rather than from the agent. This level of behavioral detail is rare and clearly exceeds what a simple 'list' description would provide.

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 front-loaded with the core purpose in the first sentence, then layers role-filtering, output format, and credentials in a logical sequence. Every sentence contributes a distinct fact; there is no filler or repetition. It is longer than a typical tool description but justified by the density of useful information (timezone, sort, fields).

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?

There is no output schema, so the description must explain the return format itself—it does, listing all fields and their meaning (due in Taipei time). It also covers sorting, default filtering, and authentication source. For a read-only 'list' tool this is complete; an agent could call it correctly without needing to guess any behavior.

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% (both parameters are described), so the baseline is 3. The description adds value beyond the schema by explaining the semantic difference of include_all_role (including teacher/TA courses) and reiterating the default for days. It also mentions the role field in the output, which indirectly clarifies what the parameter means for the response. This moves it above the schema-only baseline.

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 pair ('List the student's upcoming action events') and scopes it precisely (across courses, within a time window). It also asserts 'This is the best what's due soon overview,' which signals its intended niche relative to the sibling tools (list_assignments, get_notifications, etc.), so an agent can distinguish it without opening their schemas.

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 clearly explains when to use it ('best what's due soon overview') and how the role filter changes the result set ('By default only events from courses where you are a STUDENT... set include_all_role true to also include teacher/TA courses'). It does not explicitly name alternatives or state when NOT to use it, but the purpose is clear enough that an agent can reasonably choose it over siblings that list specific resource types.

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