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

Annotations already indicate this is a non-read-only, non-idempotent, non-destructive operation. The description adds valuable behavioral context by stating the confirmation requirement (aligning with the `confirm` parameter's const true) and the verification step after sending. It does not contradict annotations and supplements them with the two-step behavior, though it omits details about failure handling or side effects.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, dense sentence that front-loads the core action, embeds the precondition, and ends with the verification step. There is no wasted text; every clause adds necessary information. The structure is efficient and proportionate to the tool's complexity.

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 write tool with no output schema and only two parameters, the description covers the primary behavior and precondition. However, it lacks details on what happens if verification fails, whether the operation is repeatable (idempotency is already annotated but not explained), and any side effects or error conditions. Given the stakes of sending data to an external service, additional context on failure handling would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must explain parameter purpose. It does clarify `confirm` as 'explicit confirmation' and `previewId` as referring to a 'previously previewed' import, but it does not explicitly state that `previewId` comes from the preview tool or describe its format beyond the schema. The description adds meaning but could be more explicit about the source of the previewId.

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 the tool's action: 'Sends student names to ClassDojo' (applies an import) and includes a distinguishing behavior: 'only after explicit confirmation, then verifies each class by reading it back.' This differentiates it from preview_roster_import (which only previews) and verify_roster_against_workbook (which compares to workbook, not ClassDojo). The verb-resource pairing is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly conditions usage on 'explicit confirmation' and a 'previously previewed' import, making it clear this is the apply step after a preview. However, it does not explicitly name alternatives or state when not to use it, though the sibling set and title imply the workflow. This is clear context but lacks direct exclusions or comparative 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 annotations already flag destructiveHint, but the description adds precise behavioral context: the operation is an exact replacement, it is gated on explicit confirmation, and it performs a read-back of every class afterward. This goes well beyond the structured hints and does not contradict them.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense sentence delivers action, precondition, and postcondition with no filler. The destructive nature is front-loaded before the read-back 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?

For a destructive two-parameter tool, the definition captures what is replaced, when it is allowed, and the follow-up read. It does not explicitly describe the return value or specify that previewId comes from classdojo_preview_skill_sync, though sibling names and the title make this discoverable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the two parameters. It reinforces confirm's semantics with 'explicit confirmation', but it never names previewId or states that it must come from a prior preview — that is only in the title and tool name. Partial compensation only.

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 concrete action — exactly replacing target skills — plus a postcondition ('reads every class back'). This clearly identifies it as the commit/apply step and distinguishes it from classdojo_preview_skill_sync and classdojo_verify_skill_sync.

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 conveys the necessary use conditions: a previously previewed sync and explicit confirmation before any replacement. It does not name alternative tools or say when not to use it, so it stops 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?

Annotations already declare readOnlyHint: true and openWorldHint: true, and the description adds 'without writing data' which aligns with readOnlyHint. The description goes beyond the annotations by specifying exactly what is checked (browser connection, login visibility, available classes). This adds useful behavioral context without contradicting 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 description is a single, focused sentence that front-loads the main verb 'Checks' and specifies exactly what is checked. There is no fluff, redundancy, or unnecessary detail. Every word 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?

Given the tool's simplicity (no parameters, no output schema, read-only annotations), the description is sufficient. It clearly states the tool's scope and intent. An agent can confidently invoke this tool to diagnose the local environment without ambiguity. There is no missing information that would prevent correct usage.

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 has zero parameters, and the schema coverage is 100% (no properties to describe). Per the baseline for tools with no parameters, a score of 4 is appropriate. The description does not need to explain parameters, and it does not introduce any misleading information.

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 the tool's purpose: 'Checks the local browser connection, login visibility, and available classes without writing data.' This uses specific verbs and resources, and implicitly distinguishes it from sibling tools like classdojo_list_classes or classdojo_get_ui_state by focusing on a diagnostic health check. The purpose is unambiguous and immediately actionable.

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 implies this tool is for verifying the local environment (browser connection, login state, class availability) before using other tools, but it does not explicitly say when to use it versus siblings like classdojo_get_ui_state or classdojo_list_classes. There is no mention of alternatives or exclusions, so the guidance is implied rather than explicit.

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 provide readOnlyHint=true and openWorldHint=true. The description's statement 'without changing ClassDojo data' reinforces the read-only nature but adds no new behavioral detail, such as potential side effects, data freshness, or handling of open-world results. It is consistent with annotations but does not enrich them.

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, concise sentence that is front-loaded and free of fluff. It is appropriately brief for a simple read operation, though the extreme brevity contributes to the lack of parameter and usage information. The structure itself is good, but it could be slightly longer to include essential context.

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 single parameter and lack of output schema, the description should at least mention how to obtain classId or what the return format is. It does neither, leaving the tool under-specified. While the operation is simple, the missing parameter semantics and absence of any output hints make it incomplete for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate by explaining classId. It does not mention classId at all, leaving its purpose, format, or source entirely unspecified. The agent cannot know that classId identifies the class without external context, which is a critical gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('reads') and resource ('class roster') and explicitly notes it does not change data, which conveys a read-only intent. However, it does not differentiate from sibling tools like classdojo_list_classes or classdojo_inspect_workbook, which also involve reading class-related data, so it falls short of 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?

No guidance is provided for when to use this tool versus alternatives. It does not mention prerequisites (e.g., that classId comes from list_classes) or situations where siblings would be more appropriate. The agent is left to infer usage from the name and description 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 'without changing ClassDojo data' phrase is redundant but consistent. The description adds meaningful behavioral detail beyond annotations by specifying exactly what is read: positive and needs-work skills, including points and icons. This is useful given 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. It states the operation, the object, the included fields, and the side-effect profile efficiently.

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 read-only tool with one parameter, the description covers the key behavioral and return-content expectations. It lacks explicit output shape or parameter clarification, but the absence of nested objects and the simple classId parameter make it adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain that classId identifies the class whose skills are read. The parameter name is fairly self-explanatory, but with zero schema coverage the description needed to compensate and did not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Reads') and names the resource: positive and needs-work skills, including points and icons. It clearly distinguishes itself from mutation-oriented siblings like classdojo_apply_skill_sync by explicitly stating it does not change 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?

The description implies use for read-only retrieval of skills and says it does not change data, but it does not explicitly state when to prefer this tool over related siblings such as classdojo_preview_skill_sync or classdojo_apply_skill_sync. Usage context is clear but exclusion criteria are only 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 readOnlyHint annotation covers the non-mutating nature, and the description reinforces this by saying it 'does not dismiss anything'. It adds specific behavioral details about the kinds of dialogs that might block the UI state, which is useful beyond the annotation. No contradiction exists.

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 high information density. The primary action is front-loaded, and the second sentence adds a clarifying negative. No redundant phrasing or 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?

The tool has no output schema, so the description should specify what the return value looks like (e.g., a status string or enumeration). It only says 'reports whether...' without detailing the output format. It also does not cover error scenarios or the meaning of the classId. This leaves the agent uncertain about the operation's result.

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 provides only the name, type, and minLength for classId, with no description. The description does not mention classId at all, so the agent receives no guidance on what the parameter means or how to obtain a valid value. With 0% schema description coverage, the description should compensate but fails to do so.

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 the verb 'Reports' to indicate a read-only status operation on the selected class. It clearly enumerates the possible states (ready, adding students, or blocked) and explicitly states what it does not do (dismiss anything), which differentiates it from other ClassDojo tools that perform mutations.

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 context on when to use it: to check if a class is ready or blocked by a dialog. It also states an exclusion: it does not dismiss anything, implying a separate tool for dismissals. However, it does not explicitly name alternative tools or state when not to use it, 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 readOnlyHint=true, and the description adds the extra guarantee about not transmitting student data, which provides reassurance beyond the annotation. It does not detail the exact report format, but the core behavior is transparent enough for an agent to understand the 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?

One concise sentence that front-loads the action and the key safety property with no fluff or repetition. Every word earns its place, and the structure is clean.

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 inspection tool, the description covers the action and safety guarantee, but it omits how the reported column groups are returned (list, structured object, etc.) and how they should be used with downstream tools like preview_roster_import. Given no output schema exists, this lack of return-format information is a notable 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?

The only parameter, workbookPath, is not described beyond its name, and schema description coverage is 0%. The description does not clarify the expected path format, file type, or how the workbook is accessed, forcing the agent to infer from the parameter name alone. This is a significant gap for a tool with a single 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 action (scan workbook) and outcome (report candidate class, seat-number, and student-name column groups), clearly distinguishing it from import/apply operations. However, it does not explicitly contrast it with verify_roster_against_workbook, so it stops short of 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?

The phrase 'without importing or transmitting student data' implies this is a safe pre-import inspection step, giving context on when it is appropriate. But it does not name sibling tools like verify or preview, nor does it specify when to choose this over them, so usage guidance is only 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 declare readOnlyHint=true and openWorldHint=true, and the description's 'Lists' is fully consistent with a read-only operation — no contradiction. The description adds one useful behavioral detail beyond the annotations: the result scope is tied to a locally connected teacher session. However, it adds nothing about output shape or formatting, so it does only modest work beyond the 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?

A single sentence with no wasted words. It is front-loaded with the verb and noun ('Lists the classes') and defers modifiers until after the main idea. Every element — the three-digit detail, the session scope — earns its place. This is exemplary 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?

For a zero-parameter, read-only list tool with readOnlyHint and openWorldHint annotations, the description covers purpose, scope, and safety. The only missing piece is the exact return format (what a 'three-digit class' looks like in the response), but with no output schema and such low complexity, that omission is minor and an agent can reasonably infer the result shape.

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 zero parameters, there is nothing for the schema to document and nothing the description must clarify about inputs. The rubric baseline for 0 params is 4, and the description still adds value by specifying the scope of the returned data (classes in the local session). This is appropriate; the dimension is effectively satisfied by the absence of parameters combined with the scope qualifier.

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 'Lists' plus the resource 'classes' makes the core purpose unmistakable, and the 'three-digit' qualifier plus the scope phrase 'visible in the locally connected ClassDojo teacher session' sharpen exactly what is returned. It is clearly distinguishable from siblings like classdojo_get_roster (students in a class) and classdojo_get_ui_state (interface state), though the description 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?

The description provides no when-to-use vs. alternative guidance and no exclusions. The phrase 'locally connected ClassDojo teacher session' implies a scope condition (use only when a local teacher session is active), but the agent is left to infer when to pick this over the sibling roster/import/verification tools. No alternative is named anywhere.

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 and openWorldHint=true. The description adds that nothing is sent, which aligns with read-only behavior and adds a useful safety context. However, it doesn't describe the output format or error behavior, so value beyond annotations is modest.

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 19-word sentence that front-loads the core action (reads a local XLSX workbook) and states the result (reports student-name changes before sending). No wasted words.

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 tool with 5 parameters including complex mappings and no output schema, the description is insufficient. It doesn't describe what the report contains, how mappings are used, or what the output looks like. An agent would need to inspect the schema and potentially sibling tools to understand how to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain any of the 5 parameters (workbookPath, sheetNames, studentNameFormat, mappings, includeStudentDetails). The only hint is 'local XLSX workbook' relating to workbookPath. Since the schema itself provides only structural info (types, enums, required), the description fails to compensate for the low coverage.

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 the tool reads a local XLSX workbook and reports student-name changes before sending anything to ClassDojo. This implies a preview action distinct from the sibling apply_roster_import, though it doesn't explicitly name alternatives. The verb+resource is specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'before anything is sent to ClassDojo' conveys when to use this tool (as a preview preceding apply), but it doesn't explicitly name sibling alternatives or exclusions. Usage context is implied rather than explicit.

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 and openWorldHint=true, so the safety profile is structured. The description reinforces the non-mutating behavior ('before any skill is changed') but doesn't add further behavioral detail such as output format or prerequisites.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense, front-loaded sentence with no filler. Every clause earns its place, and the core action and resource are stated 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 read-only preview tool, the description states the input categories, the action, and the timing relative to mutation. It could mention what the preview returns, but with readOnlyHint and a simple compare action, the core invocation 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?

With 0% schema description coverage, the description compensates by mapping rulesSource to 'preset, source class, or inline rule list' and targetClassNames to 'target classes.' It doesn't detail the discriminator or ID format, but those are visible in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Compares') and names the exact subject matter: a preset, source class, or inline rule list versus target classes. The phrase 'before any skill is changed' and the tool's name clearly separate it from apply/verify 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?

