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

Annotations only declare idempotentHint=false and destructiveHint=false, so the description correctly implies a non-destructive write. The item_type → required-field matrix is genuine behavioral context, but it says nothing about permission requirements, position defaults, ordering effects, or duplicate-add behavior for a 12-parameter mutation.

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 action and followed by the highest-value conditional logic. No filler and nothing redundant at the sentence level.

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 the core conditional-required logic for a 12-param mutation, which is the main trap. However, it omits external_url for ExternalUrl items (it names only title), doesn't mention return value or how the created item is identified, and gives no permission/mutation side-effects — meaningful gaps with no output schema.

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 100% and every property already carries a description that states exactly the same conditional requirements (title, page_url, content_id), so the description largely restates the schema. Baseline 3 applies; no added syntax, formats, or cross-parameter rules beyond what the schema says.

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 ('Add an item to a module'), which is unambiguous and immediately distinguishable from read siblings like list_module_items. It does not explicitly contrast with update_module_item, but the verb makes the distinction clear.

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 guidance on when to use this versus update_module_item or create_module, no prerequisites (e.g. teacher/admin permission, module must exist), and no notes on what happens if the same content is added twice. The conditional-required clause is parameter guidance, not usage guidance.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description should add analysis behavior: what dimensions are scored, whether it scans all peer reviews in the assignment, and what the result looks like. It adds none of that, offering only a restatement of the name.

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 short sentence with no filler, front-loaded with the action. Its brevity is a virtue here, though it tilts toward 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?

There is no output schema and no explanation of what the analysis yields, how it scopes to the assignment's peer reviews, or what custom criteria do. For a four-parameter analytical tool with many similar siblings, that leaves too much unspecified.

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 four parameters are already documented in the schema and a baseline of 3 applies. The description contributes no extra meaning for analysis_criteria (custom JSON criteria) or generate_report, but it is not required to under the coverage rule.

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 verb+resource ("Analyze ... peer review comments") is identifiable, but "quality and content" is vague about what is actually produced. It also does nothing to distinguish it from closely overlapping siblings such as identify_problematic_peer_reviews, get_peer_review_comments, and generate_peer_review_report.

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 use this tool, no prerequisites, and no mention of the many sibling tools that handle adjacent peer-review tasks. The agent must infer the choice from the name alone.

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?

Annotations only declare idempotentHint=false and destructiveHint=false; the description adds genuine value by disclosing the failure mode (no submission record → refusal) and a non-obvious side-effect guarantee ("never creates one"). It does not cover permission requirements or what happens on a duplicate assignment.

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 sentences with zero waste; the action is front-loaded and the caveat follows. Nothing is repeated from the title or schema.

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 four-required-parameter mutation with no output schema, the definition covers purpose, precondition, and failure behavior. Minor gaps remain: no statement of required permissions or of the expected result of a successful assignment (Canvas peer review object).

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 all four parameters are already documented in the schema; baseline 3 applies. The description only indirectly clarifies reviewee_id semantics through the submission-record precondition and adds nothing about formats for course_identifier or 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?

States a specific verb and resource: "Manually assign a peer review to a student for a specific assignment." The word "Manually" distinguishes it from auto-assignment flows and from the read-only peer review siblings (list_peer_reviews, get_peer_review_assignments), though it never names an alternative 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?

Gives a concrete precondition/exclusion: refuses when the reviewee has no submission record on the assignment. That is a real when-not condition rather than implied usage. It stops short of naming an alternative path (e.g., using a bulk/auto assignment tool) for the refusal case.

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?

Annotations declare destructiveHint=true and idempotentHint=false, but the description does not disclose what is destructive about the operation, whether an existing rubric association is replaced, or what permissions are required. With annotations covering only the safety signals, the description adds essentially no behavioral context for a high-stakes mutation.

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, front-loaded sentence with no wasted words. It is efficient, though its brevity contributes to gaps in usage and behavioral guidance rather than being a structural flaw.

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 five-parameter destructive mutation with no output schema and only minimal annotations, the description is too thin. It omits prerequisites, the effect of associating an already-associated rubric, and the interaction between purpose and use_for_grading, leaving the agent under-informed.

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 all five parameters, including purpose and use_for_grading, are already documented in the schema. The description does not add meaning beyond the schema, which is acceptable at the baseline for fully described 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 states a clear verb and resource: associating an existing rubric with an assignment. It is specific enough to distinguish this from rubric creation or retrieval, but it does not explicitly differentiate from siblings such as create_rubric, update_rubric, or list_rubrics.

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 offers no guidance on when to use this tool versus alternatives like create_rubric or update_rubric. It says 'existing rubric', which implies the rubric must already exist, but it does not state prerequisites, when association is appropriate, or what happens if an association already exists.

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?

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds valuable context that deletions are 'Permanent' with a caveat about Canvas recycle-bin retention. It stops short of describing error behavior or permission requirements, but the added permanence nuance is meaningful beyond structured data.

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, front-loaded with the core action and workflow. Every sentence earns its place: the first defines the operation and two-step process, the second clarifies permanence and a key 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?

For a destructive bulk operation with full schema coverage and annotations, the description covers the critical workflow and permanence caveat. It omits some finer points like error handling or output shape, but those are either covered by schema parameters (e.g., stop_on_error) or unnecessary for a delete tool with no output schema.

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 all five parameters are fully documented in the input schema. The description reiterates 'by ID' and 'confirm with the token' but adds no syntax, format, or edge-case details beyond what the schema already provides.

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 ('Delete'), resource ('announcements'), and scope ('multiple ... by ID'), immediately distinguishing it from single-delete or criteria-based siblings. An agent can tell this is for bulk deletion by explicit IDs 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?

It clearly outlines the two-step workflow ('preview first, then confirm with the token'), which is essential for correct invocation. However, it does not explicitly name when to use this tool versus siblings like delete_announcement_with_confirmation or delete_announcements_by_criteria, leaving some inference to the agent.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is partly carried structurally. The description adds the two grading modes but does not warn about partial-failure behavior across concurrent batches, permission requirements, or irreversibility, which matters for a destructive bulk write.

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, front-loaded with the action and scope. 'Efficiently with concurrent processing' is mild filler since concurrency is already exposed via max_concurrent, but nothing is bloated.

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 destructive, non-idempotent bulk mutation with a nested object parameter and no output schema, the description says nothing about what is returned, how partial failures are reported, or the dry_run validation workflow. The schema documents parameters well, but the operational contract of a bulk concurrent write is left unstated.

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 100% and the grades parameter carries extensive warnings about comment appending and visibility, so the schema does the heavy lifting. The description's mention of rubric vs point modes loosely maps to the grades dict shape but adds no format or syntax detail 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?

