Server Quality Checklist

Tool Scores

• blackboard_get_gradesC
  2.9/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden. It implies a read-only operation but discloses no additional behavioral context such as authentication needs, rate limits, return format, or side effects. The basic 'get' semantics are clear, but nothing beyond that.

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

  Conciseness4/5

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

  The description is a single, front-loaded sentence with no redundant words. It conveys the core purpose efficiently, though it is slightly under-specified rather than overly verbose.

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

  Completeness3/5

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

  For a simple tool with one well-defined parameter, the description covers the basic action but omits details about the return payload or potential errors. With no output schema, the description should compensate, and it does not fully do so, but the tool's low complexity keeps it minimally viable.

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

  Parameters3/5

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

  The schema documents the lone parameter (courseId) with type, pattern, and description, yielding 100% coverage. The description adds nothing about the parameter, so the baseline score of 3 is appropriate per the rubric.

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

  Purpose4/5

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

  The description uses a specific verb ('Get') and identifies the resource ('all grades') with clear scoping ('for the current student in a course'). This distinguishes it from siblings that deal with assignments or feedback, though it does not explicitly name alternative tools.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. It does not mention scenarios where a sibling like get_assignment_feedback or list_attempts would be more appropriate, nor any prerequisites or context for invoking it.

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

• blackboard_list_attemptsB
  3.3/5.0
  Behavior2/5

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

  No annotations are provided, and the description does not disclose any behavioral details beyond the action itself, such as return format, pagination, or read-only nature. It is a minimal statement with no added context.

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

  Conciseness5/5

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

  The description is a single, clear sentence with no redundant information. It is concise and to the point.

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

  Completeness3/5

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

  While the two parameters are fully described, the absence of an output schema and lack of any information about the returned structure or behavior leaves some gaps. For a simple list operation, it is adequate but not fully complete.

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

  Parameters3/5

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

  Both parameters have full schema descriptions, and the tool description does not add any additional meaning beyond what the schema already states. Baseline 3 is appropriate given the 100% schema coverage.

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

  Purpose5/5

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

  The description clearly states the action (List), the resource (submission attempts), and the scope (specific assignment/gradebook column). This distinguishes it from sibling tools like list_assignments 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.

  Usage Guidelines2/5

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

  No guidance is provided on when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or comparison with sibling tools like list_assignments or get_grades.

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

• blackboard_get_courseA
  3.5/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden. It states 'Get details' but does not disclose whether the operation is read-only, what 'details' includes, any authentication requirements, or potential errors. The description adds no behavioral transparency beyond the tool's name and basic purpose.

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

  Conciseness5/5

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

  The description is a single concise sentence, front-loaded with the action and resource, and provides an example. No filler or redundant information; every word earns its place.

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

  Completeness3/5

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

  The tool is simple with one parameter, no output schema, and no annotations. The description is minimally adequate but does not explain what 'details' means or what the return structure might be. Given the lack of output schema, the description should offer more context about the response, making it borderline but not severely lacking.

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

  Parameters3/5

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

  Schema description coverage is 100% (courseId is fully described with pattern and example). The tool description repeats the same example '_529580_1' without adding new semantic value. Per rubric, baseline is 3 when schema covers parameters fully.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Get details of a specific course by its Blackboard ID'. The verb 'get' and resource 'course' are specific, and the phrase 'specific course' distinguishes it from siblings like blackboard_list_courses which retrieves multiple courses.

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

  Usage Guidelines3/5

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

  The description implies usage when you have a specific Blackboard course ID, but it does not explicitly state when to use this tool over alternatives or mention that list_courses should be used to obtain IDs. No exclusions or alternative references are provided, so it's only implied context.

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

