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

With no annotations, the description carries the full behavioral burden. It does add valuable scope clarification that only *local cached* copies are deleted (implying server-side submissions survive), which is meaningful for a delete operation, but it omits reversibility, whether files re-download on demand, and any confirmation/permission requirements.

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, front-loaded sentence with no filler. Every word earns its place and the key scoping qualifier ('locally cached') appears before the object of deletion.

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?

An output schema exists, so return values need not be explained, and there are no parameters to document. The only real omission is the when-to-use context for a cache-clearing action; otherwise the definition is complete for a zero-arg tool.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% and the empty argument object matches the description's no-argument nature.

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 verb ('Delete') and a precise resource ('locally cached copies of student submission files'), so the action and scope are unambiguous. It is inherently distinct from the grading-oriented siblings, though it doesn't explicitly contrast itself with any of them.

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 explains what the tool does but never says when an agent should invoke it (e.g., after grading to free disk space, or to force a fresh re-download). No alternatives or preconditions are mentioned.

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

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

With no annotations, the description carries the full burden. It does add one genuinely useful piece of context – 'Does not touch Canvas', i.e. the operation is local to staging and has no external side effect – but it omits reversibility, behavior when nothing is staged, and error conditions for a destructive tool.

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?

Two short sentences, zero waste, with the destructive scope front-loaded and the side-effect boundary stated immediately after. Nothing needs trimming or reordering.

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?

An output schema exists, so return values need not be described, and the tool is a simple scoped delete. The main remaining gap is the absence of any error/edge-case behavior for a destructive operation with no annotations to fall back on.

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. It explains user_ids semantics ('all for the assignment, or only the given students'), which is the one non-obvious parameter, but gives no format or validation detail for course_id/assignment_id.

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 gives a specific verb+resource ('Delete staged grades') and clarifies the two deletion scopes (whole assignment vs. only given students), which cleanly separates it from siblings like post_staged_grades and stage_grade. It doesn't explicitly name those siblings, so it falls short of the top tier.

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?

Usage is only implied: an agent infers you call this when you want to undo staging. No when-not guidance and no explicit pointer to the alternative (post_staged_grades for committing), so the agent must reason about intent from the sibling list.

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

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

With no annotations, the description carries the full burden, and it does disclose a significant, non-obvious side effect: it downloads every submission's non-video attachments into the local cache. That is exactly the kind of operational cost an agent needs to know. It still omits whether the download is mandatory or skippable, whether server state changes, and the interaction with the clear_downloaded_files sibling.

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?

It is short and has no filler, but the structure is weak: it leads with a fragmentary noun phrase rather than the action, and the arguably more critical download behavior is buried in a second sentence without being framed as a caveat.

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?

