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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It explicitly states 'WRITES TO MOODLE and emails everyone enrolled,' which reveals the mutation and the mass-email side effect. The caution to check wording also adds context. It doesn't detail reversibility or permissions, but the core side effects are transparent.

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 two sentences with zero waste. The first sentence front-loads the critical side effects, the second gives the purpose and a user-safety caveat. Every word earns its place, and it's structured for quick scanning.

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 mutation tool with no output schema, the description is adequately complete. It states the action, the side effect, and a necessary user check. It doesn't mention prerequisites like permissions or how to obtain course IDs, but those are either implied or covered in the schema. The omission of an explicit 'who can call this' is 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?

The schema description coverage is 100%, with all four parameters individually described. The tool description does not add additional parameter semantics beyond what the schema provides, which is expected given the high coverage. It doesn't compensate for any gaps, but none exist here, so a 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?

The description clearly states the action: 'Post an announcement in the course's news forum' and adds that it emails everyone enrolled. It specifies the verb and resource, distinguishing it from the sibling 'announcements' which likely reads announcements. However, it doesn't explicitly name alternatives, 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?

The description provides no guidance on when to use this tool versus alternatives. It includes a caution to check wording with the user, but that is a pre-call confirmation, not a selection criterion. No exclusions or alternative tools are mentioned, leaving the agent to infer when to use it.

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

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