• blackboard_download_file_urlA
  3.6/5.0
  Behavior3/5

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

  Annotations already disclose readOnlyHint=false and openWorldHint=true. The description adds the destination directory context, but lacks behavioral details such as overwrite behavior, download size limits, or authentication requirements. It provides some transparency beyond annotations but not rich context, earning a mid-range score.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that front-loads the action and key resource details. Every word earns its place, with no redundancy or irrelevant information.

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

  Completeness4/5

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

  For a relatively simple download operation, the description covers the core purpose adequately, supported by a complete schema and annotations. It lacks explicit mention of return values or error behavior, but those are not critical given the tool's simplicity. The absence of output schema is partially mitigated by the clarity of the action.

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

  Parameters3/5

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

  The input schema has 100% coverage with clear descriptions for all three parameters (url, filename, outputDir). The description does not add significant meaning beyond the schema; it only implies the destination directory, which the schema already covers via outputDir's description. Baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description uses the specific verb 'Download' and identifies a precise resource ('Blackboard bbcswebdav file') and destination ('protected Campus download directory'), which clearly distinguishes it from sibling download tools like blackboard_download_attachment and blackboard_download_feedback_file. The name itself ('download_file_url') reinforces the unique purpose.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives such as blackboard_download_attachment. It does not state prerequisites, exclusions, or specific scenarios, leaving the agent to infer usage solely from the schema and name.

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

• blackboard_system_versionA
  3.6/5.0
  Behavior2/5

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

  No annotations are provided, so the description must carry the full burden of behavioral disclosure. The verb 'Get' implies a read-only operation, but the description does not disclose response format, error behavior, or any side effects. For a zero-parameter tool this is a minor gap, but the description adds little beyond the basic purpose.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that immediately conveys the purpose. There is no wasted language, and it is appropriately sized for such a simple tool.

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

  Completeness4/5

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

  For a zero-parameter tool with no output schema, the description is nearly complete. It fully identifies the operation and resource. A higher score would require richer context (e.g., response format), but given the tool's simplicity, the description is adequate.

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

  Parameters4/5

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

  The input schema has zero parameters and schema description coverage is 100% (vacuously). With no parameters to document, the description does not need to provide additional semantic context. The baseline score of 4 applies.

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

  Purpose5/5

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

  The description clearly states the tool gets the Blackboard Learn server version, using a specific verb (Get) and resource (server version). It is unambiguous and easily distinguished from sibling tools like blackboard_whoami or course-specific tools.

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

  Usage Guidelines2/5

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

  The description gives no explicit guidance on when to use this tool versus alternatives. There is no mention of prerequisites or context, and while its purpose is clear, the 'when to use' is only implied by the tool name and description.

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

• blackboard_get_assignment_feedbackA
  3.7/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral disclosure burden. It states the tool shows score, instructor comments, and feedback files for graded submissions, which is useful. However, it does not explicitly state it is read-only, nor does it clarify how feedback files are represented or whether ungraded submissions are omitted.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the key action and resource. No filler or redundant wording; every phrase adds value.

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

  Completeness3/5

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

  With no output schema, the description gives a high-level summary of the return content (score, comments, feedback files) but lacks structural detail. It is adequate for a simple read tool but leaves ambiguity about the exact response format and relationship to other feedback-related tools.

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

  Parameters3/5

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

  The only parameter, courseId, is already fully described in the schema with a pattern and description. The tool description does not add additional meaning about the parameter's usage or role within the tool.

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

  Purpose5/5

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

  The description clearly identifies the action (get), resource (assignment feedback/scores), and scope (all assignments in a course). It distinguishes itself from siblings like get_grades or download_feedback_file by combining feedback, scores, and attached files into one tool.

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

  Usage Guidelines3/5

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

  The description implies usage for retrieving professor feedback and scores, but it does not explicitly state when to prefer this over alternatives like blackboard_get_grades or blackboard_download_feedback_file. No exclusions or conditional guidance are provided.

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

• blackboard_list_announcementsA
  3.7/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It indicates a read-only action ('list') and adds a behavioral constraint ('recent'), but does not define what 'recent' means (time window, count, ordering) or disclose pagination/limits. It is transparent about being a read operation but leaves key behavioral details unstated.

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

  Conciseness5/5

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

  The description is a single, clear sentence that immediately conveys the tool's purpose. No wasted words; it is concise and front-loaded.

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

  Completeness3/5

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

  Given the tool's simplicity (one param, no output schema), the description is adequate but with gaps: it does not explain the meaning of 'recent', expected output format, or usage guidelines. It is not rich enough to fully compensate for missing annotations, but it is sufficient for a basic list tool.

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

  Parameters3/5

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

  Schema description coverage is 100% (courseId described as 'Blackboard course ID' with pattern), so the schema already documents the parameter. The description adds no additional meaning about the parameter beyond 'for a course', which is already implicit. Baseline 3 applies.

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

  Purpose5/5

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

  The description uses a specific verb 'list' and a clear resource 'announcements' scoped to 'a course', which distinguishes it from sibling tools like list_assignments or list_contents. It is immediately obvious what the tool does.

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

  Usage Guidelines3/5

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

  The description implies usage ('list announcements for a course') but provides no explicit guidance on when to choose this tool over alternatives like list_contents or list_assignments, nor does it mention exclusions or prerequisites. It has clear context but lacks comparative guidance.

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