The 'before any skill is changed' clause signals this is a pre-check or dry-run, positioning it before classdojo_apply_skill_sync. It doesn't explicitly name alternatives or exclusions, but the intended usage window 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 readOnlyHint=true, and the description reinforces this by stating 'without changing ClassDojo data.' It also adds behavioral detail beyond the annotations by specifying the exact outputs (count, missing, unexpected differences). This provides useful context about what the tool returns without contradicting 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 description is a single, tightly written sentence that front-loads the action and resource, includes the output, and states the non-destructive nature. Every word adds value, and there is no fluff or repetition. It is exemplary in conciseness and structure.

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 tool is moderately complex with four required parameters, including a mappings array, yet the description provides no guidance on constructing them. There is no output schema, so the agent has no information about the report structure beyond a high-level mention of count and differences. Without parameter semantics or output details, the description is incomplete for correct invocation.

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 0% description coverage for its four required parameters, so the description must compensate. It does not mention any of the parameters (workbookPath, sheetNames, studentNameFormat, mappings) except a generic reference to 'a local XLSX workbook.' There is no explanation of how to specify sheets, name format, or class mappings. This leaves the agent guessing about parameter values, which is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('reads') and resource ('ClassDojo roster' and 'XLSX workbook'), and clearly specifies the output ('exact count, missing, and unexpected student-name differences'). It distinguishes itself from sibling tools like preview_roster_import by emphasizing that it does not change data and is a verification, not an import preview. This is a clear, specific purpose that differentiates it from related 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?

