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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description reinforces read-only. The description adds useful structure context about the 'links' field and newest-first ordering. It doesn't disclose pagination behavior or result limits, so it's adequate but not rich.

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

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

Three short sentences, front-loaded with the core purpose, followed by the optional filter then the link-handling note. Zero waste.

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

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

Covers purpose, ordering, filtering, and link navigation for a read-only list tool with full schema coverage and no output schema. Pagination/limits are unaddressed but are minor gaps for a read operation.

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 course_id and since are fully documented in the schema. The description reiterates the date-filtering semantics but adds no syntax or format detail beyond the schema. 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 (list announcements) scoped to one Blackboard course, with ordering (newest first) and an explicit filtering option. An agent can distinguish it from siblings like get_course_content or get_assignments immediately.

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?

Provides clear context: filter to items created/modified after a date, and routes to read_link for opening links inside an announcement. It doesn't explicitly state when NOT to use it (e.g., across multiple courses, for content types other than announcements), so it's not 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 and openWorldHint, so 'Read-only' is redundant. What the description genuinely adds is the status vocabulary: in_progress means started or saved as a draft and NOT handed in, and unknown must never be treated as missing work. That prevents a costly misinterpretation. It does not cover auth requirements, rate limits, or response size.

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?

Content enumeration is front-loaded in the first sentence, then the status glossary, then the read-only note. Dense with no filler, though the single long opening sentence packs a lot before the agent reaches the operational status guidance.

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

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

For an aggregation tool with no output schema, the description compensates by itemizing exactly what comes back (instructions, rubric, attachments, links, grade, status, announcements) and disambiguating the status enum values. An agent needs nothing further to call it and interpret 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% and both parameters (course_id, assignment_id) are documented there, including the <course_id>:<content_id> format. The description adds no parameter-level detail beyond what the schema provides, 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?

