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

Annotations already declare readOnlyHint and openWorldHint, and the description adds the 'newest first' ordering and the created-or-modified filter semantics. It does not mention pagination, limits, or return format, so it adds context but not a rich behavioral profile.

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-load the action and scope, then state the optional filter and read-only nature. There is no fluff or repetition; 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 two-parameter read-only list, the description plus fully documented schema provide enough to select and invoke the tool correctly. Sorting and filtering behavior are stated; return shape is not, but 'list announcements' makes the expected output reasonably inferable.

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

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

Schema description coverage is 100%, with both parameters already well documented via examples and accepted formats. The description adds no additional parameter meaning beyond what is already in the schema, so it stays at the baseline of 3.

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 ('announcements for one Blackboard course'), and ordering ('newest first'). This clearly distinguishes the tool from siblings like get_recent_updates and list_courses by resource type 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 description gives useful scope context ('one Blackboard course') and the optional 'since' filter, but it does not explicitly say when to choose this tool over siblings like get_recent_updates, nor does it name alternatives or exclusions. Usage is implied rather than spelled out.

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

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

The description repeats 'Read-only', which is already declared in annotations, and adds a few useful behaviors: attachments return local file paths (not files) and rubric inclusion is conditional ('when available'). However, it does not disclose other behavioral aspects like performance cost or external dependencies, and openWorldHint remains unexplained. The added value beyond annotations is modest.

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

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

Two sentences with no filler. The first sentence front-loads the full scope of returned data; the second provides immediate usage guidance. Every word contributes value, and the description is appropriately sized for a read-only aggregate tool.

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 no output schema, the description adequately enumerates the return contents, covering all major elements an agent would need to expect. It does not mention error conditions or edge cases, but for a read-only package tool, this is near-complete. The parameters are fully covered by the schema, so the description alone is sufficient to call the 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 coverage is 100%, and the schema already documents both parameters, including nuances like course_id being required only for bare content ids. The description adds no additional meaning to the parameters, so scoring at 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 clearly states the tool returns a unified package of assignment data, enumerating specific elements: instructions, due date, points, rubric, attachments with local paths, grade/status, and announcements. It distinguishes itself from low-level calls by framing it as an aggregate, making its purpose unmistakable.

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 instructs to 'use this instead of many low-level calls', providing clear guidance on when to prefer this tool over alternatives. However, it does not specify scenarios where a low-level tool (e.g., get_grades for just a grade) would be more appropriate, so it lacks exclusion 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?

The description adds behavior beyond the readOnlyHint annotation: results are combined and deduplicated from course content, the gradebook, and the calendar. It also explicitly restates the read-only nature. It does not cover pagination or rate limits, but with readOnlyHint=true the safety profile is already established.

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 fluff. The core behavior and data sources are front-loaded, and the optional scoping is stated compactly. 'Read-only.' is redundant with the annotation but harmless.

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

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

For a read-only list tool with fully documented optional parameters and no required arguments, the description is mostly complete: it names the resource, the sources, deduplication, and optional filters. A small gap is the absence of any return-shape hint or ordering behavior, but this is not critical given the tool's simple listing purpose.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds a helpful grouping ('scope to one course and/or a due-date window') but does not deepen the meaning of include_status or the ISO date format beyond what the schema provides. This meets the baseline for fully documented schemas.

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') and resource ('assignments and assessments with due dates'), and adds how it behaves: combined and deduplicated across three Blackboard sources. This clearly distinguishes it from siblings like get_grades, get_course_content, and get_announcements.

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

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

The description implies the tool is the unified assignment-list entry point and mentions optional course/date scoping, but it does not explicitly say when to prefer get_assignments over similar siblings like get_upcoming_work or get_assignment_context. The usage context is clear but exclusions and alternatives are not 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses where files are saved (~/.blackboard-mcp/downloads), emphasizes that nothing is sent anywhere, and notes that small text files include a text excerpt. It also states the side effect happens only when this tool is called. This is strong behavioral transparency for a download tool.

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

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

The description is three sentences with no filler. The main action and return value are front-loaded, followed by useful side-effect and privacy details. The final 'Read-only.' is redundant with the annotation but does not harm 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?