• blackboard_list_assignmentsA
  3.7/5.0
  Behavior3/5

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

  With no annotations, the description carries full burden. It discloses the content returned (due dates, scores, submission status) but omits details like return format, pagination, ordering, or any required permissions. Since 'List' implies a read-only operation, it isn't misleading, but it lacks deeper behavioral context.

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

  Conciseness5/5

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

  The description is a single, clear sentence that packs the essential action and scope without waste. Every word contributes to understanding the tool's purpose.

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

  Completeness3/5

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

  The tool is simple (one parameter, no output schema), but the description does not mention the output shape, pagination, or any limitations. While the core purpose is clear, the absence of an output schema places more burden on the description to explain return values, which it only partially does.

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

  Parameters3/5

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

  The schema provides 100% coverage for the single parameter courseId, including a pattern and description. The tool description adds no additional semantic meaning beyond implying a course context, so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  Clearly states the action (list) and resource (assignments and tasks in a course), and specifies the included data fields (due dates, scores, submission status). This distinguishes it from sibling tools like blackboard_list_announcements or blackboard_get_grades.

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

  Usage Guidelines3/5

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

  The phrase 'in a course' implies the tool is intended for course-scoped listing, but there is no explicit guidance on when to use it vs. alternatives such as blackboard_list_attempts or blackboard_get_grades. No exclusions or alternative tool mentions are provided.

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

• blackboard_whoamiA
  3.7/5.0
  Behavior3/5

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

  The description implies a read-only operation on the authenticated user's info, but it does not explicitly state that it makes no modifications, nor does it describe any potential errors or response details. With no annotations, the description carries the burden, but the simplicity of the tool limits the need for extensive disclosure.

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

  Conciseness5/5

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

  The description is a single, concise sentence that directly states the tool's purpose without unnecessary words.

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

  Completeness3/5

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

  The tool is simple, but the description is minimal and does not explain what 'student info' includes or what the response structure is. Given the absence of an output schema, this is a minor gap, but the description is sufficient for basic understanding.

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

  Parameters4/5

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

  The tool takes zero parameters, so the description has nothing to add beyond the schema, which is already empty. According to baseline, a score of 4 is appropriate.

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

  Purpose5/5

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

  The description uses the specific verb 'Get' and a clear resource ('currently authenticated UPC student info'), which clearly distinguishes it from sibling tools like list_courses or get_course. It is specific and unambiguous.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives, nor any exclusions. It simply states the operation without context.

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

• blackboard_list_attachmentsA
  3.9/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. 'List' implies a read-only operation, and the explicit mention of supported file types adds useful behavioral context. However, it does not disclose return structure, error behavior for unsupported types, or pagination, leaving some gaps.

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

  Conciseness5/5

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

  The description is two concise sentences with no extraneous information. It front-loads the core purpose and adds the file-type detail efficiently.

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

  Completeness3/5

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

  For a simple list tool with full schema coverage, the description is mostly adequate. However, since there is no output schema, the description does not explain what the returned list contains (e.g., filenames, URLs) or how unsupported file types are handled, which is a notable gap for an agent.

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

  Parameters3/5

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

  The input schema already provides 100% coverage with descriptions and patterns for both parameters (courseId and contentId). The description adds no additional parameter-level detail, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description clearly states the tool lists file attachments for a course content item, with a specific verb and resource. It also distinguishes itself by specifying the supported file types (x-bb-file and x-bb-document), differentiating it from sibling tools like blackboard_download_attachment.

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

  Usage Guidelines4/5

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

  The description provides clear context on when to use the tool by specifying that it works for x-bb-file (REST API) and x-bb-document (embedded files in body HTML). While it does not explicitly name alternatives or exclusions, the file-type scope gives the agent sufficient guidance for selection.

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