The description implies the tool is for comparing a roster against a workbook but does not explicitly state when to use it versus alternatives such as preview_roster_import or apply_roster_import. There is no mention of conditions, prerequisites, or exclusions. The context is clear from the title and description, but explicit routing to alternative tools is absent, leaving usage guidance 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 declare readOnlyHint=true, so 'without changing data' adds no new safety information. The description clarifies that verification means comparing current skills against one of three sources, but this largely restates the rulesSource oneOf in the schema; no side effects, return behavior, or error conditions are disclosed.

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 16-word sentence contains the core verb, scope, sources, and a safety guarantee. No filler or redundancy.

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 tool has no output schema, so the description should describe the comparison result format, but it doesn't. It also leaves targetClassNames semantics and the distinctions among verify/preview/apply implicit, making the definition incomplete for a moderately complex nested-parameter 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 0%, so the description must compensate. It names the three rulesSource variants but doesn't explain targetClassNames (the classes whose skills are checked) or the inner structure of inline skills (category/name/points/iconId). The oneOf details and targetClassNames pattern are left entirely to 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 uses a clear verb ('compares') and resource ('current target skills') and explicitly names the three comparison sources (preset, source class, inline rule list). This distinguishes it from mutation-oriented siblings like classdojo_apply_skill_sync and roster-focused tools like classdojo_verify_roster_against_workbook.

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 read-only note ('without changing data') implicitly separates it from apply_skill_sync, but the description never names alternatives or states when to prefer verify over preview_skill_sync. Usage context is implied rather than explicit, so an agent must infer the choice from sibling names.

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