With no output schema, the description correctly explains the primary return value (local path) and the exception for small text files (text excerpt). It also covers the download location and privacy behavior. It does not describe error cases or exact output structure, but this is sufficient for an agent to select and invoke the 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%, and the schema already documents each parameter with source and example. The tool description adds little parameter-specific meaning beyond the return behavior. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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 ('Download'), a specific resource ('a course file from Blackboard'), and the key outcome ('return its local path'). This clearly distinguishes it from sibling tools that list courses or content but do not download files.

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 and schema provide clear context for when to use this tool: after obtaining course_id from list_courses and content_id from get_course_content or get_assignments. It explains the optional file_id for multi-attachment content items. It does not explicitly say when not to use it, but the file-download purpose is distinct enough among siblings.

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, and the description reinforces the read-only nature. It adds meaningful behavioral detail beyond annotations by disclosing that hierarchy is only expanded 'a couple of folder levels' and that folder_id allows deeper navigation. It does not mention pagination or result size limits, but with annotations covering the safety profile this is sufficient.

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 concise sentences with no filler. It front-loads the primary purpose, then adds the key behavior and a read-only note. 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?

The description is complete enough for correct invocation: it identifies the required course_id, the optional folder_id, the expected content types, and the hierarchy expansion behavior. With no output schema, it could have briefly described the returned item shape, but the openWorldHint and the tool's name cover enough ground.

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 both course_id and folder_id clearly. The description adds the phrase 'go deeper into one folder' for folder_id, which slightly clarifies its purpose, but this is largely redundant with the schema's 'list instead of the course root.' 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 begins with a specific verb and object: 'List a course’s content items' and enumerates the item types (folders, documents, files, assignments, tests, links). This makes the tool's purpose immediately clear and helps distinguish it from sibling tools like get_grades or get_announcements.

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

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

The description gives clear context for when to use this tool: to browse a course's content hierarchy. It also explains how to navigate deeper with folder_id. It does not explicitly mention exclusions or alternatives such as 'for assignment details, use get_assignments,' 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?

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=true, and the description reinforces this with 'Read-only.' It adds the default time window (last 7 days) and the exact activity types covered, which is useful context beyond the structured data. No contradictions with 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 concise sentences front-load the primary scope ('Recent Blackboard activity across all courses') and immediately enumerate content types, ending with a short read-only note. Every word 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?

The description fully covers what the tool returns (activity types), the default behavior, and the safety profile. It omits response structure (e.g., grouping, ordering) and doesn't discuss pagination, but with a single optional parameter and no output schema, this is largely sufficient for an agent to call it correctly.

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

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

The schema covers the single 'since' parameter fully (ISO date, default), and the description repeats the default. With 100% schema coverage, the description adds no additional parameter semantics beyond what the schema already provides, so the 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 ('Get recent...') and defines the scope precisely: activity across all courses since a time point, enumerating the four types of updates included. This clearly distinguishes it from sibling tools like get_announcements or get_grades, which focus on single types.

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

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

The description implies a broad-overview use case (recent activity across all courses) but does not explicitly contrast with sibling tools or state when to prefer this over specialized ones. No exclusion or alternative routing is provided, leaving the agent to infer.

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 added 'Read-only' is redundant rather than informative. The description does add useful behavioral context: results are cross-course, limited to upcoming items, and sorted by due date. It stops short of describing pagination, response format, or whether assignment details are included.

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 scope and ordering, then a purpose statement. The only redundancy is 'Read-only', which duplicates annotations, but the overall length is appropriate 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?

For a simple read-only tool with one optional parameter, the description fully conveys the resource, the scope, the ordering, and the intended use case. The schema covers the parameter, and annotations cover safety. Nothing critical 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 sole parameter is fully documented in the schema with type, bounds, description, and default behavior. The description adds no extra meaning around 'days', but with 100% schema coverage the parameter semantics are already sufficient.

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 action (get) on a specific resource (upcoming assignments and assessments), narrows scope to ALL Blackboard courses, and adds organization by due date. It clearly answers what the tool does and is easily distinguishable from siblings like list_courses or get_grades.

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

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

It explicitly frames this as the one call for 'what do I have due?', giving clear context for when to use it. However, it doesn't name alternatives or state when NOT to use it, such as when results for a single course are needed.

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.