An output schema exists, so return values need not be described. But for a tool that performs bulk network/disk downloads with zero annotations and two undocumented required parameters, the definition leaves key operational details (download cost, relation to clear_downloaded_files, scope) unaddressed, so it is only minimally complete.

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 for parameter meaning, and it provides nothing. The scope is only indirectly implied by the assignment/grading framing; neither course_id nor assignment_id is explained, nor is the assignment-level scope of the grouping stated.

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 identifies a distinctive capability no sibling offers: grouping students who submitted byte-identical files for consistent grading. However, it opens with a noun phrase ('Groups of students...') rather than a clear verb+resource, so the action being performed (detect/identify shared submissions) must be inferred. It is still unambiguous enough to distinguish from list_submissions or get_submission.

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 phrase 'so identical work can be graded consistently' implies a plagiarism/team-work detection use case, but there is no explicit when-to-use versus when-not-to-use guidance and no named alternative among the many grading siblings. Usage must be inferred from context.

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

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 usefully lists the assignment data included, but does not disclose permissions, error behavior, or whether the lookup is read-only beyond the implicit 'get' semantics.

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 front-loaded sentence that lists the included fields without filler. Every phrase contributes to understanding what the caller receives.

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 simple two-parameter getter with no output schema, the description adequately summarizes the returned content. However, it omits parameter guidance and any behavioral details needed when annotations and schema descriptions are absent.

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 has 0% description coverage, and the description does not mention course_id or assignment_id at all. The parameter names are fairly self-evident, but the description adds no semantic detail to compensate for the schema gap.

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 clearly identifies the resource and the useful content returned for grading: description, rubric, points, due dates, and late policy. It implies retrieving a single assignment, distinguishing it from list_assignments, but does not explicitly state the retrieval action or name the sibling.

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 phrase 'needed to grade an assignment' hints at the context, but there is no explicit guidance on when to use this tool versus list_assignments, get_submission, or get_grading_guidelines. No prerequisites or exclusions are provided.

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

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 says the guidelines are 'saved', implying persistence, but does not state that this is a read-only operation, what happens if the course has no guidelines, or whether permissions are required.

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 a single, tight sentence with no wasted words and is front-loaded with the resource being returned. It is appropriately sized for a simple getter, though the missing verb slightly reduces clarity.

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 simple one-parameter getter with no annotations and no output schema, the description states the resource and its scope at a basic level. It does not mention read-only semantics or parameter sourcing, leaving some gaps that the bare schema cannot fill.

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. It implies that the resource is scoped 'for a course', which loosely maps to course_id, but it adds no detail about the expected ID format, where to obtain it, or validation behavior. One required parameter remains essentially undocumented.

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 the resource (grading guidelines and late-penalty tiers for a course) but uses a noun phrase with no verb, so the retrieval action is only implied by the tool name. It is distinguishable from set_grading_guidelines by the get_ prefix, but the description itself does not state that distinction.

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 call this tool versus siblings such as list_grading_courses or set_grading_guidelines, and no prerequisites or context conditions are given. The agent must infer usage purely from the name.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return payload but omits the significant side effect that download_files defaults to true and that files are downloaded (implied by the sibling clear_downloaded_files), plus no note on auth or rate limits for external Google Docs fetches.

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 dense sentence with no filler; the content list is front-loaded. It is a sentence fragment rather than a full statement, but nothing in it is wasted.

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?

With no output schema, the description usefully enumerates what comes back (text, files, QR links, lateness, comments, grade), which is real value. However, for a 6-parameter tool with no annotations and 33% schema coverage, the missing parameter semantics and file-download side effect leave it incomplete.

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 33% (attempt and fetch_links documented, download_files not), so the description should compensate. The mention of 'linked Google Docs' loosely corresponds to fetch_links, but it says nothing about attempt selection or what download_files toggles, leaving half the parameters semantically opaque.

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 is a noun phrase enumerating return content rather than a verb+resource statement, but 'A student's submitted work' combined with the tool name makes the retrieval intent reasonably inferable. It does not distinguish itself from siblings like list_submissions or get_submission_images, so an agent cannot tell from the text alone when this single-submission fetch is the right pick.

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 when-to-use guidance, no mention of alternatives (list_submissions for bulk, get_submission_images for images only), and no prerequisites. The only hint at usage is the parenthetical listing of artifact types, which describes content rather than context of use.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose genuinely useful processing semantics: PDF pages containing pictures are rendered whole to preserve captions, embedded Word images and uploaded images pass through directly, and duplicates are skipped. However, it is silent on the behaviors an agent most needs — what happens when a submission has more images than max_images (truncation? ordering?), and whether this is a pure read with no side effects.

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?

Three short sentences, front-loaded with the core deliverable, followed by the rendering rules and the dedup note. Nearly every clause earns its place; the trailing 'as images' is mildly redundant with the leading noun list but costs little.

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?

