Comment on Submission

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the scope for additional disclosure is limited. The description adds that the comment is added/appended, which is consistent with the annotation and confirms the write behavior, but it does not clarify subtle consequences: whether the comment appears to students, whether duplicate comments can accumulate, or whether edit/removal is possible. 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?

A single, well-constructed sentence with no wasted words; the action is front-loaded and mirrors the tool's name without reading as a tautology. Each word is doing something useful—excluding only the 'usage guidance'—but the sentence is so short that it leaves space for richer guidance.

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 complexity of a write operation with no output schema and no example of a typical call, the description is adequate to know the rough invocation but incomplete on what a successful response looks like, whether an ID must point specifically to a student, and what authoritative failure modes exist. Its constraints, annotations, and schema coverage lower the burden substantially, leaving this at a minimum-viable completeness.

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?

The input schema describes all four parameters, with 100% coverage, so the baseline is 3 even though the description itself adds no parameter detail. The description identifies the purpose (adding a text comment) but says nothing about the relationship among course_id, assignment_id, and user_id or validation rules beyond what the schema's own labels already imply.

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 names a specific verb ('Add'), a resource ('submission'), and the subject matter ('text comment'), making the action easy to distinguish from siblings like grade_submission or post_discussion_entry. However, it does not explicitly signal any sibling it is not, so an agent must infer that no other tool in the list handles this file.

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?

There is no guidance on when to use this tool versus alternatives such as grade_submission, list_submission_comments_needing_attention, post_discussion_entry, or send_conversation. A single sentence clarifying that comments are distinct from grades and discussion entries would have satisfied this dimension.

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