The description names a specific verb ('grade') and resource ('multiple submissions') with batch scope, and notes both rubric-based and point-based modes. It is clearly distinguishable from single-submission tools like grade_with_rubric, though it never names a sibling 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?

'Grade multiple submissions efficiently' implies batch usage but gives no conditions for choosing this over grade_with_rubric or grade_with_rubric vs simple grading, no prerequisites (permissions, submission state), and no when-not guidance. The agent must infer everything about routing.

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?

The annotations already declare destructiveHint=true and idempotentHint=false. The description adds useful behavioral scope beyond that by limiting the tool to settings only and warning that names and content cannot be changed, though it does not explain the destructive nature of bulk settings overwrites or partial-failure behavior.

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 three short sentences, front-loads the main purpose, immediately states the key limitation, and then names the relevant alternative. Every sentence 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?

For a bulk destructive settings tool with a fully described input schema and no output schema, the description covers purpose, scope limits, and the content-editing alternative. It could say more about destructive bulk behavior or what happens on partial failures, but the essential selection context is present.

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 page_urls, published, editing_roles, notify_of_update, and course_identifier. The description adds no parameter-level detail beyond the multi-page scope, so it appropriately sits at the baseline when the schema does the heavy lifting.

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 and resource: updating settings for multiple pages at once. It also distinguishes this tool from edit_page_content, which is the sibling for changing page bodies, so an agent can identify its role 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?

The description makes the multi-page scope explicit and gives a clear exclusion: it cannot rename pages or change page content, and directs body changes to edit_page_content. It does not explicitly contrast with update_page_settings for single-page updates, so it stops just short of full alternative routing.

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?

The description discloses rich behavioral details beyond the readOnlyHint annotation: it reproduces Canvas grade arithmetic, handles drop rules and excused/omitted work, compares against Canvas's own score, flags disagreements, applies hypothetical scores, computes target percentages, and notes which grading scheme is used. It also explicitly states 'Nothing is changed in Canvas,' which is consistent with readOnlyHint=true.

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 front-loaded with the primary purpose. It remains focused on relevant behavior, though the parenthetical list of grade-arithmetic rules makes it longer than strictly necessary.

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 tool's complexity, the description is complete: it explains the grading logic, optional what-if behavior, target calculation, grading-scheme handling, and the read-only nature. With no output schema, it adequately describes what the output includes and how discrepancies are surfaced.

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 all four parameters thoroughly. The description reinforces concepts like what-if scores and target calculation but does not add parameter-level semantics such as formats or constraints beyond what the schema provides.

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 uses a specific verb and resource: 'Recompute your course grade, try what-if scores, and find what you need on remaining work.' It clearly describes scenario calculation rather than simple grade retrieval, but it does not explicitly name or distinguish itself from siblings such as get_my_course_grades.

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 clear usage context: recomputing grades, trying what-if scores, and calculating the percentage needed on remaining work. It does not state when not to use the tool or explicitly point to alternatives, but the intended use cases are clear.

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?

The description adds substantial behavioral context beyond the readOnlyHint annotation: required roster-admin token rights, an INDETERMINATE result instead of a false negative, and strict limits on returned data. These are exactly the operational caveats an agent needs before calling a roster-membership checker.

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 purpose is front-loaded, followed by the permission/INDETERMINATE caveat, the return limitations, and the role default. Although longer than a minimal description, every paragraph addresses a distinct operational concern and no sentence is filler.

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 a read-only tool with no output schema, the description is complete enough: it states the limited return shape, the permission dependency, the indeterminate outcome, and the self-versus-other routing. Nothing needed for correct invocation appears to be missing.

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 already 100%, so the baseline is 3. The description still adds useful semantics for the role parameter, especially the default student scope, the fact that a NO may name another role, and the use of role="any"; it adds less beyond the schema for net_id and course_identifier.

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?

Starts with a precise verb and resource: checking whether a specific campus login ID is enrolled in a course. It explicitly contrasts the externally-supplied person with the caller, which distinguishes it from get_my_enrollments without requiring schema inspection.

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 self-enrollment questions to get_my_enrollments and explains the important role-scoping condition, including when to pass role="any". It also states the permission precondition and the INDETERMINATE outcome when roster-admin rights are missing.

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?

The description goes well beyond the annotations (idempotentHint=false, destructiveHint=false): it discloses that publication is a side effect of creation, that enrolled users may be notified, that deleting does not recall delivered notifications, and that the call requires a Canvas posting permission. These are exactly the irreversible-consequence facts an agent needs before invoking a mutation.

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 core action and its most consequential side effect (immediate publish + notifications) are front-loaded, and every sentence carries information. The final sentence about not re-posting through discussion tools is a bit long for the point it makes, but it is not filler.

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 output schema and no readOnly hint, the description covers permissions, timing, notification fallout, and failure behavior thoroughly. The one gap is that it never indicates what the call returns (e.g. the created announcement identifier), which would matter for follow-up calls such as update or delete.

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 100%, so the baseline is 3. The description earns an extra point by explaining the semantics of delayed_post_at — omitting it means immediate posting — which the schema's 'ISO 8601 datetime to schedule posting' does not make as explicit in terms of side effects.

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 opening sentence states a specific verb pair and resource: 'Create and publish a course announcement.' The closing sentence distinguishes it from the discussion-tool siblings by explaining why content is not re-posted there, so an agent can tell it apart from create_discussion_topic without opening either 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?

It gives clear conditions for the two posting modes (immediate without delayed_post_at, scheduled with it) and explicitly rules out the fallback of re-posting via discussion tools. What it does not name is a when-not-to-use case or a direct comparison with create_discussion_topic when the user genuinely wants an announcement-topic hybrid.

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?

