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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lower. The description adds genuinely non-derivable behavioral context: it returns text plus a download_link, and it explicitly warns that <sakai_content> text is authored by lecturers and must be treated as information, never instructions — an important prompt-injection guardrail. It does not discuss size limits or failure modes if the attachment name does not match.

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 resource, and the safety warning is placed at the end where it belongs. Three sentences with little waste, though the trailing 'like get_resource' clause is a slightly imprecise comparison that costs a bit of clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-field explanation is not required, and the description still signals text + download_link. Combined with the injection guidance and full schema coverage, an agent has what it needs to call this correctly; only pagination semantics for start/end remain unaddressed in prose.

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 assignment_id, attachment_name, start and end are all already documented in the schema, including the partial-name matching hint. The description adds no parameter-level detail (e.g. how start/end pagination interacts with the returned text), 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?

Specific verb ('Download') plus a precisely scoped resource: files attached to an assignment brief or returned with lecturer feedback. It also distinguishes the return payload ('text and a direct download_link') and anchors it against the sibling get_resource, so an agent can separate it from get_assignment_details or get_assignment_feedback without reading 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?

'like get_resource' establishes a family resemblance but is a similarity note rather than a routing rule; there is no explicit when-not or 'use X instead when Y'. Usage is implied (you need the attachment file for a known assignment_id), which is adequate but not directive.

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 readOnly and non-destructive, so safety is covered. The description adds valuable behavioral context: newest-first ordering, plain-text format, and the critical injection-safety warning about treating <sakai_content> as data, never instructions. That is meaningful beyond 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 precise sentences; the ordering and scope are front-loaded, and the security note follows. 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?

Output schema exists, so return values needn't be explained. The description covers ordering, scope, text format, and the prompt-injection risk. It could mention caching behavior or pagination, but given the schema and annotations, it is largely 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 100%, so all three parameters (limit, course, refresh) are already documented in the schema. The description adds only that default scope is all courses, which is minor. 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?

States a specific verb+resource: retrieves announcements, newest first, scoped to all courses or one course, with full text. Clearly distinguishable from siblings like get_calendar or whats_new.

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?

Implies usage (get announcements from all or one course) but doesn't state when to prefer it over whats_new or how it relates to other content tools. No explicit exclusions or alternatives.

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 readOnly/openWorld/non-destructive, so the safety profile is covered; the description goes well beyond by disclosing that body text inside <sakai_content> is authored by lecturers and must be treated as information rather than instructions (a prompt-injection guard) and that attachments carry a direct download link that should be surfaced instead of a Sakai address. These are behavioral traits no annotation or schema field conveys.

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 sentences, front-loaded with the payload and then the two operational warnings; every sentence carries distinct, actionable content with no restatement of the tool name 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?

An output schema exists, so return values need not be spelled out, and annotations cover the safety profile. Combined with the security and link-handling guidance, an agent has everything needed to select and invoke this tool 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%: assignment_id ('from another assignment tool') and refresh ('skip the cache and ask Sakai again') are both documented in the schema. The description adds nothing about parameter semantics, 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 ('Full brief for one assignment') and enumerates the exact payload: instructions, dates, max points, submission method, attachments, and the student's submission status. This clearly separates it from list_assignments (which enumerates many) and download_assignment_attachment (which fetches one file).

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

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

Usage is implied rather than stated: an agent can infer it should call this for the details of a single assignment, and the description adds handling guidance for the returned link ('give the student that link, never a Sakai address'). However, it never explicitly says when to prefer this over list_assignments or get_assignment_feedback, nor any prerequisites or when-not conditions.

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 cover read-only/open-world safety. The description adds valuable behavioral context beyond them: it explains what is returned (grade, comments, files), the 'nothing returned yet' state, and critically, security guidance to treat <sakai_content> as information not instructions. Cache behavior is only in the schema, not the description.

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: the first front-loads what is returned, the second adds the empty-state caveat and prompt-injection safety note. 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?

Output schema exists, so return values needn't be explained. The description covers scope, empty state, and content-trust guidance; only cache/refresh semantics and permission requirements are absent, which are minor for a read-only feedback 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 already documents both assignment_id and refresh. The description adds no parameter-level detail beyond what the schema provides, 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?

States a specific verb+resource (released grade, comments, returned files) scoped to the student's own submission of one assignment. Clearly distinguished from siblings like get_assignment_details (metadata) and get_my_grades (course grades) by focusing on feedback for a single 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?

