Get My Submission Feedback

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

Annotations declare readOnlyHint=true and openWorldHint=true, and the description adds substantial behavioral context beyond that: the filtering rule (non-self comments only), the omission of submissions without feedback, the cross-course scan behavior with per-course error tolerance, the sort order (most-recent-feedback-first), and the best-effort author role classification. This is rich, non-obvious behavior that an agent needs to know.

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 dense but every sentence earns its place: it defines the core filter, the cross-course behavior, the sort order, and the role-labeling caveat. It is front-loaded with the primary purpose and then layers the important behavioral details. No filler or repetition of schema content.

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 2 optional parameters, 100% schema coverage, and no output schema, the description covers everything an agent needs: what is returned, what is excluded, how errors are handled, sort order, and the meaning of the role field. The absence of an output schema is mitigated by the detailed description of the result set and the courses_failed field.

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 the schema already documents both parameters. The description adds value by explaining the consequence of omitting course_id (scan all active courses) and the meaning of unread_only (Canvas read_status), which goes slightly beyond the schema's bare descriptions. A 4 is appropriate because the description reinforces and enriches the parameter semantics without being redundant.

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 states a specific verb ('List') and resource ('the authenticated student's own submissions that carry feedback comments from an instructor or a peer reviewer'), and precisely distinguishes what counts as feedback (non-self comments) from what does not (self comments). It clearly differentiates from siblings like list_submissions, get_submission, and list_submission_comments_needing_attention by scoping to the authenticated student's own submissions with feedback.

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?

The description gives explicit usage context: omit course_id to scan all active courses, and explains the error-handling behavior (courses that error are skipped and reported in courses_failed). It also clarifies the best-effort role labeling, which helps an agent decide when this tool is appropriate versus alternatives. While it doesn't name sibling alternatives explicitly, the scope is so clearly defined that an agent can infer when to use it.

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