No annotations are present, so the description must carry the behavioral burden. It discloses scope and sort order, and 'Recent announcements...' plausibly implies a read operation, but it does not explicitly state side-effect safety, failure behavior, or auth requirements. For a simple list tool, the ordering disclosure is the main added value, but the absence of annotations limits confidence.

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 compact sentence front-loads the core resource and order and contains no filler. It is appropriately sized for a tool with two parameters.

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-list tool, scope and order are conveyed, and the schema documents parameters. However, with no annotations and no output schema, the description leaves return-item shape and failure/edge-case behavior implicit, so completeness is adequate but not strong.

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%; courseid is documented as 'Course id from my_courses' and limit as 'How many to return.' The description adds no parameter-specific meaning beyond the schema, so the baseline 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 states the resource ('announcements in the course's news forum') and the ordering ('newest first'), clearly signaling a list/read operation. It is not a tautology and is distinguishable from the sibling announce, though it lacks an explicit verb like 'list' and does not name the sibling alternative.

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 about when to choose this over siblings such as announce or course_contents. The 'newest first' phrasing implies a read-only listing, but there are no explicit conditions, 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only lists data fields; it does not state whether this is a read-only operation, any authentication requirements, pagination behavior, or what the response structure looks like. For an un-annotated tool, this leaves critical operational behavior undocumented.

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, compact sentence with no redundant padding. It front-loads the resource and enumerates key fields efficiently. However, its noun-phrase structure sacrifices explicit action clarity, which prevents a perfect score for 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?

Given the simplicity (one parameter, no output schema) and the absence of annotations, the description is partially adequate. It tells the agent the fields of an assignment but does not explicitly state that the tool returns a list of assignments for the course, nor any output shape or edge cases. Without an output schema, this omission leaves a real gap for correct invocation and interpretation.

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 sole parameter 'courseid' is documented as 'Course id from my_courses' in the schema. The description adds no new parameter-specific meaning beyond 'in a course', so the schema does the heavy lifting. This matches the baseline score of 3 for high schema 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 names the resource ('Assignments in a course') and lists concrete attributes (assignid, due date, max grade, brief), which clearly identifies what is returned. However, it lacks an explicit verb such as 'list' or 'get', so the tool's action is inferred rather than stated. The mention of 'submission tools need' hints at its role but does not fully differentiate it from siblings without inference.

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 explicit guidance on when to use this tool versus alternatives. The phrase 'the assignid the submission tools need' implies it should be used before submissions, but it does not state prerequisites, exclusions, or alternative tools. Agents are left to infer usage context from sibling names 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?

With no annotations, the description must disclose behavior. It indicates the output is what students see in order, but it doesn't state whether the operation is read-only, any permission requirements, or behavior on invalid input. It adds some context about the output perspective but lacks safety and error details.

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 two short sentences, front-loading the resource and adding a clarifying note about cmid. There is no redundancy 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?

For a one-parameter tool with no output schema, the description gives the essential purpose but omits details about the response structure, such as whether sections include names or activities are nested. It's adequate but could be more complete about the returned data 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?

The single parameter courseid is fully described in the schema ('Course id from my_courses'), so the description adds no additional parameter meaning. The mention of 'cmid' is about the output, not the parameter, so the description does not enhance parameter understanding.

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

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

The description clearly identifies the resource as course sections and modules, and adds the ordering and student perspective. It is distinct from sibling tools like assignments or gradebook, though it doesn't explicitly state the action (e.g., 'retrieves'), it's implied by describing the content.

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 others, nor any mention of alternative tools or conditions. The description only states what the tool returns, leaving the agent to infer when it's appropriate.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals a 'shows' behavior in the second sentence, but the first sentence 'Grade items' hints at a mutating action, and there is no explicit statement that this tool does not write grades. Safety-critical behavior, such as whether it is strictly read-only and what happens with insufficient permissions, is left ambiguous.

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 two sentences with no filler, stating scope first and then the result. It is well-structured, though resolving the 'Grade items' ambiguity with a word like 'View' would have made it more precise without adding length.

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 low-complexity tool with only two documented parameters, the description covers the main invocation context and what the result conveys. However, with no output schema and no annotations, it would be more complete if it explicitly stated that this is a read-only lookup and described how empty marks are represented in the 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?

Schema description coverage is 100%, so the schema already documents courseid and userid including the '0 for everyone visible' default. The description mostly restates that scope and adds little beyond what the schema provides, so the baseline of 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?

The description identifies the resource (course grade items) and the action is reasonably clear: it shows which items have marks and which are still empty, for one student or everyone visible. It is not a tautology, but the verb 'Grade' in 'Grade items' can briefly be read as writing marks rather than viewing them, and it does not explicitly differentiate from grade_submission.

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

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

The description gives useful scoping context: a courseid is required and userid can target one student or 0 for everyone visible. However, it never explicitly says when to use this tool versus siblings like grade_submission or missing, so the usage is only implied rather than clearly delineated.

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

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

With no annotations provided, the description carries full responsibility for exposing side effects, and it does so well. It explicitly warns 'WRITES TO MOODLE, visible to the student,' notes that the grade uses the assignment's own scale, and states 'This overwrites whatever mark and comment were there before.' This gives the agent the critical destructive-mutation context.

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 compact and well-structured: the mutation warning is front-loaded in ALL CAPS, followed by the core action, then key behavior detailscherry, and finally a user-confirmation directive. Every sentence adds necessary operational or risk information without 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 six-parameter mutation tool with no output schema, this description is complete enough for an agent to invoke it correctly. It covers the primary parameters (grade, feedback), the special -1 sentinel value, the overwrite side effect, student visibility, and the need for user confirmation. It also cross-references assignments for scale context.

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 already documents all six parameters with full coverage, so the baseline is 3. The description adds meaningful value by explaining that the grade is on the assignment's own scale, that -1 leaves the mark unchanged, and that feedback overwrites prior comments. This goes beyond the schema's per-parameter descriptions, though it does not add detail for every 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 uses a clear verb-resource pairing: it 'Put[s] a mark and written feedback on one submission' and explicitly says it 'WRITES TO MOODLE, visible to the student.' This distinguishes it well from sibling listing/inspection tools like submissions, submission_status, and gradebook.

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 clear context for when to use the tool: grading a single submission with a mark and feedback. It also adds the practical guardrail to 'confirm the numbers with the user first.' However, it does not explicitly name alternative tools or state when not to use this tool instead of gradebook or other related functions.

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

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

No annotations are provided, so the description carries the full burden. It states the operation is a listing and supports filtering, but does not mention the return format, whether it is read-only, or any side effects. For a simple enumeration tool this is acceptable, but it could be more explicit about output structure.

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 that are dense with information: purpose, filtering, and intended usage. The most important information is front-loaded, and every word contributes value. No fluff 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?

For a simple tool with one optional parameter and no output schema, the description covers all essential aspects: what it returns, how to filter, and when to use it. Minor gaps like explicit return format are not critical given the simplicity. The description is sufficiently complete for an agent to invoke 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 100%, so the parameter's description ('Substring filter, empty for all') already conveys the meaning. The tool description adds examples (assign, forum, grade) and usage context, but does not fundamentally extend the parameter semantics beyond what the schema provides. Baseline of 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?

The description clearly states the tool lists all web-service functions available to the token, with optional substring filtering. It explicitly distinguishes itself from sibling tools by framing it as a discovery mechanism ('find out what this Moodle actually allows') rather than a specific action.

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 explicit guidance on when to use it: before assuming a tool is missing, and how to filter. It does not explicitly state when not to use it, but the sibling tools (whoami, my_courses, etc.) make the purpose unambiguous. The guidance is clear and contextual.

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

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

No annotations are provided, so the description must convey behavioral traits. It implies a read-only query by saying 'The list to look at,' but does not explicitly state it is non-destructive or mention any side effects, prerequisites, or limitations. For a simple query, this is adequate but not thorough.

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 two short sentences, front-loading the core purpose and adding a practical use case. It is concise with no fluff, though it could be slightly more explicit about the verb.

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 (2 parameters, no output schema), the description covers the purpose and typical usage. However, it does not specify the format of the returned list (e.g., student names vs. IDs) or any ordering/pagination, leaving some ambiguity for an agent about the exact output.

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 'assignid' and 'courseid' already described as IDs from respective tables. The tool description adds no extra semantic context beyond what the schema provides, so it meets the baseline for full schema 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 resource: students enrolled in the course who have not submitted the assignment. While it lacks an explicit verb like 'list' or 'get', the phrasing 'The list to look at' implies a read operation that returns such students. It is distinct from sibling tools like 'submissions' or 'submission_status' because it focuses specifically on missing submissions.

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 a clear usage context: 'on the morning after a deadline.' This tells the agent when to invoke this tool. However, it does not explicitly state when not to use it or mention alternatives, but the trigger scenario is concrete and useful.

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

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

No annotations are provided, so the description must carry the behavioral burden. It states that the tool returns the current account's enrolled courses, which implies a read-only lookup, but it does not explicitly say the operation has no side effects or mention authentication/permission requirements.

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

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

The description is a single sentence with no filler. It front-loads the resource and scope, and the final clause adds the most useful cross-tool context: course IDs are needed by other tools.

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 tool with no output schema, the description provides the essential integration fact: returned course IDs are required by other tools. It does not specify the exact return shape (e.g., array of objects), but the tool is simple enough that this is 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?

The tool has zero parameters and an empty input schema, so there are no parameter semantics for the description to clarify. Per the baseline rule for tools with no parameters, a 4 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?

The description clearly identifies the resource ('courses'), the scope ('this account'), and the key output ('id every other tool needs'). It distinguishes my_courses from siblings like whoami and list_functions without requiring the agent to inspect 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?

The phrase 'with the id every other tool needs' strongly implies this is the prerequisite lookup tool before calling course-scoped siblings. It provides clear context for when to use it, though it does not explicitly name alternatives or state 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?

With no annotations, the description carries the transparency burden. It discloses the output contents and the semantic of userid, but does not mention output format, pagination, permission requirements, or whether all enrollment roles are included. This is useful but incomplete.

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

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

Two tight sentences with no filler. The output-relevant facts come first, and the downstream-consumer note is a single purposeful clause.

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 list tool with no output schema, naming the returned fields and connecting them to grade_submission gives an agent enough to call it correctly. Minor gaps such as response structure or pagination exist but are not critical for this simple 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% and courseid is already documented as 'Course id from my_courses'. The description adds no additional parameter semantics 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?

The description clearly identifies the resource (students enrolled in a course) and the returned information (role, email, last access). It lacks an explicit action verb such as 'list' but is specific enough to distinguish the tool from submissions/gradebook siblings and ties its output to grade_submission.

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

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

It provides clear context: the returned userid is what grade_submission expects, so an agent can infer this is the step to call before grading. It does not name alternatives or state 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?

With no annotations, the description carries the full burden. It implies a read-only list operation but does not explicitly state that it does not modify data. It also does not disclose potential performance considerations, pagination, or required permissions. The description is purely about what it returns, not about how it behaves or any caveats.

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 that efficiently conveys the core purpose and key output fields. It is concise and to the point, though it could be slightly more structured, but overall it earns a high score for conciseness.

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 lists the returned fields (userid, status, timestamp, file names with URLs, online text), which compensates for the lack of an output schema. However, it does not mention the only_submitted parameter's effect or any limitations such as pagination. Given the tool's simplicity, it is mostly complete, but some usage context is 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 already provides full descriptions for both parameters (assignid and only_submitted), so the description adds no extra meaning. It implicitly references the assignment via 'one assignment' but does not elaborate on parameter usage or formats. Since schema coverage is 100%, the baseline 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 clearly states the tool's purpose: to list who submitted what for a single assignment, including status, timestamp, file names with URLs, and online text. The scope 'for one assignment' helps distinguish it from course-level or student-level tools, but it does not explicitly name sibling tools like submission_status or missing to differentiate.

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 tool versus alternatives. It does not mention that submission_status might be for a single student's status or that missing might be for missing submissions. No when-to-use or when-not-to-use information is given, leaving the agent to infer based on the name and parameters.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does disclose the main return contents (submission state, lock status, grade, feedback, extension), which is helpful, but it does not explicitly state that the operation is read-only, nor does it cover error behavior, permission requirements, or what happens when no submission 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?

The description is a single, dense sentence that front-loads the core concept and lists the specific status components. There is no filler or redundant restatement of the tool name.

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 covers what an agent needs to know about the returned information: submission state, locking, grade, feedback, and extension. Since there is no output schema, this enumeration is valuable, but it does not address edge cases like missing submissions or access failures, leaving it slightly incomplete.

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

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

The input schema already describes both parameters clearly (userid as student id, assignid as assignment id), reaching 100% schema description coverage. The description adds only general context about a single student and assignment, so it provides no meaningful parameter-level 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 clearly identifies the tool's scope: it provides a comprehensive status snapshot for one student on one assignment, including submission state, lock status, grade, feedback, and extension. It distinguishes itself from sibling tools like submissions or gradebook by emphasizing the singular student/assignment view, though it lacks an explicit verb like 'get' or 'retrieve.'

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 'for one student on one assignment' implies the intended use case, distinguishing it from broader list-oriented siblings like submissions or gradebook. However, it does not explicitly state when to prefer this tool over alternatives or mention any exclusions or prerequisites.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It states that the tool returns ownership info, the Moodle target, and the count of allowed functions, which are the key behaviors. It does not mention potential failure modes or side effects, but for a read-only diagnostic tool this is adequate. The description adds meaningful context beyond the empty 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 exceptionally concise, using two short sentences. The first sentence front-loads the core functionality, and the second adds a clear usage directive. No redundant or filler content—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 has no parameters, no output schema, and a simple diagnostic role, the description fully covers what an agent needs: the purpose, the usage timing, and the expected output categories. It is complete for the tool's complexity.

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, so the schema is trivially complete. The description does not need to explain parameter semantics since there are none. Baseline for 0 params is 4, and the description appropriately omits parameter details.

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 function: it identifies the token owner, the target Moodle instance, and the count of allowed web-service functions. This is specific and distinct from sibling tools like list_functions or my_courses, which have different purposes. The phrase 'Who the token belongs to' directly addresses identity and 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?

The instruction 'Run this first when something fails' provides a clear context for when to use the tool—during troubleshooting. It implies a diagnostic role but does not explicitly name alternatives or state when not to use it. However, the guidance is actionable and sufficient for an agent to decide to invoke it first on failure.

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