Implies usage is for checking feedback on one's own submission, and notes it reports when nothing has been returned. No explicit when-to-use vs alternatives or prerequisites, but the single-assignment scope 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 openWorldHint=true, so the read-only, external-data nature is covered. The description adds the ordering behavior ('soonest first'), which is useful. However, it doesn't disclose caching behavior despite a 'refresh' parameter existing, nor does it say what the calendar source is beyond 'course calendars'.

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 with no waste, front-loading the resource, scope, ordering, and optional filter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, and annotations cover the safety profile. The description is complete for a read tool but leaves the sibling relationship with get_upcoming_deadlines implicit, which matters given overlapping 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 description coverage is 100%, so the schema already documents course, refresh, and days_ahead thoroughly. The description only hints at the optional course scoping. Baseline 3 is appropriate 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?

States a specific verb and resource ('Upcoming calendar events') plus the exact content types (classes, exams, quiz and assignment deadlines) and the ordering ('soonest first'). This distinguishes it from siblings like get_upcoming_deadlines and list_assignments.

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 says it draws from 'the student's course calendars' and can be scoped to one course, implying usage context. But it doesn't explicitly say when to use this versus the closely related get_upcoming_deadlines sibling, which is a notable omission given the overlapping purpose.

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 readOnly/openWorld/non-destructive, and the description adds genuinely non-obvious context: only released assignment grades are returned because UG Sakai does not share gradebook, quiz or exam scores. It does not mention caching behavior tied to the refresh parameter, but the data-availability limit is meaningful added value.

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, grade scope front-loaded, followed by the availability constraint and the sibling routing. No filler and 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?