Annotations declare idempotentHint=false and destructiveHint=false, but notably omit readOnlyHint, so the description carries real weight and adds none of it. It does not warn that retrying will create duplicate assignments, does not state that the assignment starts unpublished by default, and says nothing about permissions or side effects on the gradebook.

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 short sentence with no filler, so it is concise and front-loaded. The low absolute size reflects under-specification rather than padding, but as far as structure goes it wastes nothing.

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 14-parameter mutation with no output schema and no readOnly hint, one sentence is far too thin. An agent gets no picture of what the created assignment returns, what happens with unpublished defaults, or how course_identifier is resolved when it can be a code or a Canvas ID.

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% and each of the 14 parameters carries its own description (formats, enums for grading_type and submission_types, defaults), so the schema does the heavy lifting. The description adds no meaning beyond it, which is the expected baseline of 3 here.

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 sentence identifies a verb and resource ('Create a new assignment') and adds scope ('in a course'), so the basic purpose is clear. However, it is close to a restatement of the name/title and does nothing to separate it from sibling mutations such as update_assignment or delete_assignment_with_confirmation.

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 versus update_assignment, when creation should be avoided, or what prerequisites (instructor role, course manage permission) are needed. The agent must infer all of this from the name alone.

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?

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds valuable context beyond that by explaining the preview-then-confirm safety flow and the short-lived token. It does not state what exactly is destroyed or whether the source course is left intact, keeping it below 5.

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 purpose and then the two-phase mechanics. Every sentence carries actionable information with no filler.

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 destructive two-phase operation with 7 params and an output schema, the description covers the token flow, the date-shifting constraint, and preview behavior, which is enough to call correctly. Minor gaps remain around token expiry behavior and source-course impact.

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 100%, so baseline is 3. The description adds a genuinely extra constraint not captured in the schema: date shifting accepts either all four date fields or none. The token parameter semantics are already in the schema, so it doesn't go further.

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 ('full course-copy migration request') and frames the two-phase preview/confirm nature up front. An agent can tell this apart from siblings like get_content_migration_status, which is read-only status checking, 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?

Clear procedural guidance: first call to preview, second call with the token and identical arguments to execute. It does not name the alternative sibling (get_content_migration_status) or state exclusions, so it falls short of a 5.

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?

Far beyond the annotations, it discloses required permissions (manage_groups_add, manage_groups_manage, read_roster), hard limits (200 students, 50 groups, 250,000 CSV characters), the single-use caller/content/state-bound token, partial-result semantics with created IDs and run_id, 24-hour server-local run records that do not survive restart and require affinity, and the concurrency caveat that Canvas offers no atomic membership compare-and-set.

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?

Information density is high and the critical preview/approval workflow is front-loaded, with limits and failure semantics after. It is a dense block of short sentences with little grouping, which slightly impedes scanning, but almost every clause carries operationally relevant 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 destructive, non-idempotent bulk mutation, it covers workflow, permissions, limits, partial failure, resumption, token invalidation and concurrency; an output schema exists so return-value documentation is unnecessary. The only meaningful omission is how course_identifier is interpreted and what exactly a preview call returns before a token is supplied.

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?

With 0% schema description coverage, the description carries the burden well: it specifies csv_data columns (group_name, description, canvas_user_id, one student per row), that names/emails are rejected as IDs, that existing group-set names are rejected for group_set_name, and the single-use nature of confirmation_token. The gap is course_identifier, whose ID-vs-slug/integer semantics are never explained.

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 ('Preview, then confirm creation of a NEW course group set and its groups/members') and defines the scope (CSV-driven bulk creation). It also implicitly separates this tool's job from resume_course_group_creation by describing the resume path and its fresh preview/token requirement.

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 gives a clear operational sequence: preview, show the complete preview, obtain the instructor's explicit approval, then confirm. It also states the resume path ('resume uses a fresh preview/token and checks ALL current memberships'). What it does not do is name resume_course_group_creation explicitly or state when to prefer other group tools such as list_groups.

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?

The annotations only state idempotentHint=false and destructiveHint=false, while the description adds critical behavioral context: the topic is always published on creation, students may see it immediately, and later unpublishing does not undo that initial visibility. It also warns against reposting failed announcement content, which is meaningful safety guidance beyond the 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?

The key behavior is front-loaded in the first sentence, and the remaining sentences focus on non-obvious publishing consequences and misuse prevention. There is no filler, and the caution about failed announcements earns its place as safety 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?

For a mutation tool with sparse annotations and no output schema, the description covers the most important side effect: immediate publication and its visibility implications. It could mention authentication/permission requirements or return behavior, but the core invocation risks are well addressed.

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 100%, so all seven parameters are already documented. The description adds useful meaning for delayed_post_at by explaining that it schedules later visibility, which is more than the schema's plain 'schedule posting' wording, though it does not add analogous semantic detail for the other optional 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 states a specific verb and resource: 'Create and publish a discussion topic in a course.' It also differentiates from update_discussion_topic and create_announcement by explaining that unpublishing does not undo initial visibility and that failed announcement content should not be reposted here.

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 gives clear usage conditions and exclusions: there is no draft option, delayed_post_at should be used when the topic must not be visible yet, and failed create_announcement content should not be posted here. It does not fully spell out the general choice between discussion topics and announcements, but the context is strong.

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?

Annotations only declare idempotentHint=false and destructiveHint=false, so the description carries the important side-effect disclosure: modules are published by default and therefore student-visible immediately, subject to unlock_at and prerequisites. This is exactly the kind of non-obvious consequence an agent needs. It stops short of noting permission requirements or that a failed partial create can't be retried idempotently, which the idempotentHint=false annotation implies.

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?

Front-loaded with the purpose, then the default-visibility behavior with the escape hatch (published=False) at the end. Every sentence carries information, though the middle sentence is long and packs three separate gating concepts (unlock_at, prerequisites, default publish) into one clause chain.

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 7-parameter creation tool with no output schema, the description covers the one behavior that matters most (default visibility) and the draft escape hatch. What's missing is what comes back — whether the created module's ID is returned so the agent can chain into add_module_item — and any permission/enrollment requirement.

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 baseline is 3; the description earns an increment by explaining the real consequence of the `published` flag — visibility to students on creation — rather than restating "Whether the module is published." It also contextualizes unlock_at and prerequisite_module_ids as gating conditions, though it adds nothing about position or require_sequential_progress 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?

The first sentence states a specific verb and resource ("Create a module in a course"), which is unambiguous and clearly distinct from update_module, delete_module, and add_module_item in the sibling list. It doesn't explicitly name those siblings, but the create/update/delete/item split is inferable from the name and description.

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 implicitly clear from the creation verb, and there is one concrete usage hint — "pass published=False to build it as a draft" — for the draft workflow. However, it never addresses when to use this versus add_module_item (adding content to an existing module) or how it precedes update_module, and offers no prerequisites or exclusions.

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?

Adds real value beyond the annotations by disclosing that pages publish by default and are student-visible on creation, subject to module/access restrictions — a side effect an agent must know about. However, with destructiveHint=true declared, the description says nothing about the destructive/mutation implications, permission requirements, or whether a duplicate title overwrites anything.

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 with the core action front-loaded and the non-obvious default immediately after. No filler; could be tightened slightly but is well-structured.

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-param mutation tool with no output schema, the description covers the most important behavior (default publication) but omits permission requirements, what `front_page=True` displaces, and what the returned page reference looks like. 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 coverage is 100%, so the schema already documents all six parameters. The description adds contextual meaning for `published` (default visibility to students) beyond the schema's 'Whether to publish (default: True)', but says nothing about `front_page` or `editing_roles`, which carry non-obvious course-wide effects.

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 ('Create a page in a Canvas course'), which clearly separates it from siblings like edit_page_content, update_page_settings, and delete_page. It doesn't explicitly name a sibling boundary, but the create vs. modify distinction 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?