• blackboard_download_attachmentA
  4/5.0
  Behavior4/5

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

  Description adds meaningful behavioral context beyond annotations: files are stored in a 'protected Campus download directory' and 'outputDir may be a relative subdirectory only'. This complements the readOnlyHint=false annotation by specifying the side effect location. It does not mention overwrite behavior or return values, but the key destination constraint is disclosed.

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

  Conciseness5/5

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

  Two concise sentences, front-loaded with the main action, and every word earns its place ('protected Campus download directory' and 'relative subdirectory only' are essential constraints). No verbose or redundant phrasing.

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

  Completeness4/5

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

  Given 5 parameters, full schema coverage, and no output schema, the description provides adequate context for invocation: it specifies source, destination, and a key parameter constraint. However, it lacks guidance on when to call this after blackboard_list_attachments and does not mention what the tool returns, leaving minor gaps.

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

  Parameters3/5

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

  Schema covers all 5 parameters with descriptions (100% coverage), including details like 'Relative subdirectory inside ~/Downloads/campus-cli'. Description only reiterates the outputDir constraint without adding new semantic information beyond the schema, so baseline 3 is appropriate.

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

  Purpose5/5

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

  Description clearly states the action 'Download a file from a course content item' and destination 'protected Campus download directory'. This distinguishes it from sibling tools like blackboard_download_file_url by specifying the source (course content item) and target (protected download directory). Tool name reinforces attachment context.

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

  Usage Guidelines3/5

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

  No explicit when-to-use or alternative tool guidance is provided. The description gives a clear context (downloading from course content) but does not contrast with siblings like blackboard_download_file_url or blackboard_download_feedback_file, leaving selection to the agent's inference from the name and description.

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

• blackboard_list_coursesA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. The verb 'List' implicitly indicates a read-only operation, and the 'current student' qualifier adds scope context, but it does not disclose potential behaviors such as pagination, return field structure, or authentication requirements. It is neither misleading nor rich, so 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.

  Conciseness5/5

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

  The description is a single, clear sentence with no unnecessary words or redundancy. It is front-loaded with the verb and resource, making it maximally concise.

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

  Completeness4/5

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

  Given the tool's low complexity (zero parameters, no output schema), the description is largely complete. It states exactly what it does. However, it could hint at what fields the returned course objects contain, but this is not critical for a simple list tool.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema provides 100% coverage by definition. The description adds no parameter information, but none is needed. The baseline for zero-parameter tools is 4, and the description meets it.

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

  Purpose5/5

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

  The description uses the specific verb 'List' and clearly identifies the resource 'all enrolled courses for the current student', distinguishing it from blackboard_get_course which presumably targets a single course. The scope is explicit and unambiguous.

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

  Usage Guidelines3/5

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

  The description does not explicitly state when to use this tool versus alternatives like blackboard_get_course or blackboard_list_contents. The usage is implied by the name and description but not explicitly differentiated, so it falls into 'implied usage'.

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

• blackboard_download_feedback_fileA
  4.2/5.0
  Behavior3/5

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

  Annotations already mark it as non-read-only, non-idempotent, and open-world. The description adds the experimental status and version limitation, which is useful context. It does not disclose the download destination or potential side effects, but the schema parameters hint at that.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the purpose, and the second sentence provides the key workflow instruction. No wasted words; the experimental caveat is integrated naturally.

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

  Completeness4/5

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

  Given the tool's complexity (6 params, 4 required, no output schema), the description explains the crucial workflow dependency (blackboard_get_assignment_feedback) and the potential unavailability. It does not describe the return value or output path, but the schema covers the output parameters, making it sufficiently complete.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the provenance of fileId, attemptId, and columnId from blackboard_get_assignment_feedback, and notes the filename defaults to the name in feedbackFiles, which goes beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool downloads a feedback file attached to a graded attempt, identifies the exact source of the fileId, and distinguishes this from generic attachment/download tools by referencing the feedback workflow. The experimental note adds clarity about its reliability.

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

  Usage Guidelines4/5

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

  It explicitly tells the agent to use the fileId from blackboard_get_assignment_feedback, establishing a clear usage context. However, it does not explicitly differentiate from sibling tools like blackboard_download_attachment, though the feedback-specific focus implies when to use it.

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

