Get My Submission Feedback

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

Annotations declare readOnlyHint and openWorldHint, but the description adds substantial behavioral detail beyond those: self-comments are excluded, submissions with no non-self comments are omitted, failing courses are reported in courses_failed, results are sorted most-recent-feedback-first, and teacher/peer role labeling is best-effort with a specific rule. No contradiction with annotations.

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 sentences, each carrying distinct information: core filtering rule, cross-course scanning with error handling, sort order, and role-labeling limitation. There is no redundant or filler content, and the main purpose is front-loaded.

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?

Given the absence of an output schema, the description covers the essential behavior: filtering semantics, cross-course error handling, sorting, and role labeling limitations. It does not specify the exact shape of returned submission items or pagination, but the information provided is sufficient for an agent to invoke the tool correctly and interpret results.

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?

Both parameters are fully described in the input schema (100% coverage), so the description adds little parameter-specific meaning. It reiterates the course_id omission behavior already in the schema and does not introduce new details for unread_only beyond the schema's existing description.

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 and resource: 'List the authenticated student's own submissions that carry feedback comments from an instructor or a peer reviewer.' It clearly differentiates this tool from siblings like get_my_submissions by focusing only on submissions with non-self feedback and explicitly excluding self-comments.

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?

Provides clear context for when to use the tool: omit course_id to scan all active courses, use unread_only to filter unopened submissions, and understand that per-course errors are skipped. However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks explicit exclusion guidance.

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