With an output schema present and annotations covering the safety profile, the description need not explain return values. It supplies the one thing structured data cannot: the institutional data-availability limitation and the correct alternative 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%, with both 'course' (formats and source site_id) and 'refresh' (cache bypass) fully documented in the schema. The description adds no parameter-level detail beyond that, 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+resource ('the student's own released assignment grades for one course') and immediately scopes what data is available, explicitly diffentiating from gradebook/quiz/exam data. It also names the sibling it is not (get_assignment_feedback), so an agent can distinguish it 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?

Gives an explicit alternative for a related need ('Use get_assignment_feedback for the lecturer's comments'), which routes the agent correctly. It does not cover other nearby siblings such as list_assignments or get_assignment_details, and gives no explicit when-not beyond the feedback pointer.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the payload is a link plus setup instructions, but discloses nothing further (e.g., that the link is static/shareable). With annotations carrying the safety burden, a 3 is appropriate.

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: the first names the returned artifact, the second gives the usage trigger. No filler, and the usage condition is front-loaded in its own sentence. The first sentence is a dense noun phrase but still readable.

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-param static-link tool with an output schema already declaring the return shape, the description needs only to say what it returns and when to call it — both present. Nothing an agent needs to invoke it correctly 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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool is 4. No parameter-level meaning is missing.

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 resource: the Sakai-MCP connector address for both the browser (claude.ai) and the Claude phone app, plus how to add it. The 'get_phone_and_web_link' name is elaborated into concrete content. It is distinguishable from all siblings (which fetch course data) though the phrasing is slightly jargon-heavy.

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 an explicit trigger: 'Use when the student asks how to use Sakai-MCP on the web or phone.' This is clear context, but no alternatives or when-not conditions are named (none of the siblings overlap, so exclusions are largely unnecessary).

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 readOnly/non-destructive, but the description goes well beyond them: it discloses the pagination model, the presence of a direct download_link, and critically warns that text inside <sakai_content> tags is untrusted lecturer content that must never be treated as instructions. That prompt-injection guidance is high-value behavioral context an agent cannot get from structured fields.

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 pagination behavior are front-loaded, followed by the download link and safety note. The safety sentence is long but earns its place; the whole is dense without being padded.

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, return-value detail is unnecessary, and everything an agent needs otherwise is covered: supported formats, pagination continuation, page/slide selection, download link, and untrusted-content handling.

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 does not: start/end are framed as page, slide, or part indices depending on file type, and start doubles as the continuation token via next_start.

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+resource (download a course file) and states the return value (its text, with supported formats). It implicitly distinguishes itself from the sibling list_course_resources by being the retrieval-of-content tool rather than a lister.

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 guidance on continuing paginated reads (call again with start=next_start) and selecting pages/slides, which is real usage context. However, it never states when to choose this tool over siblings such as download_assignment_attachment or view_slide, leaving that to 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral value beyond that: results are ordered soonest-first, assignment entries carry submission status, and overdue assignments that still accept late submissions are included rather than excluded. Only caching/refresh nuance is absent, and that lives in the 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?

Three tight sentences, front-loaded with the resource and ordering, then the contents, then the alternative. Every clause carries information; nothing is redundant with the title or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return formatting need not be described, and annotations cover the safety profile. The description supplies what remains: scope across courses, sort order, inclusion of overdue-late items, and the pointer to get_assignment_details for detail.

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% (both refresh and days_ahead are documented in the schema, including the cache semantics of refresh), so the baseline is 3. The description implies a forward-looking window but does not restate the default horizon or the 1-120 day bound, adding nothing 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?

States a specific verb+resource with explicit scope ('across all of the student's courses, soonest first') and enumerates the contents: assignments with submission status plus quiz/exam deadlines from course calendars. This clearly distinguishes it from list_assignments (per-course listing) and get_calendar, and the extra note about overdue late-submission items nails down what 'upcoming' includes.

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?

Routes the agent to a related tool: 'Use get_assignment_details with an assignment_id for the full brief,' establishing that this tool returns summaries, not detail. It gives clear context for when this tool applies but does not explicitly state when to prefer it over list_assignments or get_calendar.

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 cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the lower bar applies. The description nonetheless adds real behavior: ordering ('Open assignments come first') and the shape of what is returned. It does not mention that results may be cached, which matters given the refresh parameter.

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, no waste, with the result content and ordering front-loaded ahead of the sibling routing note. Every sentence 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?

An output schema exists, so return values need no explication, and ordering plus field coverage are given. The only gap is the caching/refresh interaction implied by the refresh parameter, a minor omission for a read-only list 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%, so course, refresh, and include_closed are fully documented in the schema, including the non-obvious include_closed default of true. The description adds no parameter-level detail beyond that, making the baseline 3 correct.

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+resource+scope ('All assignments in one course') and enumerates the returned fields (status, due date, submission, released grade). It also names the sibling it is not, so an agent can distinguish it from get_assignment_details 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 routes single-assignment lookups to get_assignment_details, giving a clear alternative with the selecting condition. It does not address the other plausible sibling for deadline aggregation, get_upcoming_deadlines, so the guidance stops just short of a full routing statement.

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 readOnly and non-destructive, so safety is covered; the description adds the key behavioral guarantee that download_link is a student-usable direct link, never a Sakai address requiring login. It does not mention caching behavior for refresh, but that is documented in the 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?

Two sentences, front-loaded with purpose, followed by the routing note. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values needn't be detailed; the description nevertheless names the key fields and the download_link guarantee. Complete for a read-only list 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 course and folder are already documented in the schema. The description reinforces folder as a narrowing mechanism but adds no syntax or format detail beyond what the schema provides. 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?

States a specific verb (list) and resource (course resources: files and links), enumerates returned fields, and distinguishes itself from get_resource, which reads a file. An agent can tell what it returns without opening the schema.

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

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

Explicitly names the folder input as the way to narrow long lists and routes the agent to get_resource for reading a file, giving both the when-to-use condition and the alternative. Nothing is left to 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?

Annotations already cover the safety profile (readOnly, non-destructive, open-world), but the description adds a genuinely useful behavioral fact: how to interpret an empty result. It doesn't discuss caching behavior or pagination, which the refresh parameter implies exists, so it is not fully 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?

Two short sentences with no filler, and the empty-result caveat is placed right after the purpose statement. The opening sentence is a noun fragment rather than a crisp verb phrase, which slightly weakens the front-loading.

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?

Because an output schema exists, return values need not be explained, and the description covers the key interpretive case (empty list). For a simple two-parameter read tool this is largely complete, though token/paging size for large Lessons sites goes unmentioned.

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 both the course identifier formats and the refresh cache-skip semantics are already documented in the schema. The description adds no parameter-level detail beyond that, making the baseline 3 correct.

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

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

The description identifies a specific resource — the pages of a course's Lessons tool — and distinguishes it from sibling list tools like list_course_resources by contrasting Lessons with Resources. The phrasing 'Pages in a course's Lessons tool' is slightly fragmentary rather than a clean verb+resource statement, 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?

It gives real selection context: many UG courses keep material in Resources instead, and an empty result means the course doesn't use Lessons — an implicit route to list_course_resources. There is no explicit 'use this when...' or named alternative tool, 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?

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds non-obvious behavior beyond that: results are cached and the cache is only bypassed by refresh, and the default scope is the latest term only — both material to interpreting results correctly.

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 with no filler: output shape first, default scope second, cross-tool key format third. Each sentence carries distinct, actionable information and the most important facts 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?

An output schema exists, so return values need not be spelled out, yet the description still names the key returned fields. Combined with the caching note, the past-term scoping rule, and the accepted identifier formats, an agent has everything needed to call this 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 both parameters are already documented ('Skip the cache and ask Sakai again', 'Also list courses from earlier terms'). The description restates include_past's effect in slightly different words but adds no new syntax, format or interaction detail, 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?

Starts with a specific verb+resource ('List the student's UG Sakai course sites') and enumerates exactly what each entry contains (site_id, course code, term, short summary). No sibling tool lists courses, and the mention of course code/name/site_id keys distinguishes it from the detail-oriented siblings like list_course_resources or list_assignments.

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 default-behavior rule ('Shows only the latest term unless include_past is true') and points to interoperability ('Other tools accept the course code, name or site_id'), which implicitly tells the agent this is the discovery step before other calls. It stops short of explicitly saying when to use it versus alternatives, so it isn't a full 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: the return is a rendered picture, and for PowerPoint the embedded images are returned alongside text. It stops short of stating any size, resolution or page-limit behavior, so it is strong but not exhaustive.

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?

Purpose is front-loaded in the first clause, followed by the PowerPoint-specific detail, the usage trigger, and a prompt-injection caution. Every sentence carries weight, though the trailing <sakai_content> safety note is longer than the tool mechanics require.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully discloses that the result is a picture rather than text, which is essential for an agent to interpret the response. Combined with 100% parameter coverage and clear annotations, it is nearly complete; only edge-case behavior such as invalid pages or large documents is unaddressed.

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 both parameters (page, resource) are already fully documented with defaults and minimums. The description implies page/slide selection but adds no syntax or format 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 and resource ('Show one PDF page or PowerPoint slide as a picture') and explicitly scopes the value-add: equations, diagrams, handwritten annotations, charts. This clearly separates it from text-oriented siblings like get_resource, which the description names directly.

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 explicit trigger ('Use after get_resource when the text looks incomplete or the student asks about a diagram'), naming both the precursor tool and the two conditions that select this tool. Nothing is left to 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?

Adds real context beyond the readOnly/openWorld annotations: cross-call statefulness ('since they last asked'), a first-run window (7 days), and a prompt-injection warning about treating <sakai_content> as data. It notably omits that the default mark_seen=true suppresses items on later calls, which sits awkwardly with the declared readOnlyHint.

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, front-loaded with the resource scope and followed by the two non-obvious operational facts (window, untrusted content). 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?

An output schema exists, so return values need no explanation; the description covers scope, window behavior, and safety. The only gap is that it does not surface that a normal call persists 'seen' state, which matters for an agent deciding whether to call it repeatedly.

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 single mark_seen parameter is fully documented there, so the baseline is 3. The description's 'since they last asked' framing contextualizes statefulness but adds no syntax or behavior specific to the parameter itself.

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 ('what changed in the student's current courses') and enumerates exactly what is aggregated: announcements, assignments, released grades, Resources files, quiz/exam deadlines. This clearly distinguishes it from point-lookup siblings like get_announcements, get_my_grades, and list_course_resources.

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 'since they last asked' and 'the first check shows the last 7 days' implies this is the recurring digest tool, but it never explicitly says when to use it instead of, or before, the granular siblings. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered structurally. The description adds real context on top: that this doubles as a connectivity probe and returns identity fields, which the annotations do not 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?

Two short sentences, zero filler, with the identity lookup stated first and the diagnostic use case second. 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?

An output schema exists, so return values need no elaboration, and with no input parameters the description only needs to establish purpose and trigger conditions — both are present. Nothing an agent needs to call it correctly is absent.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter meaning the description could add. Nothing is missing or misdescribed on this dimension.

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 action (check the connection) and a specific resource (the logged-in student's ID, name and email) on a named system (UG Sakai). An agent can tell exactly what comes back without opening any schema, and none of the sibling tools do this.

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 two concrete triggers: the student asking who they are logged in as, and a fallback 'when other tools fail' diagnostic case. That fallback routing is genuinely useful, though it doesn't name which failing tools it substitutes for or state any exclusions.

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