• blackboard_list_peopleA
  4.2/5.0
  Behavior4/5

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

  Without annotations, the description carries the behavioral disclosure burden. It transparently reveals a key privacy behavior: 'Contact email is only included for instructors — classmates' emails are never returned, even with search.' This adds meaningful context beyond basic listing, though it does not describe all return fields or error handling.

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

  Conciseness5/5

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

  Three concise, front-loaded sentences. The first identifies the subject, the second gives the primary use case, and the third covers search and the important privacy caveat. No wasted words.

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

  Completeness4/5

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

  Given there is no output schema, the description partially explains return content (instructors and classmates, contact email for instructors only) but does not explicitly list all fields. The main functionality and notable edge case (email privacy) are covered, making it reasonably complete for a simple list tool.

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

  Parameters3/5

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

  Schema coverage is 100% with both parameters described. The description adds minimal extra value: 'Pass search to look up one person by name' restates the schema's 'Name of one person in the course.' The description does not introduce syntax or format details beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool lists instructors and classmates of a course, with a specific use case: resolving an internal user id into a person's name. It distinguishes itself from sibling tools by focusing on course people, not courses, announcements, or assignments.

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

  Usage Guidelines4/5

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

  Provides clear usage context: 'Use it to resolve an internal user id into a person's name' and 'Pass search to look up one person by name.' It gives practical guidance on when to use the tool, though it does not explicitly mention when not to use it or name alternatives.

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

• blackboard_raw_apiA
  4.2/5.0
  Behavior4/5

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

  The description adds a behavioral detail beyond the annotations by stating that modifying methods require direct user confirmation. This is valuable context for an agent, as it indicates an additional authorization step for non-read-only operations. The annotations already declare destructiveHint=true, so the description complements rather than contradicts them.

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

  Conciseness5/5

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

  The description is two short sentences that convey the core function and a critical safety caveat. There is no fluff or redundant information; every word earns its place.

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

  Completeness4/5

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

  Given the tool's raw nature, the schema covers parameter details and annotations cover safety, the description provides a sufficient warning about mutating methods. While it does not explain response formats or error handling, those are implicitly raw API responses, and the description is adequate for a pass-through tool. A slightly higher score would require explicit guidance on endpoint paths or response expectations.

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

  Parameters3/5

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

  The input schema has 100% parameter descriptions, so the description does not need to repeat parameter details. The baseline of 3 applies here since the description adds no additional parameter semantics beyond what the schema already provides.

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

  Purpose5/5

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

  The description clearly states 'Call a public Blackboard REST API endpoint,' which specifies the action (call) and the resource (public Blackboard REST API endpoint). This distinguishes it from the sibling tools, which provide high-level operations like listing courses or retrieving user info. The name 'blackboard_raw_api' also reinforces this distinct purpose.

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

  Usage Guidelines4/5

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

  The description provides a clear usage caveat: 'Modifying methods require direct user confirmation through MCP elicitation.' This tells the agent when extra steps are needed for destructive operations. While it does not explicitly mention alternatives or say 'use this when no specific tool exists,' the 'public endpoint' qualifier and the existence of specialized siblings imply its role as a fallback or raw access tool.

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

• blackboard_list_contentsA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden. It discloses that the tool lists content and that parentId navigates into subfolders. While it doesn't mention return format or pagination, the tool is a straightforward read operation with no side effects, so the disclosure 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.

  Conciseness5/5

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

  Two concise sentences: the first states the main purpose, the second explains navigation. No filler or redundant information.

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

  Completeness4/5

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

  The tool is simple, and the description covers purpose and navigation. It doesn't detail what 'content items' include (e.g., files, folders, assignments), but this is a minor ambiguity given Blackboard's standard terminology and the presence of distinct sibling tools.

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

  Parameters4/5

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

  Schema coverage is 100%, with both parameters well described. The description adds value by explicitly saying 'Use parentId to navigate into subfolders', which clarifies the parentId parameter's purpose beyond the schema description.

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

  Purpose5/5

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

  The description uses a specific verb ('List') and resource ('content items') with scope ('inside a course or folder'). It clearly distinguishes itself from sibling tools like list_courses, list_announcements, and list_people by focusing on course content structure.

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

  Usage Guidelines4/5

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

  The description provides clear usage context: when to list contents and how to navigate into subfolders using parentId. It does not explicitly mention alternatives or exclusions, but the guidance is adequate for the tool's simple navigational purpose.

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

