list_submissions

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

No annotations are provided, so the description carries the full behavioral burden. It implies 'submission state and grades' are returned but does not disclose auth requirements, pagination behavior, whether the limit truncates or throttles, or the default user scoping beyond what is in the schema. For a read tool with zero annotation coverage, this is a significant gap.

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?

One-line purpose followed by a structured Args block. Efficient, though the purpose sentence omits an explicit verb and relies on the name for action. No wasted sentences.

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?

Covers parameters well and states the return content at a high level, but for a read tool with no annotations and no output schema, it omits auth requirements, pagination/limit semantics, and error behavior. Adequate but with clear gaps.

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 0%, so the description must compensate, and it does: user_id explains the 'me' default, numeric id/email forms, and the teacher-only '-' value; limit is defined as maximum submissions; course_id and coursework_id are traced to their source tools. This meaningfully exceeds the bare schema titles.

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: submission state and grades for one assignment. The verb is implicit ('list') matching the name. It clearly distinguishes itself from sibling list_* tools by naming the assignment-submissions domain, though it does not explicitly contrast with list_students or list_coursework.

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?

No explicit when-to-use or when-not-to-use guidance. It implies teacher/student context via the '-' value but does not state that listing all students requires teacher privileges as a selection condition, nor does it point to alternatives.

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