Names a specific verb+resource ('one package describing a Blackboard assignment') and enumerates its contents: instructions, due date, points, rubric, attachments, links, grade, submission status, announcements. An agent can immediately distinguish it from get_assignments (a list) or get_attachment (a single 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?

Explicitly tells the agent to prefer it over 'many low-level calls' and routes link handling to the sibling read_link by name. It gives clear usage context but stops short of stating when not to use it (e.g. when only the due date is needed, get_upcoming_work may suffice).

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 and openWorldHint, so the "Read-only" sentence is largely redundant. The description does add genuine behavioral context beyond annotations: the result is merged and deduplicated across three upstream sources, which tells the agent to expect canonicalized output rather than raw per-source records.

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

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

Three tight sentences: what it returns and from where, then the optional scoping, then the safety profile. Nothing is repeated and the most distinctive information (deduplication across sources) leads.

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 should ideally hint at the shape of returned items (fields, ordering, status presence), which it does not. Everything needed to invoke the tool correctly is present, though, so the gap is modest.

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

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

Schema description coverage is 100%, so all four parameters are already fully documented, including the Syracuse-timezone semantics and the include_status cost/"unknown" caveat. The description only restates course and due-date scoping at a high level, adding no syntax the schema lacks, 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 ("List assignments and assessments with due dates") and adds a distinctive mechanism (combined and deduplicated from course content, gradebook, and calendar) that separates it from get_course_content or get_grades. It stops short of naming the closest siblings, get_upcoming_work and get_assignment_context, so an agent must still infer the boundary.

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?

"Optionally scope to one course and/or a due-date window" implies when the filters matter, but there is no explicit guidance on when to prefer this tool over get_upcoming_work or get_assignment_context, which appear to overlap. Usage is implied 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 and openWorldHint, yet the description still adds real value: the save location (~/.blackboard-mcp/downloads), per-format extraction semantics (pages, speaker notes, CSV per sheet), pagination via next_offset, and the privacy note that nothing is sent anywhere. Only 'Read-only' is redundant with 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?

Front-loaded with the core action and return shape, then format specifics and pagination. Four sentences, all relevant, with no filler; slightly dense but nothing that should be cut.

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 carries the return-value burden and does so: it describes the text payload, the saved path, per-format structure, and how to continue long files. An agent can call this correctly and interpret the result without further documentation.

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 parameters are already documented; the description goes further by explaining the offset/next_offset continuation loop and the multi-file case (file_id/file_name from available_files). It adds semantics the schema cannot, though it references a 'next_offset' field not present in the input 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 ('Download') and resource ('a course file ... from Blackboard') plus the return form (text contents + local save path). This is clearly distinguishable from siblings like read_link or get_course_content, which fetch pages/links rather than file bodies.

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

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

Gives clear operating context: the supported file types, the local path where files land, and the pagination contract ('pass next_offset back as offset to keep reading'). It never names when to prefer this over a sibling such as read_link, so it stops short of explicit alternatives/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?

The readOnlyHint annotation covers safety, and the description goes beyond it by disclosing the lazy-expansion behavior (only a couple folder levels returned, folder_id required for deeper traversal) plus the structure of each item's 'links' array. This is real behavioral context not present in the annotations, though it doesn't discuss result size, limits, or error cases.

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 what is returned, then traversal mechanics, then next-step tools. Every sentence earns its place with no 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?

With no output schema, the description still conveys the shape of returned items and their links, and points to read_link/get_attachment for consuming them. It is nearly complete for an agent's needs, though it does not mention pagination, item counts, or ordering.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema doesn't: folder_id is framed as a way to 'go deeper into one folder' relative to the auto-expanded root, which clarifies the traversal semantics rather than just restating the param.

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 (a course's content items) and enumerates the item types returned (folders, documents, files, assignments, tests, links), which distinguishes it from siblings like get_assignments and get_announcements. An agent can tell what this returns without opening a 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?

Clearly explains the traversal model — hierarchy is auto-expanded a couple levels and folder_id drills deeper — and routes to the right siblings for continuation (read_link for links, get_attachment for files). No explicit 'when not to use' or coverage of how it relates to get_assignments/get_grades, but the context is strong.

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

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

The annotations already declare readOnlyHint and openWorldHint, and the description adds meaningful behavioral context: results are scoped to grades visible to the signed-in student and include feedback and grading status. This goes beyond the annotation by clarifying the visibility/auth boundary, though it omits details like pagination or possible empty results.

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 no filler; the core purpose and returned fields are front-loaded, and the visibility note is placed second. 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?

For a simple read-only tool with one parameter and no output schema, the description adequately covers what the agent needs to know: what is returned, whose grades, and the visibility constraint. No critical information is missing 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 provides 100% coverage for course_id, including format and an example. The description adds only minor context by framing the course as the grade source, so it meets the baseline but does not significantly enrich 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 names a specific verb ('List'), a specific resource ('the student's own grades for one Blackboard course'), and enumerates the returned fields. This clearly distinguishes it from siblings like get_assignments or get_course_content, which cover different course 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 makes it clear the tool is for retrieving a single student's own grades for a specific course, which implies when to use it. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to select it appropriately.

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 and openWorldHint, so the 'Read-only' clause is largely redundant, but the description adds real behavioral value by disclosing that it reports only *changed* items and grades on *changed* gradebook items, plus announcement links. It omits any note on result volume, ordering, or pagination.

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

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

One dense sentence with the aggregation scope front-loaded, followed by a short qualifier. Every clause contributes (scope, time window, contents), and there is no filler.

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

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

For a one-optional-parameter read tool with no output schema, the description adequately covers what is returned and the default time window. Minor gaps are the treatment of 'current courses' (enrollment scope) and result ordering or size limits.

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

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

Schema coverage is 100% and the single 'since' parameter is fully documented with format and default in the schema. The description restates the default but adds no syntax or edge-case detail beyond it, 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 (gets/aggregates) and resource (recent Blackboard activity across current courses), then enumerates exactly which activity types are captured: announcements, content changes, assignment changes, and gradebook changes. This aggregate scope cleanly distinguishes it from the single-resource siblings get_announcements, get_grades, and get_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 time window is explained ('since a point in time, default last 7 days'), which implies the tool is for a recent-activity sweep, but no alternative or exclusion is named. It never says when to prefer this over get_announcements/get_grades or how to follow up after receiving results, leaving routing 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?

Goes well beyond the readOnlyHint annotation: it discloses sort order, the window boundary ('end of the last day, Syracuse time'), inclusion of recently overdue unhanded-in work, and an interpretation rule for the 'unknown' status ('never treat unknown as missing work'). That last point materially changes how an agent should reason about the results.

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

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

Front-loaded with the core purpose, and the routing statement follows immediately. The trailing 'Read-only' repeats the readOnlyHint annotation and is the one sentence that does not fully earn 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 no output schema, the description carries the burden of explaining returns, and it does: due-date ordering, submission status, and the full status vocabulary with edge-case handling. Minor omissions remain (result size limits or pagination), but an agent has what it needs to call and interpret 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?

The single 'days' parameter is fully described in the schema, so the baseline is 3. The description adds genuine meaning by specifying that the window terminates at the end of the last day in Syracuse time, which clarifies how the integer is actually interpreted.

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 plus scope: 'Upcoming assignments and assessments across ALL Blackboard courses, sorted by due date, with submission status.' The ALL-courses scope and the 'what do I have due?' framing distinguish it from course-scoped siblings like get_assignments and get_course_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?

Explicitly positions itself as 'the one call to answer "what do I have due?"', which is clear routing guidance. It also notes it recovers recent unsubmitted items from the past few days. It does not name an alternative tool or state when NOT to use it, 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 declare readOnlyHint=true, so the 'Read-only' sentence adds little beyond the annotation. The description does add value by specifying that only 'currently visible' courses are returned, and that the output consists of course ids used by other tools. This goes beyond the structured annotations, though it does not clarify open-world semantics explicitly.

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

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

Three short sentences with the primary action and scope front-loaded, followed by purpose and read-only status. Every sentence earns its place with no redundant or filler wording.

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, the description is complete: it names the resource, institutional context, output type (course ids), and why that output matters. The absence of an output schema is mitigated by the explicit statement that it returns course ids. Minor ambiguity around 'currently visible' is acceptable given the tool's simplicity.

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

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

The input schema has no properties, so the baseline is 4. The description does not need to explain parameter meanings because there are none; it appropriately focuses on output and purpose instead.

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 ('List'), resource ('courses'), and scope ('student’s currently visible Blackboard (Syracuse University)'). It also says the output is course ids needed by every other blackboard tool, which distinguishes it as the foundational listing tool among the get_* 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 description clearly implies usage context: call this first to obtain course ids needed by other tools. However, it does not explicitly name sibling alternatives or state when not to use it, so it falls just 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 declare readOnlyHint=true and openWorldHint=true, but the description adds crucial context: it states it 'never submits, joins, or types anything' and explains pagination behavior with next_offset. It also notes limitations like YouTube refusing transcripts. The main omission is that it doesn't describe error conditions or rate limits, but for a read-only tool with annotations, this is well-covered.

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

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

The description is dense but front-loaded with the core action and supported types. It could be slightly trimmed, but every sentence contributes information about capabilities, input sources, or constraints. It remains focused despite its 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?

Given the complexity of resolving various link types, the description provides a comprehensive list of supported content, input sources, access restrictions, pagination details, and note about no output schema. It fully equips an agent to invoke the tool correctly, with no significant gaps.

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

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

Schema coverage is 100%, so the schema fully documents all three parameters. The description mentions next_offset and offset in its pagination note, and implies course_id via the access constraint, but does not add syntax or format details beyond the schema. 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 (open) and resource (a link posted in Blackboard), and enumerates the content types it resolves (Google Docs, Slides, PDFs, etc.). This clearly distinguishes it from siblings like get_attachment or get_course_content, which reference links but do not open them.

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

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

Explicitly specifies the source of its inputs ('Links come from the "links" field of get_course_content, get_announcements and get_assignment_context') and the access constraint ('Only links that appear in the student's own courses can be opened'). This provides clear when-to-use versus when-not-to-use guidance without relying on inference.

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