With no output schema and no annotations, the description does a decent job of explaining the shape of the return (rendered page images vs. direct file images), which is the highest-value gap. But for a six-parameter tool with 17% schema coverage and an unmentioned max_images cap, the definition leaves an agent guessing about identifiers, attempt selection, and truncation behavior.

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 only 17% — just the `detail` enum is documented in the schema — yet the description mentions no parameter at all. It never explains course_id/assignment_id/user_id, what `attempt` selects, or that max_images defaults to 12 and caps at 30, so the reader cannot tell whether max_images silently truncates the set. It only loosely implies the source identifiers via 'a student's submitted files', which is insufficient compensation for the coverage gap.

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 concrete resource — screenshots, photos and scanned pages extracted from a student's submitted files — and implicitly states the retrieval verb via the name. It is clearly distinguishable from siblings like get_submission or list_submissions, which return text/metadata rather than rendered images. It stops short of an explicit 'retrieves X for Y' framing, but the resource and scope are unambiguous.

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 statement of when to reach for this tool versus get_submission, list_submissions, or open_in_speedgrader, nor any prerequisite or permission context. The reader must infer from the name alone that this is the image-oriented path. The only quasi-guidance is the duplicate-skipping note, which is behavior rather than usage selection.

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

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 mentions an aggregated output detail (how many submissions still need grading) but omits whether the operation is read-only, permission needs, pagination, or any constraints; the output schema likely covers return values, so this addition is marginal.

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, front-loaded sentence fragment with no wasted words. It is appropriately sized for a simple list tool, though the fragment form is slightly less clear than a full verb phrase.

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?

An output schema exists, so return values need not be explained. The description states the resource and an output dimension, which is the minimum for a simple list tool, but it leaves parameter semantics and usage context uncovered.

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 for both parameters. It only implies course scoping via 'in a course' and never explains the only_needing_grading filter, adding little meaning beyond the self-descriptive parameter names.

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 identifies the resource (assignments in a course) and a distinguishing output detail (submission grading counts), clearly separating it from sibling tools like get_assignment and list_submissions. It lacks an explicit verb, but the name supplies 'list' and the scope is unambiguous.

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 states what the tool returns but gives no explicit context for when to choose it over alternatives like get_assignment or list_submissions. Usage is only implied by the resource name, with no exclusions or prerequisites.

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

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

With no annotations, the description carries the full burden, and it does disclose the key behavioral trait: results are permission-filtered to grading-eligible courses. It says nothing about pagination, ordering, or what include_concluded does, so the disclosure is partial.

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 tight clause with no filler, and the most important qualifier (grading permission) is front-loaded. It is arguably too terse rather than too long.

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?

An output schema exists, so return values need not be described, and the tool is a simple read-only listing. The remaining gap is the undocumented include_concluded parameter and the absence of any workflow guidance, which leaves it only minimally complete.

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% and the sole parameter include_concluded (default false) is never mentioned in the description. The agent gets no explanation of what a 'concluded' course is or why it would be included.

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 identifies the exact resource returned: courses where the caller is a teacher/TA with grading permission. That scope distinction is meaningful, though it is a noun phrase with no verb and does not contrast itself with siblings like list_assignments or whoami.

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 statement of when to call this tool versus alternatives, nor any prerequisite or workflow position (e.g., 'call this first to get course IDs for list_assignments'). Usage is only inferable from the name.

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

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

With no annotations, the description carries the full burden, and it does disclose the key behavioral trait: the data is local/staged and unposted. However, it says nothing about read-only safety, whether the query filters by course or assignment, or what happens when nothing is staged.

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 economical sentence with no filler, and the distinguishing condition ('not yet posted to Canvas') is front-loaded. It reads as a fragment without a leading verb, which slightly weakens the framing.

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?

An output schema exists, so return format need not be described, but the optional filtering parameters and any usage context are left unexplained. Adequate for a simple read tool, but with clear gaps around filtering behavior.

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% and both parameters (course_id, assignment_id) are entirely undocumented. The description does not mention that results can be scoped by course or assignment, so it fails to compensate for the coverage gap beyond the self-explanatory parameter names.

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 clearly identifies the resource: grades and comments that are staged locally and not yet posted to Canvas. It implicitly differentiates from siblings like post_staged_grades and discard_staged by emphasizing the 'not yet posted' state, though it never states the verb 'list' explicitly.

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 explicit guidance on when to call this versus post_staged_grades, discard_staged, or stage_grade. An agent can infer it previews pending items, but neither prerequisites nor exclusions are stated.

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

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

No annotations are supplied, so the description carries the full burden. It never states that this is a read-only operation, whether results are paginated or scoped by role, or that the default filter silently limits output to ungraded work — a meaningful behavioral gap for a grading workflow.

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 front-loaded sentence with no filler or redundancy. It is appropriately short, though the brevity is partly under-specification rather than efficiency.

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?