• blackboard_save_attempt_draftA
  4.4/5.0
  Behavior4/5

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

  Annotations already signal write behavior (readOnlyHint=false), but the description adds valuable context: the attempt remains open with status InProgress and no submission occurs. This clarifies the draft behavior beyond mere flags.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core purpose and followed by clarifying exclusions. Every sentence adds value without redundancy.

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

  Completeness4/5

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

  The tool has no output schema, so return values are not needed. The description explains core behavior, state implications, and the exclusion of submission, which is sufficient for a draft-save tool. Slight gaps exist around failure conditions but are not critical for this operation.

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

  Parameters3/5

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

  Schema coverage is 100%, so parameters are well-documented. The description adds a high-level mapping ('text, attached files, or both') but does not go beyond the schema's existing parameter explanations, matching the baseline for full schema coverage.

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

  Purpose5/5

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

  The description clearly states the tool saves progress on an assignment attempt without submitting it, specifying text, attached files, or both. It explicitly distinguishes from the sibling submit tool, making its purpose unambiguous.

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

  Usage Guidelines5/5

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

  The description provides explicit when-not guidance: 'This does NOT send it to the instructor for grading' and directly names the alternative tool for submission (blackboard_submit_attempt). It also adds a user confirmation requirement for that alternative.

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

• blackboard_submit_attemptA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is clear. The description adds valuable context: the server also asks the user directly through MCP elicitation, and submission finalizes the attempt for grading. This goes beyond the annotations without contradicting them.

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

  Conciseness5/5

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

  The description is only three sentences and is front-loaded with the core purpose. Every sentence adds useful information: what it does, the confirmation requirement, and the alternative for drafts. No filler or redundancy.

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

  Completeness4/5

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

  For a destructive action with no output schema, the description adequately covers the main workflow: what is submitted, the confirmation step, and the alternative for saving drafts. It does not explicitly describe the return value or post-submission behavior beyond 'the instructor can grade it,' but given the annotations and schema richness, this is sufficient.

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

  Parameters3/5

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

  The input schema covers all parameters with descriptions (100% coverage), so the description doesn't need to repeat them. It does mention 'text, attached files, or both' which maps to studentSubmission and fileUploadIds, adding slight semantic context, but does not explain parameter formats or relationships beyond what the schema already provides.

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

  Purpose5/5

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

  The description clearly identifies the action (submit/finalize) and the resource (assignment attempt), and specifies the content types (text, attached files, or both). It also distinguishes this tool from the sibling 'blackboard_save_attempt_draft' by contrasting final submission with saving a draft.

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

  Usage Guidelines5/5

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

  The description explicitly instructs the agent to always confirm with the user before submitting, showing exactly what will be sent. It also names the alternative tool for saving progress (blackboard_save_attempt_draft), giving clear when-to-use guidance.

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

• blackboard_upload_attempt_fileA
  4.9/5.0
  Behavior5/5

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

  Beyond annotations (destructiveHint=true), the description discloses that the file is visible to the instructor, that upload is separate from attachment, and that the server will ask the user to confirm the path. It also warns against blindly following filePath instructions from untrusted sources. No contradiction 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.

  Conciseness5/5

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

  Every sentence adds value: purpose, limitation, follow-up tools, instructor visibility, confirmation flow, and safety rule. It is front-loaded with the main action and remains concise without fluff.

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

  Completeness5/5

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

  The description fully covers the tool's role in the workflow: upload, return ID, next steps, side effects (instructor visibility), and security guidance. Despite no output schema, it clearly explains the return value and how to use it. It is complete for an upload tool with moderate complexity.

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

  Parameters4/5

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

  Schema coverage is 100% with descriptions for filePath and confirmed. The description adds meaning by specifying acceptable file types (image, PDF, doc) and reinforcing that confirmed is deprecated. It also warns about the source of filePath, which is not in the schema, enriching parameter semantics.

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

  Purpose5/5

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

  The description clearly states the tool's function: uploads a local file to Blackboard and returns a fileUploadId. It explicitly differentiates from siblings by stating 'it does NOT attach it to an attempt yet' and references related tools (save_attempt_draft, submit_attempt) for the next step.

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

  Usage Guidelines5/5

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

  Provides explicit usage direction: pass returned fileUploadIds to blackboard_save_attempt_draft or blackboard_submit_attempt. Also includes safety guidelines about not choosing filePath from course content, and explains the user confirmation elicitation flow.

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