Gives an actionable usage hint ('pass published=False to create a draft') but does not say when to use this versus edit_page_content or update_page_settings, nor any prerequisites (e.g., teacher role needed to create pages in a course).

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?

Annotations declare destructiveHint=true and idempotentHint=false, but the description does not explain the destructive or non-idempotent consequences, required permissions, or whether creation can be undone. It adds detail about criteria encoding but little behavioral context beyond what the annotations already state.

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 front-loaded with the core action and then explains the complex criteria format. The example is justified by the complexity of the criteria JSON, though the overall text is somewhat 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?

The description adequately covers the most complex input, criteria, but omits return values, permission requirements, and guidance on sibling tools. Given the lack of an output schema and the presence of multiple rubric-related siblings, these gaps keep completeness at a minimum-viable level.

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 already 100%, so the schema documents all seven parameters. The description still adds substantial value for the complex criteria parameter by defining its required and optional fields and providing a complete JSON example.

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 and resource: create a new rubric in a course, with optional assignment association. The scope is clear, but it does not distinguish this tool from siblings such as create_rubric_from_csv or associate_rubric.

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 by 'Create a new rubric.' The description gives no guidance on when to use this instead of create_rubric_from_csv, update_rubric, or associate_rubric, nor when to pass assignment_id versus using the separate association tool.

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?

Goes well beyond the annotations (idempotentHint=false, destructiveHint=false) by disclosing that the tool polls the import job to a terminal state, that imported rubrics land in Draft and are invisible to list_rubrics, and that succeeded_with_errors is terminal and can mean zero rubrics created. These are exactly the non-obvious behaviors that would mislead a caller.

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?

Front-loaded with the action and mechanism, then a required-format block, then a short bullet list of caveats. Every element, including the CSV example, earns its place by preventing a concrete failure mode.

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?

No output schema exists, and the description implies the tool returns after polling to a terminal state but does not describe the response shape. For a two-required-param mutation with rich CSV semantics, the rest is well covered.

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 100%, so the baseline is 3, but the description substantially enriches csv_content by giving the required column set, the 'Rubric Name' requirement, and the row-per-rating-level repeating convention. course_identifier is left to the schema, which is adequate.

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 (create), resource (rubric), scope (one or more, in a course), and mechanism (from a CSV string). This clearly differentiates it from the sibling create_rubric (single rubric) and list_rubrics, so an agent can pick it 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?

The description establishes context for use: bulk creation via Canvas's native CSV import endpoint, with the required CSV format. It does not explicitly say when to prefer create_rubric over this tool, so the alternative routing is left implicit.

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?

The annotations declare destructiveHint=true and idempotentHint=true, so the description should clarify what is destroyed or overwritten. It does add useful privacy context by saying the CSV maps real student data, but it does not explain whether an existing map is overwritten, where the file is written, or how idempotency behaves.

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 definition is a single efficient sentence with zero waste. The core action and artifact are 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?

For a one-parameter tool, the description covers the central purpose and privacy sensitivity. However, given destructiveHint=true and no output schema, it should say more about file location, overwrite behavior, and the relationship to get_anonymization_status.

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% for the single course_identifier parameter, and the schema already documents that it accepts a course code or Canvas ID. The description adds only that the mapping is for a course, which is already implied by the parameter.

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 and artifact: create a local CSV mapping real student data to anonymous IDs for a course. It is clear what the tool produces, though it does not explicitly distinguish itself from the sibling get_anonymization_status tool.

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 no guidance on when to use this tool versus alternatives such as get_anonymization_status, nor does it mention prerequisites, sequencing, or exclusions. The intended workflow must be inferred.

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?

Annotations already flag destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuine value on top by disclosing that deletion is permanent and that Canvas may retain a recycle-bin copy depending on admin settings. The preview-then-confirm gate is also a behavioral trait not expressible in annotations, though it omits any mention of permission requirements or what the preview returns.

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 with the destructive action and its required workflow front-loaded, followed by the permanence caveat. Nothing is repeated and nothing is padding.

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 destructive bulk-delete with no output schema, the description covers the essential points: what qualifies for deletion, the mandatory preview/confirm handshake, and irreversibility. It leaves minor gaps around what the preview response contains and whether limit is enforced only at confirmation.

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 all four parameters including the nested criteria dict and the limit safety cap are already documented in the schema. The description only echoes the confirmation_token concept via "confirm with the token" without adding format or value constraints, so the baseline 3 applies.

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 ("Delete announcements") plus a scoping qualifier ("matching criteria"), so the action is unambiguous. It does not, however, distinguish itself from the closely related siblings delete_announcement_with_confirmation and bulk_delete_announcements, which an agent must otherwise infer from those tools' own schemas.

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?

"Two-step: preview first, then confirm with the token" gives an explicit operational sequence that an agent must follow, which is real usage guidance rather than implied context. It stops short of naming alternatives, so it never says when to reach for bulk_delete_announcements or the single-item delete instead.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, so safety is covered; the description earns credit for adding the two-step preview/confirm protocol and the nuance that deletion is permanent but Canvas may retain a recycle-bin copy depending on admin settings. That recycle-bin caveat is non-obvious behavior an agent could not infer from the 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?

Two short sentences with no filler; the core action and the gating two-step workflow are front-loaded, and the permanence warning is placed as a distinct trailing note. Slightly terse rather than padded — no sentence 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?

For a destructive, four-parameter mutation tool with no output schema, the description covers the critical unknowns: the confirmation-token workflow and the true reversibility picture. It does not describe what the preview call returns or when require_title_match should be set, which leaves a modest gap for an agent designing the preview step.

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 announcement_id, course_identifier, confirmation_token and require_title_match. The description reinforces the token semantics ('preview first, then confirm with the token') but adds nothing about require_title_match or accepted identifier formats, so it sits at the 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 and resource: 'Delete an announcement.' An agent knows immediately what the tool does. However, it does not distinguish this from the sibling tools bulk_delete_announcements and delete_announcements_by_criteria, leaving ambiguity about which delete path to take.

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?