With no annotations, no output schema, 0% parameter coverage, and an enum of seven mutually exclusive filter values, the definition leaves critical call-time decisions unexplained. It should at minimum document the filter values and the default's effect.

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%, and the description does not explain the seven filter enum values, the needs_grading default, or the meaning of course_id/assignment_id beyond their names. It mentions 'status' and 'lateness' loosely, but this does not compensate for three undocumented parameters.

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 the resource (submissions for an assignment) and what it returns (status, lateness, current score), which is enough to separate it from the singular get_submission sibling. It is a noun phrase rather than a verb statement, but the intent (listing) is unambiguous.

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 indication of when to use this versus get_submission, list_staged, or list_assignments, and no mention of the default filter (needs_grading) that governs which submissions come back. The agent must infer all routing decisions.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the side effect that this opens a browser UI rather than returning data, which is meaningful for an agent choosing a data-fetching sibling instead. However, it does not cover permissions, whether the action is read-only, failure modes, or what the caller gets back.

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 sentence with zero filler, front-loading the action and resource before the optional scope. Nothing is wasted or reordered.

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?

An output schema exists, so return values need not be explained. Still, for a side-effecting UI-launch tool with no annotations and undocumented parameters, the description should note prerequisites (e.g. relevance of course/assignment context, or that it depends on a logged-in browser session).

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 should compensate. It only clarifies user_id (targeting a specific student); course_id and assignment_id are left entirely to their bare titles, and the fact that user_id is optional is already expressed by its null default and non-required status in the schema.

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 verb and resource ("Open SpeedGrader") plus the destination ("in the user's browser") and an optional scope ("on a specific student"). An agent can tell this is distinct from the grading/post-staging siblings, though it never explicitly contrasts itself with any of them.

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 "optionally on a specific student" clause hints at when to supply user_id, but there is no explicit when-to-use guidance, no prerequisites (e.g. browser session/login state), and no named alternative among the sibling tools.

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

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 discloses one useful trait (grade is untouched) but omits the most consequential behavior: that confirm defaults to false and the call is preview-only until explicitly approved, as well as any statement about visibility, notification, or reversibility of a posted comment.

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 tight sentence with the scope constraint front-loaded and no wasted words. It is efficient, though its brevity contributes to the coverage gaps elsewhere rather than earning credit for completeness.

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 6-parameter tool with no annotations, no output schema, and 17% schema coverage, this one sentence is not enough. The preview/confirm safety flow and the meaning of group_comment are left for the agent to infer, which is risky for a tool that publishes user-visible content.

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 only 17% – just the confirm parameter. The description adds no meaning for course_id, assignment_id, user_id, text, or group_comment; notably group_comment is an undocumented boolean/null flag with no explanation anywhere. With such low coverage the description should compensate but does not.

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 gives a specific verb+resource ('Post a feedback comment on a student's submission') and adds a scoping clause ('without changing the grade') that distinguishes it from the grading siblings like stage_grade. It stops short of naming a sibling explicitly, so it does not reach 5.

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 'without changing the grade' clause implies this is the non-grading alternative to the stage_grade/post_staged_grades flow, but no sibling is named and no when-not condition is given. The critical two-step preview/confirm workflow is never mentioned, so usage is only implied.

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

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

No annotations are provided, so the description carries full burden; it usefully discloses the critical preview-vs-post gate and that results appear in SpeedGrader. It stops short of stating irreversibility, required teacher permissions, or what happens on partial failure.

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?

Two tight sentences with the mutation and its safety gate front-loaded; no waste.

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 mutation tool with no annotations and no output schema, the definition covers the core post/preview behavior but omits workflow relationships to sibling staging tools and consequence details an agent needs to invoke it safely.

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 coverage is only 50%, and the two undocumented parameters (course_id, assignment_id) are the required ones. The description restates confirm's preview behavior (already fully documented in the schema) and says nothing about user_ids, so it adds little beyond the schema.

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?

Clear specific verb+resource: it sends staged grades/comments to Canvas and notes they surface in SpeedGrader. An agent can tell this is the publish step for previously staged grades, but it never names sibling tools like stage_grade, list_staged, or discard_staged to differentiate the workflow position.

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 implies a two-phase workflow by noting that without confirm=true the call only previews, which is genuine usage guidance. However it never states when to prefer this over siblings (stage_grade/discard_staged) or the precondition that grades must already be staged.

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

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

With no annotations, the description carries the full burden. It usefully discloses that data is 'stored only on this computer' (local-only persistence), which is real behavioral context, but it omits whether saving replaces vs. merges existing guidelines, what happens to unfilled fields, and any auth requirements.

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 front-loaded sentence with no filler; the storage caveat is parenthetically tucked in after the core action. Every clause earns its place.

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?

There is no output schema and no annotations, so the description should do more work. It covers purpose and storage locality but leaves key mutation semantics (overwrite behavior, partial-update behavior, failure modes) unaddressed despite being a save/create-style tool.

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 coverage is 67%, and the schema itself richly documents guidelines and late_penalty_tiers (including the LateTier shape with an example-scale hint). The description adds only the framing 'manual late-penalty scale' and does not mention the required course_id, so it is roughly at baseline.

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 verb ('Save') and resource ('grading guidelines and a manual late-penalty scale') scoped 'for a course', which clearly distinguishes it from the read-oriented sibling get_grading_guidelines. It does not name any sibling explicitly, but the write-vs-read split is inferable.

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?

Usage is implied by 'Save ... for a course', but there is no explicit when-to-use guidance, no mention of the get_grading_guidelines counterpart, and no stated preconditions or exclusions. The agent must infer the workflow context.

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

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

With no annotations, the description carries the full burden and does disclose the most important trait: this is a local staging write with no Canvas side effect, requiring a separate post step. It does not address overwrite/re-stage behavior for the same user/assignment, permissions, or idempotency.

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?

Two short sentences, zero waste, with the surprising behavior (local only) front-loaded ahead of the workflow routing.

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 13-parameter grading tool with no annotations and no output schema, the description is thin. It never explains what a staged entry contains, how breakdown/grade/extra_credit/late_penalty interact, or what list_staged will show, though the schema descriptions cover much of the field-level semantics.

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 69% and the description adds no parameter-level detail beyond naming 'grade/comment' — precedence between 'grade' and 'breakdown', the auto late deduction vs. manual 'late_penalty', and the effect of 'group_comment' are left entirely to the schema. Baseline 3 is appropriate since the schema does most of the work.

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?

Specific verb (save/stage) plus resource (grade/comment) and a critical scope qualifier: 'nothing is sent to Canvas.' An agent can immediately tell this apart from post_staged_grades without opening the schema.

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?

Explicitly routes the agent through the workflow: review with list_staged, send with post_staged_grades. It names the follow-up alternative and its condition, but offers no when-not-to-use guidance (e.g. post_comment for standalone comments, or that staged grades can be discarded).

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

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, and it discloses essentially nothing about side effects, permissions, or whether the call is safe/non-mutating. For a trivial zero-arg lookup this is a modest gap, but identity tools can leak auth/instance context that is worth calling out.

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?

It is a single short sentence with no padding, which is good, but it is under-specified rather than genuinely concise — the fragment lacks a subject/verb and spends its one clause on the return value instead of the action.

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?

With no output schema and no annotations, the description does at least indicate what the call yields (account and instance), which is the essential payload. However it omits the return format and any indication of when the result matters, leaving it minimally adequate for a diagnostic tool.

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 tool takes zero parameters, so the baseline is 4. There are no arguments whose semantics the description could clarify or confuse.

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 the resource it exposes (the Canvas account and instance) but is a noun-phrase fragment with no verb, so it reads as a label rather than a statement of what the tool does. An agent can infer it returns identity/connection info, but the purpose is only implied. It is distinguishable from all grading-related siblings, which helps.

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 when-to-use guidance, no mention that it takes no arguments, and no comparison to alternatives. The only guidance is implicit from the name 'whoami'. Nothing tells the agent whether this is a setup/verification step or a routine call.

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