Get My Activity Stream

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

The readOnlyHint=true annotation is consistent, and the description adds genuinely non-obvious behavior beyond it: reading the feed does not mark anything read, items are newest-first, results are grouped by kind, and the feed is capped to active courses. That last point and the read-state guarantee are things an agent could not derive from annotations or 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 core identity and the kind list, followed by two useful constraints. Slight redundancy: 'across all active courses' is restated at the end as 'Canvas limits this feed to your active courses,' which costs a sentence for a point already made.

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 no-output-schema, all-optional-parameter read tool, this covers purpose, scope, ordering and read-state side effects, which is enough to call it correctly. The one remaining gap is the shape of the individual feed items (what fields each entry carries beyond the preview text), which the preview_chars/include_summary parameters only gesture at.

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%, with all four parameters including ranges, defaults and enum values documented inline. The description adds only indirect hints ('grouped by kind' loosely maps to include_summary; preview implies preview_chars), so baseline 3 is appropriate — the schema does the heavy lifting.

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 resource and scope: 'Your recent Canvas activity across all active courses, grouped by kind,' and identifies it concretely as the dashboard 'Recent Activity' feed with the five item kinds enumerated. This makes it clearly distinguishable from the granular siblings (list_my_announcements, get_unread_count, list_conversations) that cover single sources rather than an aggregated feed.

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 defines the domain well: use this for a cross-course recent-activity digest, and it explicitly bounds what is NOT included ('Group activity and inbox messages not tied to a course are not included'). However, it never names the sibling tools an agent should reach for instead (e.g. list_conversations for group inbox messages, list_my_announcements for a single kind), so routing is inferred rather than stated.

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