'Two-step: preview first, then confirm with the token' gives an explicit operating procedure that governs how the call must be sequenced, which is real usage guidance. It stops short of stating when to prefer this single-item tool over the bulk-delete siblings, so no explicit exclusivity rule is given.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, and the description goes well beyond them by disclosing the blast radius: every submission and grade attached to the assignment is removed, and a recycle-bin copy may or may not survive depending on admin settings. That is precisely the loss-of-data context an agent needs before a destructive call.

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 with zero filler; the two-step protocol is front-loaded and the destructive consequences follow immediately. Every sentence carries distinct information.

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 destructive tool this covers the essentials: mechanism, sequencing, and impact. It omits permission/authorization requirements and whether recovery from the recycle bin is user-actionable, which would round it out, but annotations carry the safety profile and no output schema needs explaining.

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 all four parameters (including confirmation_token's preview semantics and require_name_match) are already documented in the schema. The description only reinforces the token/preview concept and adds nothing on course_identifier or name matching, so the baseline applies.

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 ("Delete an assignment") and immediately characterizes the unusual two-step protocol. No sibling tool in the list deletes assignments, so confusion with create_assignment/update_assignment is impossible.

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?

"Two-step: preview first, then confirm with the token" tells the agent exactly how to sequence the call and when to omit the token. It stops short of naming preconditions or explicitly discouraging use versus alternatives (e.g., archiving), so it is clear context rather than full when/when-not guidance.

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?

Goes well beyond the destructiveHint annotation by spelling out the blast radius: the module and its item links are gone, but the underlying pages, assignments and files remain in the course. That distinction is the single most important thing an agent needs before calling a destructive tool, and the two-step token flow adds a further safety behavior not encoded in 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?

Three short sentences, no waste, and the irreversible nature and workflow are front-loaded before the caveat about retained 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 destructive tool with no output schema, the description covers permanence, cascade scope and the confirmation workflow. The one remaining gap is that it doesn't say what the preview step returns (an item count? a warning?), which an agent would want before committing to the second call.

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 100% and the schema already documents module_id, course_identifier and confirmation_token ('Token from the preview call; omit to preview'). The description restates the token workflow in prose without adding format details, so the schema is doing the heavy lifting and baseline 3 applies.

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 ('Delete a module') and immediately defines scope: 'Permanently removes the module and its item links.' The clarification that linked content (pages, assignments, files) survives distinguishes it from the sibling delete_module_item and from generic deletion tools.

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?

'Two-step: preview first, then confirm with the token' tells the agent exactly how to sequence the call. That is strong procedural guidance, but it never names an alternative (e.g. delete_module_item for removing a single item, or update_module as a non-destructive path), so the when-not-to-use case is implicit.

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?

Annotations already indicate destructiveHint=true and idempotentHint=true, but the description adds crucial scope: only the item-module link is removed and linked content survives. It also discloses the required preview/confirm token workflow, which is important behavioral context beyond the 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?

Two short sentences, front-loaded with the action and followed by the key safety caveat. Every sentence carries useful information with no filler.

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 destructive mutation with complete schema and destructive annotations, the description covers the main things an agent needs: the scope of deletion and the preview/confirm protocol. No output schema exists, but the critical invocation semantics are present.

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%, and all four parameters are already documented in the schema, including confirmation_token's preview behavior. The description reinforces the token workflow but adds little syntax or constraint detail beyond what the schema provides.

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 uses a specific verb and resource: 'Remove an item from a module.' It also clarifies that only the module link is removed, distinguishing this action from deleting the underlying page, assignment, or the module itself.

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 gives explicit procedural guidance: preview first, then confirm with the token. It does not name alternatives such as update_module_item or delete_module, so there is no explicit when-not guidance, but the required invocation context is clear.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds real value beyond that: the mandatory preview/confirm token flow and the caveat that a recycle-bin copy may exist depending on admin settings, which tempers the word "Permanent." It does not mention permission requirements or what the preview returns.

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, front-loaded with the action and the two-step requirement, with the permanence caveat second. Nothing is wasted and no filler precedes the operative instruction.

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 destructive mutation with no output schema, the description covers the critical unknowns: the confirmation flow and the true extent of permanence. It leaves auth/permission expectations and preview-call output unclear, which is a minor but real gap.

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 explains all four parameters. The description reinforces that confirmation_token comes from the preview call, but says nothing about require_title_match, the key safety parameter. Baseline 3 applies when the schema carries the detail.

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 ("Delete a page") that is unambiguous against page siblings like create_page, edit_page_content, and update_page_settings. It does not explicitly name those siblings, so it falls short of the 5 mark.

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?

"Two-step: preview first, then confirm with the token" gives concrete invocation guidance and a clear order of operations. It does not say when deletion is the right choice versus alternatives such as update_page_settings or bulk_update_pages, so no exclusion guidance.

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?

Annotations only say readOnlyHint=false, idempotentHint=true, destructiveHint=false; the description adds real behavioral context beyond that: the stdio-only availability, and a non-obvious platform caveat that on Windows owner-only access is not enforced so files inherit the destination folder's permissions. The security workaround (use a verified-private folder or avoid a local copy) is disclosed rather than left to be discovered.

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?

Front-loaded with the core action, then alternatives, then the platform caveat, then ID discovery — a sensible priority order with no filler. The second mention of read_course_file as a Windows fallback is mildly redundant but tied to a distinct risk, so it mostly 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?

For a 3-parameter, no-output-schema tool with annotations present, the description covers availability constraints, safer alternatives, security caveats, and ID sourcing. The only gap is what a successful call returns (e.g., the saved path or filename), which an agent may want to report back.

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 file_id, course_identifier, and save_directory (including the default temp dir and must-exist constraint) are already documented. The description adds only indirect color — that file_id values come from the list tools and that save_directory choice matters on Windows — without any new syntax or format detail.

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 ('Download a file from a Canvas course') plus the destination ('to the local filesystem'), which immediately separates it from read_course_file. The distinction from the sibling content-reading tool is spelled out, so an agent can choose without opening either 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 names the alternative ('Use read_course_file to get file content back in the response instead') and gives discovery guidance ('Use list_course_files or list_module_items to find file IDs'). It also states an environment precondition — only available on a local (stdio) server — which is exactly the kind of when-not guidance agents need.

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?

Annotations only declare idempotentHint and destructiveHint; the description adds substantial context beyond that — the body is fully overwritten rather than merged, guards cause a fetch-first + refuse-on-failure + read-back-after cycle, and settings/roles/front-page are left untouched. This materially changes how an agent should prepare arguments (complete page vs fragment) and is the kind of behavioral detail annotations cannot convey.

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 replacement semantics and the sibling pointer are front-loaded, and the guard behavior is grouped into a single paragraph. It is dense rather than padded, though the parenthetical restatement about fetching/refusing/reading back repeats a mechanism already implied per-parameter.

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 an 8-parameter mutation with no output schema, the description covers destructive scope, mode selection, and guard behavior well. The remaining gap is that it does not say what the tool returns after the read-back (e.g., refreshed body/updated_at) nor how conflicting new_content + find inputs are resolved, which an agent would need for recovery on refusal.

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 100%, so baseline is 3, but the description goes further by explaining the interaction between parameters: new_content is a complete replacement and should be omitted when using find/replace, find must occur exactly once, and each guard (expect_updated_at, find/replace, require) triggers fetch/refuse/read-back semantics. It does not clarify what happens if new_content and find are supplied together, leaving one small ambiguity.

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 first sentence states a specific verb and resource ('Replace the HTML body of a page') and immediately bounds scope ('and optionally its title'). It also distinguishes itself from update_page_settings by naming what it does not touch (publishing state, editing roles, front-page status), so an agent can separate it from siblings like update_page_settings, bulk_update_pages, and create_page without opening schemas.

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 explicitly routes between two modes: pass new_content for a full-body rewrite, or pass find/replace for a single fragment, and warns that new_content is not merged. It also names the sibling to use for settings ('use update_page_settings') and explains the opt-in guard conditions, which is exactly the when-to-use guidance an agent needs.

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?

Annotations declare idempotentHint=true and destructiveHint=true, but the description adds no context about what is destructive: nothing says it writes a file to local disk (save_locally defaults true), nothing mentions the default anonymization of student data, and nothing warns about export volume or permissions. With a destructive hint and no explanatory text, the description leaves the risky behavior opaque.

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 short, front-loaded sentence with zero redundancy. It is efficient, though the brevity edges toward under-specification rather than tightness.

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?

This is a 7-parameter bulk export that writes files and handles sensitive student data, with no output schema. The description says nothing about the default-on anonymization, local file creation, or what 'all peer review data' contains, so an agent cannot predict the operation's consequences from the text.

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 all seven parameters are already documented in the schema. The description only echoes this with 'various formats', adding no meaning about format choices, filename behavior, or how anonymize_data/include_analytics affect output. Baseline 3 applies.

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 (Export) and resource (peer review data) with scope (all) and purpose (for analysis). However, it does not differentiate itself from the many peer-review siblings such as generate_peer_review_report, analyze_peer_review_quality, or get_peer_review_comments, so an agent must infer how this differs.

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 export over the report/analytics siblings, no mention of prerequisites, and no exclusions. The only hint is 'for analysis', which does not route the agent among the numerous peer-review 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's remaining burden is low, but it still adds little. It does not say what happens if no page titled 'UFIXIT' exists (empty result vs. error), whether it searches within a single course only, or what form the report takes.

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 efficient, though its brevity is partly under-specification rather than disciplined economy.

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, so the description is the only place the agent could learn what a 'UFIXIT report' contains or how it relates to parse_ufixit_violations downstream. For a retrieval tool whose value depends on the returned report structure, this leaves a meaningful gap.

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 100%, with both course_identifier and page_title fully documented including the 'UFIXIT' default, so the schema carries parameter semantics. The description adds no clarification on accepted course code formats or when to override page_title, so the baseline 3 applies.

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 uses a specific verb ('Fetch') and resource ('UFIXIT accessibility report') and states the source location ('from Canvas course pages'). It does not distinguish this from closely related siblings such as parse_ufixit_violations, scan_course_content_accessibility, or format_accessibility_summary, leaving the agent to infer whether this retrieves a pre-existing page versus generating a report.

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 when-to-use guidance, prerequisites, or exclusions are given. Given siblings like parse_ufixit_violations and scan_course_content_accessibility in the same accessibility family, the description should explicitly say whether this is the retrieval step that feeds those tools, but it says nothing.

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?

Annotations already declare readOnlyHint=true, so the bar is lower, yet the description adds real behavior: only individuals are returned, non-staff appear as Student_<hash> pseudonyms under anonymization, and name searches then match staff only. These are non-obvious result-shaping traits an agent would otherwise get wrong; only pagination/limit behavior is left unstated.

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 tight sentences: what it returns first, the workflow use second, the anonymization caveat last. No repetition of title or schema content, and every sentence carries decision-relevant information.

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 a full schema, an output schema, and readOnlyHint annotations, the description covers the parts that matter (scope of results, anonymization effects, intended follow-up tool). It does not mention result ordering or that limit caps matches at 50 beyond the schema, a minor gap.

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 100%, so the baseline is 3, but the description adds meaning the schema only partially conveys: the anonymization caveat on search ('matches only course staff') clarifies a subtle query-time behavior beyond the field's own text, and the individuals-only note constrains interpretation of results.

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 ('Find people you can message in a course') plus the concrete output (Canvas user IDs) and a scope constraint ('Only individual people are returned'). It does not explicitly contrast with look-alike siblings such as list_users or get_group_members, so an agent must infer the distinction, which keeps it just below a 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?

Gives a concrete usage moment ('look up your instructor's or TA's user ID before send_message'), naming the downstream tool explicitly. It lacks an explicit when-not condition or named alternative lookup tool, but the intended workflow is clear.

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?

Annotations declare idempotentHint=true and destructiveHint=true; the description is consistent with this by emphasizing preview-by-default and restricting fixes to scanner-flagged auto_fixable items. It adds useful context beyond annotations, though it doesn't disclose partial-failure behavior or whether fixes are reversible once applied.

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 short lines, front-loaded with the core action and scope, then the prerequisite, then the safety default. Every sentence earns its place with no redundant filler.

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 output schema, the description covers the essential workflow (scan first, preview by default, scope limited to auto_fixable). It is nearly complete, missing only a note on what the response reports or handling of failures.

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 100%, so all four parameters including the fix_types and content_types enumerations are already documented in the schema. The description only restates the dry_run default, adding little beyond the structured fields, so baseline 3 is appropriate.

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 (auto-fix) plus resource (accessibility issues in Canvas course content), and it explicitly differentiates itself from scan_course_content_accessibility by describing itself as the apply step that acts on issues 'flagged as auto_fixable by the scanner.' An agent can clearly tell which of the sibling tools performs the mutation.

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?

States an explicit prerequisite and alternative: 'Run scan_course_content_accessibility first to see what will be fixed.' It also documents the default-safe invocation (dry_run=True preview) versus dry_run=False to apply, so the agent knows the intended workflow without inference.

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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds the input source and transformation goal, but it does not describe the summary's format, grouping, or contents, which are relevant since there is no output schema.

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, front-loaded sentence with no filler. Every word contributes to identifying the action and output.

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 formatter with complete schema coverage and a read-only annotation, the description supplies enough context to invoke the tool correctly. It is slightly incomplete in not describing the summary's shape, but that is a minor gap given the tool's narrow purpose.

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 100%, and the parameter description already explains that violations_json is the JSON string from parse_ufixit_violations. The tool description repeats the same source without adding further semantics such as expected structure or validation constraints.

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 ('Format') and resource ('parsed violations') with the output type ('human-readable summary'). It clearly identifies the transformation but does not explicitly distinguish this tool from siblings like parse_ufixit_violations or fetch_ufixit_report.

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 'parsed violations' and the parameter description referencing parse_ufixit_violations, so an agent can infer it should be called after parsing. However, the description does not state when to use this versus alternatives or any exclusions.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description could have spent its words on adding value. It adds only the 'instructor-ready' audience framing, and says nothing about what the report contains, whether it aggregates data behind the scenes, or privacy handling beyond the schema's include_student_names flag.

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 wasted clauses. It is terse rather than padded, though that terseness is what leaves the gaps above.

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?

Five parameters, no output schema, and a dense cluster of sibling reporting tools. The description should at least say what the report covers and when to pick it over generate_peer_review_report; it does neither.

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 all five parameters are already documented in the schema, including format_type, report_type, and include_student_names. The description adds no parameter meaning beyond that, which is the baseline 3 case.

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 verb and resource ('Create instructor-ready reports on peer review quality'), but the purpose is vague for a tool that sits next to generate_peer_review_report, analyze_peer_review_quality, and get_peer_review_completion_analytics. Nothing in the sentence tells an agent how this report differs from those siblings.

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 and no naming of alternatives. With four closely-named peer-review reporting tools in the sibling list, the agent has to guess which one applies.

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?

Annotations declare destructiveHint=true and idempotentHint=false, but the description does not explain what could be destructive, whether files may be overwritten, or what side effects occur when saving reports. It adds only the report's content areas, not the behavioral context needed for a reportedly destructive operation.

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 single sentence is front-loaded and free of filler. However, for a nine-parameter report generator with file-save and destructive annotations, it is terse enough that important usage context is omitted.

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 a destructive annotation, the description should clarify side effects, file-saving behavior, and how this tool relates to the granular peer-review analytics and follow-up tools. It gives a useful high-level purpose but leaves key operational context missing.

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 schema has 100% description coverage, so all nine parameters are documented in the structured schema. The description adds no parameter-specific meaning, which is acceptable at this coverage level but does not improve on 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?

The description states a specific verb and resource: generate a peer review completion report, and it names the included content types: summary, analytics, and follow-up recommendations. It is distinguishable from lower-level siblings such as get_peer_review_completion_analytics and get_peer_review_followup_list, though it does not explicitly say this tool aggregates 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 provides no guidance on when to use this report generator rather than the many granular peer-review siblings such as get_peer_review_completion_analytics, get_peer_review_followup_list, or generate_peer_review_feedback_report. There are no exclusions, prerequisites, or recommended contexts.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered, but the description adds essentially nothing beyond restating the name. It does not disclose what the 'statistics' contain, whether results reflect a point-in-time snapshot, or any permission requirements for viewing anonymization data.

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 repetition. It is efficient, though its brevity comes at the cost of the detail noted elsewhere.

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 beyond readOnlyHint, the description carries the full burden of explaining the return payload, yet 'status and statistics' is left undefined. An agent cannot predict what fields or metrics it will receive, which is a real gap for a status-reporting 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; the baseline of 4 applies. No misleading parameter claims are made.

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 ('Get current data anonymization status and statistics'), which is clear enough to distinguish a read of anonymization state from the write-oriented sibling create_student_anonymization_map. However, it never says the scope (institution-wide vs. per-course) or what 'statistics' actually covers, so the purpose is clear at a coarse level only.

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 versus the sibling create_student_anonymization_map or any other status tool, and no prerequisites or exclusions are stated. The agent must infer usage entirely 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?

The readOnlyHint annotation already establishes the safety profile, but the description adds almost nothing beyond intent: it does not say what analytics are returned (score distribution, averages, submission rates), whether results are aggregated or per-student, or any access constraints. For an analytics tool with no output schema, that is a meaningful 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?

A single front-loaded sentence with no wasted words. It is efficient, though its brevity is partly the cause of the missing behavioral detail.

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 is the only place an agent could learn what the 'detailed analytics' actually contain, and it says nothing about the returned fields or granularity. An agent cannot predict the response shape before calling.

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%, with both parameters documented as course code/Canvas ID and assignment ID. The description only implies the assignment scoping and adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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 (get analytics) and a specific resource (student performance on a specific assignment), which is more precise than the tool title alone. However, it does not distinguish itself from closely related siblings such as get_student_analytics, get_assignment_details, or get_peer_review_completion_analytics.

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 tool versus get_student_analytics (per-student view) or get_assignment_details (metadata view). The agent must infer the intended selection criteria from the name alone.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds no behavioral context beyond that—it does not explain what 'detailed information' contains, whether the call is affected by permissions, or what the raw_dates flag changes. For a read-only tool with annotations, this is a minimal contribution.

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 sentence, front-loaded and free of filler. It is concise, though that conciseness comes at the cost of missing useful context rather than being optimally informative.

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?

No output schema exists, so the description should explain what 'detailed information' entails (e.g., assignment metadata, due dates, submission types). It does not, and it also omits any differentiation from the many sibling assignment-related tools. For a tool in a crowded LMS namespace, this leaves key context 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?

Schema description coverage is 100%, with course_identifier, assignment_id, and raw_dates all documented in the schema. The description adds no additional meaning or formatting guidance beyond that baseline, so it neither helps nor harms parameter selection.

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 and resource (get, assignment), but it essentially restates the title 'Get Assignment Details' without clarifying what 'detailed information' includes or how it differs from sibling tools like list_assignments, get_assignment_analytics, or get_my_assignment_scores. An agent can identify the resource but not the exact scope.

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 list_assignments or get_assignment_analytics, nor any mention of prerequisites or context. The agent must infer that this is a single-assignment retrieval tool from the required parameters alone.

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?

annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that the response is complete and includes the description field, which is mildly useful, but says nothing about permissions, error behavior when the event_id is invalid, or what 'in full' actually contains.

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 short sentence with the key qualifier ('in full') front-loaded; nothing is padded and every clause carries information.

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 one-parameter read tool with no output schema and readOnlyHint set, the definition covers what is needed to invoke it. The only gap is that 'in full' is never concretized into the fields returned.

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% and the schema's event_id text is richer than the description, including the string-or-integer type and the alternative tool for assignment due dates. The description adds no parameter meaning beyond that, so baseline 3 applies.

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 ('Get one calendar event') plus a scope qualifier ('in full, including its description'), which separates it from the list tool. It does not name list_calendar_events or any sibling in the description text itself.

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?

Use is only implied: retrieve a single event when you need the full record. The explicit 'from list_calendar_events' and 'use get_assignment_details instead' routing lives in the schema's parameter description, not in the description, so the agent must read the schema to get the guidance.

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?

The readOnlyHint already marks this as a safe read, but the description adds useful behavior beyond annotations: progress is read once per call, polling is conditional on poll_again, and terminal results may include migration issues. It does not cover auth or rate limits, but those are not central for this read operation.

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 short and front-loaded: it states the core read operation first, then explains polling behavior and terminal-result caveats. Every sentence contributes useful information without repetition.

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 the description need not explain return structure. It still adds the important output-adjacent behaviors: one progress read per call, conditional polling via poll_again, and possible migration issues in terminal results, making it complete for an agent using this 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 description coverage is 100%, and both parameters are already documented in the schema, including migration_id being the value returned by create_content_migration. The description adds no additional parameter syntax or constraints beyond that 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?

The description clearly states a specific verb and resource: it reads one content migration and its current progress snapshot. It makes the single-migration scope clear, but it does not explicitly contrast with the related create_content_migration 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?

It gives concrete polling guidance: each call reads once and the caller should poll again only when poll_again is true. It does not explicitly say to use this after create_content_migration or name alternatives, so it is clear but not fully routing-aware.

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?

Annotations already declare readOnlyHint=true, but the description adds a genuinely non-obvious trait: viewing does not mark the conversation read. That is the kind of side-effect disclosure that saves an agent from a wrong assumption, though nothing is said about pagination or message volume limits.

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 with no filler, and the read-state caveat follows immediately after the purpose. Efficient, though the caveat could have been folded in more tightly.

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 an output schema present and annotations covering the safety profile, the description only needs to cover the read-state semantics, which it does. The remaining gap (how to discover conversation IDs) is minor for a two-parameter read 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 100%, so both parameters are documented structurally; the phrase 'with messages' loosely maps to include_messages, but the description adds no detail on the default (true) or on the accepted ID types. Baseline 3 applies when the schema does 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?

States a specific verb and resource ('Get detailed conversation information with messages'), clearly distinguishing it from the listing sibling list_conversations. It stops short of explicitly naming the sibling used to enumerate conversations, but the purpose 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?

Gives clear usage context by naming mark_conversations_read as the alternative for marking read, which is the most likely point of confusion. It does not mention how to obtain a conversation_id (e.g., via list_conversations), leaving a small gap.

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?

readOnlyHint=true already establishes the safety profile, so the description only needs to add aggregation-specific context. Instead it only restates the sections covered, which mirrors the include_* flags in the schema, and says nothing about cost, response shape, or behavior when sections are excluded.

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-formed sentence with the verb and the three content areas front-loaded; nothing redundant or padded. It is arguably too short for the aggregation semantics, but there is no filler.

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 aggregation tool with a fully documented 4-parameter schema, the key missing piece is what the returned overview looks like and how large it can get. That gap is modest given the annotation and complete schema coverage, but it prevents a 5.

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% and each of the three boolean flags is documented with its default, so the schema carries parameter meaning. The description's mention of pages/modules/syllabus loosely maps to those flags but adds no filtering or format detail beyond them.

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 ("Get a comprehensive overview of course content") and enumerates the included sections (pages, modules, syllabus). Clear on its own, but it never distinguishes itself from close siblings like get_course_structure, get_syllabus, list_pages, or list_modules, which plausibly return overlapping data.

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 exclusions, and no mention of alternatives despite a crowded sibling set containing get_course_structure and get_syllabus. The agent must infer that this is the 'one-shot aggregate' variant versus the targeted list_* 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?

readOnlyHint=true already establishes this is a safe read, so the description carries less burden, but it adds nothing behavioral: it does not say what happens with an invalid or unknown identifier, whether archived/concluded courses are returned, or what 'detailed' covers. With no output schema, the phrase 'detailed information' stays unquantified.

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 zero filler. It is efficiently written, though its brevity comes at the cost of the information a caller actually needs.

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 one-parameter read tool with full schema coverage, the definition is minimally sufficient: an agent can form a call. It is however silent on the shape of the returned 'detailed information' and on how this differs from the many adjacent course-content getters, leaving real ambiguity in a very crowded sibling set.

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 100% and the schema itself explains 'Course code or Canvas ID' plus the string-or-integer union, so the description need not repeat it. The description adds no extra meaning such as format examples or whether a code or numeric ID is preferred, which is the expected baseline-3 outcome.

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: retrieve detailed information about one course, keyed by an identifier. It is clear on its own but draws no boundary against near-neighbours like get_course_content_overview, get_course_structure, or get_syllabus, which also return course-level data.

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 or when-not-to-use guidance, and no hint about which sibling to pick when the agent wants course-level information. The invocation context has to be inferred entirely from the tool 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds that it returns the full structure in one call, which is useful behavioral context. It does not describe the return format, pagination behavior, or permission requirements, but with annotations covering safety, this is adequate.

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, front-loaded sentence with no wasted words. It communicates the core action and its key efficiency trait immediately.

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 read tool with full schema coverage, no output schema, and readOnly annotations, the description is minimally sufficient. However, because this is an aggregation tool, it could better state what 'full module and item structure' includes (e.g., nested modules with items) and whether it is meant to replace the list tools.

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%, and both parameters are clearly documented in the schema, including the accepted course identifier forms and the unpublished-content toggle. The description adds no parameter-specific meaning beyond the schema, so the baseline score of 3 applies.

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 uses a specific verb and resource: it retrieves the full module and item structure for a course. The phrase 'in a single call' hints at aggregation and distinguishes it somewhat from list_modules or list_module_items, though it does not name those siblings 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?

Usage is only implied: 'in a single call' suggests this is the efficient way to get modules plus items instead of making multiple list calls. However, it does not explicitly say when to use this tool versus list_modules or list_module_items, nor does it state any prerequisites or exclusions.

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?

readOnlyHint=true already covers the safety profile, so the description only needs to add context. Instead, 'including all its replies' is stated unconditionally even though include_replies defaults true but is toggleable, and nothing is said about permissions, group-scoped entries, or response size for large threads.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.