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

Annotations declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to repeat that this is a read-only operation. The description adds value by specifying the content types (grades, content, announcements, due-date reminders) and the ordering (newest first). It also implies that the stream is aggregated across all courses)Skip the fact that it may be cached (which is hinted by the flushCache parameter). This is useful context beyond annotations; the only minor gap is not explicitly stating that it can be cached, but the parameter hints at it.

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: one that states the tool's output and one that gives a use case. Both sentences are information-dense and front-loaded with the key facts (content types, ordering). No unnecessary detail, and the use case is a nice addition that doesn't waste space.

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 that the schema covers parameters 100%, the annotations declare it's read-only and open-world, and the tool has no output schema, the description is quite complete. It tells the agent what the tool returns (recent grade postings, new content, etc.), how it orders (newest first), and when to use it. Minor omissions could include pagination behavior or exact date range limits, but these are not critical given the tool's simplicity and annotation coverage. A 4 is justified.

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%, meaning the schema already documents both parameters (limit and flushCache). The description does not add any additional parameter semantics beyond what the schema provides Sell the description's purpose is not about parameters; it's about the tool's overall behavior. The schema provides reasonable descriptions for both parameters, so the description doesn't need to compensate. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it returns the Ultra activity stream, which includes recent grade postings, new content, announcements, and due-date reminders across all courses, newest first. It uses a specific verb ('list' is implied by 'activity stream') and clearly distinguishes from siblings like bb_unread_counts or bb_announcements, which are more specific. The description also provides a use case ('what changed recently?'), making the tool's purpose immediately clear.

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 explicitly states when to use this tool: it's a good single call for 'what changed recently?' queries. It also provides context that it aggregates recent activity across all courses, which implicitly differentiates it from tools like bb_announcements (specific to announcements) or bb_unread_counts (focuses on unread counts). However, it doesn't explicitly mention alternatives for when not to use it, but the use case guidance is strong enough to warrant 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 and openWorldHint=true, so the read-only nature is implicit. The description adds valuable behavioral context beyond that: the batch API default, ordering (newest first), and the distinction between full text and preview (via fullText). This enriches the agent's understanding without contradicting 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 tight sentences: the first states the core behavior and ordering; the second covers default scope and a use case. Every word earns its place, and the most critical info (what it lists) is front-loaded.

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

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

For a read-only tool with 5 optional parameters and no output schema, the description covers the main behavior, default scoping, and an example usage. It doesn't discuss rate limits or error cases, but those are less critical given the read-only annotation. What's needed to decide whether to call it is present.

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 each parameter is already documented. The description mentions 'full text' and default scoping, which aligns with parameters but doesn't add new semantic depth beyond the schema. The baseline of 3 is appropriate because 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?

The description opens with a specific verb and resource: 'Lists course announcements with their full text, newest first.' It immediately conveys the tool's core function and adds distinguishing details (coverage of all courses vs. one course) that set it apart from sibling tools like bb_list_content or bb_todo.

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

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

It provides a clear use case: 'Use this for "what did my instructors post?" or catching up after time away.' This tells the agent when to invoke it. It doesn't explicitly state when not to use it or name alternatives, but the context is sufficient for basic selection.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to repeat those. It adds the condition about instructor usage, which is useful context. However, no additional behavioral traits (e.g., limit behavior, sorting, or error conditions) are disclosed 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.

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

The description is a single, concise sentence that front-loads the primary action and scope. Every word adds value; there is no fluff or repetition.

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 list tool with only two parameters and no output schema, the description gives the essential purpose and scope. However, it does not describe the return structure, pagination, or how 'limit' is applied, leaving some ambiguity for the agent.

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 only 50%: courseId has a description in the schema, but the 'limit' parameter has no description. The tool description does not explain the meaning or usage of 'limit' at all. The description mentions 'per session' but does not clarify how limit interacts with sessions, leaving the parameter semantics incomplete.

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 verb 'Lists' and the resource 'attendance records', scoping it to the signed-in user within a specific course. It also lists the statuses (present/absent/late/excused) and the condition of instructor usage, which differentiates it from sibling tools like bb_get_course or bb_list_courses.

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

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

It provides a usage condition ('when the instructor uses Blackboard attendance') which helps the agent understand when data is available, but it does not mention any alternatives or when not to use this tool. No explicit comparison with siblings is given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds that it uses Blackboard's own batch endpoint and that it performs GET reads in a single round trip, which aligns with the annotations. It does not cover partial-failure behavior or rate limits, but the read-only safety is well covered by annotations and the description reinforces it without contradiction.

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

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

The description is two sentences with no filler. The core purpose is front-loaded, the example is embedded naturally, and the comparison to bb_raw_request is concise and useful.

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 batch GET tool with complete schema and read-only annotations, the description covers the essential context: purpose, usage scenario, and path format. It does not describe the response format, but given there is no output schema and the tool is relatively straightforward, the missing information is not critical. It is adequately complete for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents paths and maxChars. The description adds a concrete example path ('v1/courses/_12345_1/groups') that illustrates the version-relative format, but this is minor value beyond the schema's own examples. Baseline 3 is appropriate.

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

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

The description clearly states it fans out up to 20 GET reads in a single round trip using Blackboard's batch endpoint. It specifies the verb (GET) and the resource (batch endpoint), and distinguishes itself from the sibling bb_raw_request by emphasizing efficiency for repeated reads across courses.

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

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

It provides a clear use case: 'when gathering the same data across many courses' and explicitly contrasts with repeated bb_raw_request calls, noting it is cheaper. It does not explicitly state when NOT to use it (e.g., for non-GET operations), but the GET-only constraint is implied and the comparison gives strong guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context: it walks recursively, returns folder paths, and can be bounded by maxDepth/maxNodes. It does not mention pagination or what happens when maxNodes is exceeded, but the openWorldHint and readOnlyHint cover the main risk.

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

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

Three sentences, each earning its place: what it does, why it matters, and how to bound it. The most important information is front-loaded.

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

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

For a read-only recursive traversal with a fully documented schema, the description is nearly complete. It could mention what happens when maxNodes is hit or whether the result is a flat list vs. nested tree, but the phrase 'returns every item with its folder path' implies a flat list, and the annotations cover the safety profile.

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 all six parameters. The description adds the recursive-walk semantics and the bounding intent, but it does not add meaning beyond the schema for individual parameters. 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 ('Walks'), a precise resource ('full content outline of a course recursively'), and the return payload ('every item with its folder path, type, and any attached file'). It also positions itself as 'the primary way to discover what material a course contains,' which distinguishes it from sibling tools like bb_list_content and bb_get_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?

The description says this is the primary discovery tool and gives bounding guidance ('Use maxDepth/maxNodes to bound very large courses'). It does not explicitly name alternatives or state when not to use it, but the primary-tool framing plus sibling names gives an agent enough context to select it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds behavioral context beyond the annotations: it lists the types of entries returned, states the default all-courses scope, and implies date-range filtering behavior. It doesn't mention pagination or ordering, but the annotations carry the main safety burden, so a 4 is appropriate.

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

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

Three sentences with zero waste. The core action and scope are front-loaded, the entry types are enumerated compactly, and the sibling routing is a single clear sentence. 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 read-only list tool with no output schema, the description covers the main things an agent needs: what it returns, the default scope, and when to use the sibling instead. It doesn't describe the return shape or pagination, but with readOnlyHint and openWorldHint annotations plus 80% schema coverage, the remaining gaps are minor. A 4 is appropriate.

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 80%, so the schema already documents most parameters. The description adds the default 'Covers all courses by default' which clarifies courseId's optionality, and the date-range framing maps to days/since/until. However, it doesn't add detail about limit or the interaction between since/until and days beyond what the schema already says. Baseline 3 is correct.

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

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

The description states a specific verb ('Lists'), a resource ('calendar entries'), and a scope ('in a date range'), and enumerates the entry types included (class sessions, instructor-created events, assignment due dates). It also distinguishes itself from the sibling bb_todo by noting the default all-courses behavior. This is a clear, specific purpose statement that an agent can act on.

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 explicitly says to use bb_todo instead when the question is specifically about assignment deadlines, which is a clear when-not-to-use directive. It also states the default behavior ('Covers all courses by default'), which implies when to use it (broad calendar queries) versus when to restrict with courseId. This is strong usage guidance.

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 indicate readOnlyHint and openWorldHint. The description adds meaningful behavioral context: it returns only recurring/configured meetings and explicitly states that an empty result is expected when no schedule was set up. This goes beyond what annotations provide.

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

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

The description is two sentences with no filler. It front-loads the core behavior, includes the output fields, and adds the important empty-case condition in a compact way. 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 one-parameter, read-only tool with no output schema, the description is complete enough. It states what is returned, the empty behavior, and the schema covers the courseId format. No critical calling information 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 single parameter courseId is fully documented in the input schema with an example format ('_12345_1'), giving 100% schema description coverage. The tool description adds no additional parameter semantics, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Lists') and resource ('recurring class meetings configured for a course') with concrete fields (day, time, room). It is clear and unambiguous, though it does not explicitly name any sibling tool to differentiate itself from, such as bb_calendar.

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 empty-result note gives some context about when the tool may return nothing, but there is no explicit guidance on when to use this tool versus alternatives like bb_calendar or bb_get_course. Usage context 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 include readOnlyHint=true and openWorldHint=true)Skip, which already indicate the operation is safe and may have external side effects. The description adds: 'Respects the configured size limit per file' and 'skips files already on disk,' which are useful behavioral details about potential limits and idempotency. However, it does not disclose that downloads may hit the blackboard's permissions or that some files may fail silently, but given annotations cover the read-only nature, a 3 is appropriate.

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

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

The description is two sentences: the first states the primary function and output organization, the second gives the use case and safety behavior. It is concise and front-loaded with pivotal information. No fluff, though it could be slightly more structured with bullets, but it is efficient.

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

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

Given the tool has 4 parameters, a read-only annotation, and no output schema, the description adequately covers the tool's purpose and key behavior. It doesn't explain return values, but for a download tool, that's less critical. It could benefit from noting that the operation runs in the background or requires specific permissions, but the description is sufficient for typical use.

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 have descriptions in the schema. The tool description only adds context on the `maxFiles` and `maxNodes` defaults implicitly via 'size limit' but does not restate each parameter. Since the schema already explains each parameter well, the description adds marginal value. Baseline 3 is correct.

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

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

The description clearly states the tool's purpose: 'Walks a course and downloads every attached file to a local folder, organised by course.' It specifies the action (download), the resource (course files), and the output (local folder). It distinguishes itself from simpler file download tools like bb_download_file by indicating bulk behavior, and from other siblings by the phrase 'Use for archiving a course or grabbing all slides at once.'

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

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

It provides explicit use cases: 'Use for archiving a course or grabbing all slides at once.' It implies contrasts: `bb_download_file` for single files, `bb_download_submission` for submissions menus. However, it does not explicitly say when *not* to use it or list alternatives by name. The guidance is clear but minimal exclusions.

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

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

With readOnlyHint=true and openWorldHint=true already providing safety context, the description adds meaningful behavioral detail: the local side effect of saving, the return saved path, and special handling for Google-provided exports. There is no contradiction with the annotations - the description's behavior is read-only against the server while still having a client-side write.

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 focused sentences, with the core action front-loaded and no filler. It efficiently covers the action, usage, and a special complication, each sentence earning its place.

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

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

Given 5 params, complete schema coverage, and no output schema, the description fills important gaps: it explicitly states the return (saved path) and the non-Google/Google file behavior. It doesn't explain interactions between 'all' and 'fileName', but the schema describes both params, so the agent has enough context 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 descriptions cover 100% of parameters, so the baseline is 3. The description mentions format's role for Google-export formats, but this only restates what that parameter describes in the schema. It does not add new parameter-level semantics beyond the schema, so no score above baseline.

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

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

The description states the core verb and resource ('Downloads a file from a content item and saves it locally') and the differentiator 'without extracting text' which separates it from text-reading siblings. It also covers a special case (Google-linked content items), 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.

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

It explicitly lists when to use the tool ('Use this for Office documents, images, archives, or anything the user wants to keep'), giving solid context. It doesn't name a specific alternative (e.g., bb_read_file) or state when not to use it, but the 'without extracting text' phrase implies the trade-off.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds little beyond restating the download purpose. It does not mention return format, file packaging, size limitations, or other behavioral details, leaving the description carrying minimal extra weight.

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

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

Two short sentences, with the core action front-loaded and the prerequisite immediately following. Every word earns its place; there is no filler or redundancy.

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

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

The description plus high-coverage schema provides enough for an agent to select and invoke the tool correctly. The absence of an output schema and any return-format details is a minor gap given the straightforward download nature, but the invocation guidance is otherwise complete.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaningful semantic value by telling the agent that attemptId and columnId are obtained from bb_get_grade_detail, explaining how to source them rather than just what they are.

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 and object: downloads files the student submitted with an assignment attempt. This clearly distinguishes it from sibling download tools like bb_download_file and bb_download_course_files by grounding it in the assignment-attempt context.

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 explicitly instructs the agent to call bb_get_grade_detail first to find the attemptId and columnId, which is directly actionable. It does not enumerate when not to use the tool versus alternatives, but the sequencing guidance is clear and useful.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the list of returned fields (body text, file metadata, etc.), which gives useful context about the output. However, it does not add behavioral traits like performance implications, error handling, or response formatting. Given the annotation coverage, the description adds moderate value but not rich 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.

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

The description is two sentences with zero waste. The first sentence states the purpose and enumerates the content, the second gives a concrete use case. It is front-loaded with the core function and appropriately sized.

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 tool has no output schema, so the description's enumeration of returned fields (rendered body text, file metadata, external link, due date, embedded files) is the primary guide to the response. Combined with the schema's parameter descriptions and the read-only annotation, the description is sufficiently complete for an agent to use the tool correctly. It could add more about response formatting, but it is adequate.

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 provides full descriptions for all three parameters, including examples and default behavior for includeChildren. The tool description adds no additional parameter semantics, so it relies entirely on the schema. With 100% schema coverage, a 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 states a specific verb (read) and resource (content item) and enumerates the detail fields: rendered body text, attached file metadata, external link target, due date, and embedded files. It also names the use case ('announcement-style document or assignment brief'), which clearly differentiates it from siblings like bb_list_content or bb_search_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?

The description gives a clear usage context: 'Use this to actually read an announcement-style document or assignment brief.' This implies it is for fetching full content rather than just listing or searching. However, it does not explicitly name alternatives or state when not to use it, so it lacks explicit exclusion criteria, though the context is clear.

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

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

Annotations already declare readOnlyHint=true, so the description need not repeat safety. It adds value by specifying the exact fields returned (name, code, term, availability window, Ultra/Classic mode, tools), which clarifies the scope of the read operation. 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.

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

A single, front-loaded sentence that lists all key return fields with no filler. Every word contributes to understanding the tool's output.

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 retrieval tool, the description covers the essential return data and the tool's purpose. It doesn't address error handling or pagination, but given the annotations and the simplicity of the operation, it is sufficiently complete 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?

Schema description coverage is 100%, so both courseId and includeTools are fully documented in the schema. The description mentions 'tools enabled' which aligns with includeTools but adds no additional meaning 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?

The description clearly states the action (get) and resource (one course) and enumerates the fields returned (name, code, term, availability window, mode, tools). This distinguishes it from list operations like bb_list_courses, though it doesn't name a specific alternative. It is specific enough for an agent to know what this tool returns.

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 usage (retrieve full detail for a single course) but provides no explicit guidance on when to choose this over bb_browse_course or other getters. It does not mention alternatives or exclusions, so the agent must infer from the name and context.

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 description doesn't need to restate read-only behavior. It adds value beyond annotations by disclosing the full scope of the response, including every attempt, timestamps, statuses, submitted text, and instructor feedback. The only slight gap is not explaining what happens when includeAttempts=false, though the schema covers that parameter.

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

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

Three short sentences with no filler. The most important scoping statement ('Everything about one gradebook item') is front-loaded, followed by a concrete enumeration and a final routing clue. 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 read-only detail retrieval tool with no output schema, the description compensates well by enumerating the returned contents: score, rubric/points, due date, attempts, submitted text, and feedback. It also handles the key distinction from the grade list. There is no missing critical context an agent needs to decide to call it.

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 parameters are fully documented in structured form. The description does not add parameter-specific meaning beyond saying the tool returns detailed grade information; it reinforces the purpose but does not clarify 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.

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

Description states a specific verb ('get') and resource ('grade detail') and enumerates exactly what is returned: score, rubric/points, due date, attempts with timestamps and status, submitted text, and feedback. It also differentiates itself from the sibling tool bb_list_grades by noting that feedback lives here and not in the grade list.

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?

'This is where feedback lives. The grade list does not carry it' explicitly tells an agent when to choose this tool over the obvious alternative, bb_list_grades. It clearly signals that feedback/detail retrieval requires this tool rather than the summary list, giving both positive and negative routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, carrying the safety and stability profile, and the description does not contradict them. The description adds no further behavioral disclosure beyond the aggregate computation itself (e.g., no mention of rate limits, result format, or how open-world data affects the numbers); with annotations in place, that is acceptable but not value-adding.

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 zero wasted words: the computational result is front-loaded, followed by one usage directive. It reads quickly and conveys everything needed without redundancy.

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

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

For a read-only aggregation tool with one optional, fully documented parameter and annotations, the description covers what is computed and when to call it. The lack of an output schema is partially mitigated by naming the returned summary values, though the exact response shape is left unspecified.

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

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

Schema description coverage is 100%, and the sole parameter (maxCourses) is fully documented with type and bounds, so the schema carries the semantic load. The description adds no meaning for the parameter, which aligns with the baseline 3 when the schema is complete.

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 ('computes') and a precise resource (grade standing per course), enumerating exactly what is produced: number of graded items, running points total, and average percentage. It signals its distinction from sibling tools by contrasting 'how am I doing overall?' with 'listing every item,' though it never names the sibling (e.g., bb_list_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?

The description explicitly states when to use the tool ('how am I doing overall?' questions) and what it is NOT for ('rather than listing every item'). This gives real routing context against the itemized grade-list tools, but it stops short of naming alternative tools explicitly, so an agent must infer which sibling to pick instead.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the tool's safe read-only nature is covered. The description adds the one-level scoping. It does not describe the response format or pagination, but given the annotations, this does not go beyond what is expected.

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 long: first states the core function, second gives the directive about using bb_browse_course. No wasted words, and the key detail is front-loaded.

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

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

For a read-only list tool with no output schema, the combination of the description and annotations is sufficient for correct invocation. It defines the operation, the target scoping, the alternative to prefer, and the parameters are all described in the schema. There are no gaps needed 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?

The schema already has descriptions for courseId and contentId (67% coverage). The description adds the phrase 'immediate children' to clarify the level of listing, but it doesn't explain the limit parameter at all, which remains entirely described by the schema's min/max. The added value over the schema is modest.

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 ('Lists') and a specific resource ('immediate children of a course folder or lesson, or the top level of the course'), and explicitly differentiates itself from the sibling tool bb_browse_course by naming it. An agent can immediately understand what the tool does and how it differs from a similar tool.

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

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

It provides an explicit usage rule: 'Prefer bb_browse_course unless you specifically want one level.' This directly tells the agent when to use this tool instead of the sibling, which is exactly the kind of guidance that removes ambiguity.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only safety profile is established. The description adds value by disclosing the dual behavior (list threads vs. read messages in a thread), but it does not address ordering, pagination, or what occurs when conversationId is combined with limit. It adds context without contradiction, earning a mid score.

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

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

A single, tightly written sentence that front-loads the primary behavior and appends the optional mode. No wasted words, though it could marginally benefit from a usage hint. Efficient and well-structured.

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 listing tool with moderate complexity (3 parameters, no output schema), the description conveys the essential behavior and the two invocation modes. Without an output schema, it does not specify return format, but the dual-mode clarity is sufficient for an agent to call it correctly. Minor gaps around limit/pagination remain.

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 67%, with courseId and conversationId already documented in the schema. The description implicitly maps 'message threads' to the default and 'messages inside one thread' to conversationId, but adds no new detail about limit semantics or value formats. At this coverage level, 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 states a specific verb (lists) and a precise resource type (message threads / 'conversations' in a course), and additionally discloses the dual-mode behavior of optionally listing messages inside a thread. This clearly differentiates it from siblings like bb_list_discussions, which covers discussion forums rather than course messages.

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 no explicit when-to-use or when-not-to-use guidance, and does not name any alternative tool. With several plausible siblings (bb_list_discussions, bb_announcements, bb_todo) that an agent could confuse for message-like content, the lack of routing guidance is a notable gap.

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, so the read-only and un-paginated nature are already provided. The description adds value by describing the returned fields and, crucially, the format and significance of courseId (like _12345_1), which is behavioral context beyond what annotations offer. 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.

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

The description is two sentences with no redundant words. It front-loads the core purpose and immediately follows with the most critical behavioral detail (courseId as a prerequisite). Every sentence earns its place, making it both concise and well-structured.

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 listing tool with five optional parameters and annotations covering read-only and open-world behavior, the description is sufficiently complete. It provides the essential context an agent needs: what the tool returns, the key output (courseId) and its role in subsequent calls. The lack of an output schema is mitigated by the explicit field enumeration, and the parameter details live in the schema. Minor gaps like pagination are covered by the openWorldHint annotation.

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 each parameter (term, search, availableOnly, includeHidden, organizations) already has a clear description in the schema. The tool description does not add any parameter-specific semantics, so per the baseline rule for >80% coverage, a score 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 a specific verb and resource: 'Lists the courses the signed-in user is enrolled in,' and enumerates the returned fields (course id, name, term, role, last-access date). It differentiates from siblings by explicitly noting the returned courseId is the prerequisite for all other course tools, making its purpose and position among the tools unambiguous.

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

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

The phrase 'Start here' gives explicit usage guidance, indicating this tool should be invoked first to obtain course IDs needed by other course tools. While it doesn't name specific alternative tools or exclusion criteria, the instruction to start here clearly establishes when to use this tool versus diving into course-specific operations.

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 annotation, the description explains the conditional behavior driven by messageId and the relationship to bb_browse_course. It does not discuss pagination or default limits, but the read-only safety profile is already covered by 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 front-loaded sentences with no filler: the first states the operational behavior, the second gives the required lookup path. 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 read-only list operation with no output schema and an openWorldHint, the description tells the agent what it will get and how to satisfy the required forumId. Minor gaps such as default limit and exact response shape remain, but they are not blocking 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 description adds meaning beyond the schema by explaining that messageId selects the reply view and that forumId should be the conferenceId/id from bb_browse_course. The undocumented limit parameter is not addressed, but three of four parameters already have schema descriptions.

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

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

The description uses a specific verb ('Reads') and resource ('discussion forum'), and clearly distinguishes the two call modes: top-level posts by default, or replies when messageId is provided. It does not explicitly name or differentiate a sibling tool such as bb_list_conversations, so it stops short of full sibling differentiation.

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 a concrete prerequisite: obtain forumId from a 'discussion' item in bb_browse_course, including where to find the id (contentDetail conferenceId/id). This is clear usage context, though it does not explicitly state when to choose this tool over sibling read-list tools.

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 already signals a safe read operation, so the description is free to add context. It does so by disclosing the output contents (operation name, path template, local overrides) and the fact that this is server-local knowledge, which is meaningful beyond the annotation.

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 deliver the main functional claim, the output details, and the recommended use case without wasted words. The most important information is front-loaded.

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

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

For a simple read-only listing tool with one optional parameter, the description covers what the tool returns and why an agent would use it. No output schema exists, but the description explicitly names the key output fields, making the behavior sufficiently complete.

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

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

The single optional parameter 'filter' is fully documented in the schema as a 'Case-insensitive substring filter.' The description adds no additional meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description specifies a precise verb and resource: 'Shows every Blackboard API endpoint this server knows,' and details exactly what is included (operation name, path template, local overrides). This clearly differentiates it from other list tools like bb_list_courses or bb_list_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?

It gives clear context by stating 'Useful for discovering what to pass to bb_raw_request,' which tells the agent when this tool adds value. It does not explicitly mention when not to use it or compare it to sibling tools, so it stops short of a full 5.

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

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

The annotations already provide readOnly and openWorld hints, and the description adds useful behavioral detail: it walks the course, includes embedded and linked documents, and returns metadata rather than file bytes. It does not discuss pagination or rate limits, but given the annotations 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 short sentences with a clear action verb and concrete enumerations. It avoids boilerplate and every clause adds useful detail about scope or return value.

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 provided, the description names the returned fields meaningfully (name, type, size, contentId). It could mention pagination/limits or clarify that only readable items are returned, but the core behavior is sufficiently complete for a simple list 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?

The JSON schema already describes the parameters, including the meaning of deep and maxNodes. The description adds no parameter-specific instructions, but full schema coverage makes that acceptable.

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

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

The description clearly identifies the action: it walks a course and lists every readable document. It enumerates the exact item types covered (attached files, embedded files, and Google Docs/Slides links) and states the returned fields, making the tool's role unmistakable and distinct from generic list-content or course-structure tools.

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 when to use the tool by saying it lists files and returns contentId for fetching, but it does not explicitly contrast it with sibling tools or state when not to use it. This is adequate but not actively helpful for routing.

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 reveals the output shape (graded items, score, status) and importantly discloses the cost behavior: cross-course mode uses roughly one request instead of one per course. With readOnlyHint present, no contradiction. It doesn't mention pagination/limits, but the core behavior is transparent.

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

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

Three tight sentences: what it does, what it returns, and the cost characteristic of cross-course mode. Front-loaded and 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?

Covers both operation modes, returns, and API request behavior. No output schema exists, but the description explains what each list entry contains. Could mention limits, ordering, or auth, but for a list tool this is sufficient.

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 descriptions already cover all 3 parameters 100%. The tool description adds the “every enrolled course when omitted” semantics for courseIdache, which is useful, but largely overlaps with schema. No additional meaning beyond schema and the batch request detail.

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

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

States a specific action and resource: lists grades for one course, with an explicit fallback to all courses when courseId is omitted. It also describes what is shown (item, score, status), which differentiates it from the grade-summary and grade-detail 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?

Clearly explains the two usage modes: pass courseId for one course, omit it for all enrolled courses多看. It does not explicitly compare with siblings like bb_grade_summary or bb_get_grade_detail, so not a perfect 5, but the context is clear enough for invocation decisions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to restate safety. The description adds the behavioral context that it returns roles and is useful for contact/group identification, but it doesn't disclose details like pagination behavior, default limit, or whether the roster is filtered by the 'role' parameter. This is acceptable given the annotations cover the read-only nature.

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 wasted words. The main action is front-loaded, and the use cases are concise and informative.

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 list tool with one required parameter and an output schema absent, the description is sufficient. It explains the purpose and use cases, and the schema covers the parameters. It could mention pagination or default limit behavior, but given the tool's simplicity and annotations, it is nearly complete.

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

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

Schema description coverage is 67%: courseId and role have descriptions, but limit has none. The description adds meaning by explaining the purpose of the roster (roles, contact, group members), which helps interpret the role parameter. However, it doesn't add detail about the limit parameter or the exact format of the role values beyond the schema's enum. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists people enrolled in a course with their roles, using a specific verb ('Lists') and resource ('people enrolled in a course'). It also provides concrete use cases (finding an instructor, identifying group members) that distinguish it from sibling tools like bb_list_courses or bb_get_course.

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 the tool ('finding an instructor to contact, or identifying group members'), which implies it is for roster-related queries. It does not explicitly name alternatives or state when not to use it, but the use cases are specific enough to guide an agent.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description carries a lighter burden. It adds that results include date ranges, which is helpful, but it does not disclose ordering, pagination behavior, or what happens when limit is omitted. This is adequate given the annotation coverage.

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

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

A single, direct sentence that says what the tool does and what it returns. No wasted words or repetition of the title or schema.

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

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

The tool is simple, but the description omits the meaning of the optional 'limit' parameter and does not describe the default return format or pagination. With no output schema and no parameter descriptions anywhere, an agent lacks enough information to fully understand all call options.

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 0% for the single 'limit' parameter, and the tool description does not mention it at all. With no support from the schema description, the tool description leaves the parameter's meaning entirely to inference, so it fails to compensate.

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 ('lists'), resource ('academic terms'), scope ('defined on the instance'), and output detail ('with their date ranges'). Clearly differentiates from sibling list tools such as bb_list_courses and bb_list_conversations.

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

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

Usage is implied by the name and description: it is the read-only listing for academic terms. However, it does not explicitly say when to use this versus other list tools, mention prerequisites, or note how the limit parameter might affect call decisions.

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 indicate this is not read-only (readOnlyHint=false), is idempotent, and not destructive. The description adds the critical context about requiring BLACKBOARD_MCP_ALLOW_WRITES=1 and that the server is read-only by default, which is valuable beyond the annotations. It also mentions it corresponds to a UI button. However, it doesn't describe what happens on success or failure, but with idempotentHint=true Agenda, some of that is 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 two sentences, with the purpose and key constraint front-loaded. It's efficient and to the point, with no unnecessary words. Every sentence adds value: one for the action, one for the enabling requirement.

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

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

Given the tool is a simple mutation with two required parameters and full schema coverage, the description covers the purpose and the key write-enabling condition. There's no output schema, so return values aren't specified, but for a mutation tool that's not critical. It doesn't mention error handling or common failure cases, but given the simplicity and idempotency, it's adequate. A 3 is fair—it's complete enough, but could have hinted at the typical failure when writes are disabled.

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?

Since schema coverage is 100%, the schema already documents all three parameters (courseId, contentId, reviewed) with descriptions. The description doesn't add extra semantic detail beyond what the schema provides, but the parameter descriptions are self-explanatory (e.g., 'Must be a reviewable item' in contentId). Baseline 3 is appropriate because 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?

The description clearly states the tool marks a reviewable content item as reviewed, explicitly linking it to the 'Mark Reviewed' button in Ultra. This distinguishes it from other content-related tools that list or get content, though it doesn't explicitly name a sibling to differentiate from. The verb 'marks' and resource 'reviewable content item' are specific.

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

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

The description provides clear context: it's for reviewable items, requires writes to be enabled, and notes the server is read-only by default. This implies when to use it (when you need to mark content as reviewed) and when not to (when writes are disabled). It doesn't explicitly mention alternative tools, but the constraint is clear. It could have named a sibling for un-reviewing, but the 'reviewed' parameter handles that.

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 carry readOnlyHint=false and openWorldHint=true, so the description need not repeat those. It adds useful context beyond them: the raw JSON return format, that the Ultra internal API exposes more than this server models, and the 'escape hatch' nature implying caution. It does not explicitly warn about destructiveness, but the schema's method enum and the note that writes need to be enabled supply that. No contradiction between description and 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?

Four sentences with no filler. The first sentence establishes the core purpose and return type; the second gives the primary usage condition; the third points to the broader API; the fourth instructs a preliminary step. Every sentence earns its place, and key guidance is front-loaded.

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

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

Given the tool's open-ended nature, the description is sufficiently complete. It explains when to use it (no dedicated tool), how to discover wrapped endpoints (bb_list_endpoints), and what the response looks like (raw JSON). The schema covers parameters, and annotations cover the write/open nature. It does not describe error handling, but that is not essential for an escape-hatch tool and is not expected at this level.

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 each parameter (path, body, query, method, maxChars) already has a clear description. The tool description does not add extra parameter-level detail, but it maps conceptually to the 'any API path' idea. Per the rubric baseline of 3 for high schema coverage, this is appropriate.

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

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

The description clearly identifies the tool as an 'escape hatch' that issues a request against any Blackboard API path and returns raw JSON. It distinguishes itself from the many sibling tools by being the generic fallback when no dedicated tool exists. The verb 'issues a request' plus the resource 'any Blackboard API path' 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.

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

It explicitly states when to use it: 'Use this when no dedicated tool covers what you need.' It also provides a concrete step ahead of use: 'Call bb_list_endpoints first to see what is already wrapped,' giving the agent a clear decision path and avoiding redundant calls.

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 annotation, the description discloses page-window streaming for PDFs, Google provider exports, accepted formats, and the important limitation that Office formats download but cannot be extracted. This gives an agent concrete expectations for context usage and failures.

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?

Five succinct, high-signal sentences: purpose, Google-link special case, PDF windowing, format coverage, and final usage mandate. Every sentence earns its place, and the key user recommendation is saved for the last sentence for impact.

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 for a read-only extraction tool: it covers behavior, limitations, format support, and practical use in lectures. Given the detailed annotations and 100% schema coverage, no critical context is missing for an agent.

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 description itself does not deeply elaborate on each parameter, instead referencing the schema-level terms like fromPage. It adds minor contextual value by explaining the purpose of windows and offset-style continuation, but it does not materially improve upon the already-complete schema.

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

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

The description opens with a clear verb–resource pair ('Downloads a file attached to a content item and extracts its text') and adds a distinctive secondary capability: resolving Google Slides/Docs/Sheets links into readable text. It closes with an explicit usage statement ('This is the tool to use to actually read lecture notes or a handout'), and the format coverage details distinguish it from sibling tools like bb_download_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?

The description explicitly recommends when to use the tool ('This is the tool to use to actually read lecture notes or a handout') and provides conditional guidance for PDFs and Google-linked documents. It does not explicitly name when-not-to-use scenarios or compare against siblings like bb_download_file, so it stops just short of the clearest possible when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds a useful behavioral trait: searching all courses 'walks each tree,' implying a potentially slow operation. This goes beyond the schema and gives the agent an expectation about performance, which is valuable.

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, no filler. The first sentence states the core function and scope; the second provides usage context and a performance caveat. The most important guidance is front-loaded, making it easy for an agent to parse quickly.

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

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

Given the tool's complexity (5 parameters, all documented) and the presence of readOnlyHint, the description covers the main use case and performance implications. It doesn't describe the return format, but that's not critical for a search tool, and the output schema is absent. The description is sufficient for an agent to invoke it correctly in most scenarios.

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 all parameters have descriptions. The description adds semantic guidance not present in the schema: the trade-off between courseId (fast, targeted) and omitting it (slow, comprehensive), and the 'titlesOnly' hint that it's faster. This helps the agent choose parameters wisely.

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

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

The description clearly states the tool's function: searching content item titles and body text for a query string, with the option to restrict to one course or search all enrolled courses. It distinguishes itself from sibling list/browse tools by focusing on search, and the example 'where are the lecture slides on transformers?' makes the intent unambiguous.

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 says when to use it ('when the user asks where something is') and provides a concrete example. It also gives a clear performance preference: 'prefer a single courseId when you know it,' which guides the agent toward efficient invocation without being overly restrictive.

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, so the description doesn't need to restate safety. It adds useful behavioral context: the tool reports session validity, capture time, and cookies, and the keepAlive parameter can extend the session. It doesn't mention what happens if no session exists, but the annotations cover the read-only nature and the description adds the keep-alive behavior.

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 wasted words. The first sentence states what it reports, the second gives the usage trigger. The most important information is front-loaded.

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

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

For a simple read-only diagnostic tool with one optional parameter and no output schema, the description is nearly complete. It covers what the tool does, when to use it, and the parameter's effect. A minor gap is not describing the output format or what happens when no session exists, but the annotations and simplicity of the tool make this acceptable.

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 the keepAlive parameter. The description adds context by explaining that keepAlive pings the keep-alive endpoint to extend the session, which goes beyond the schema's bare description. This is a good complement to the schema.

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

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

The description clearly states the tool's function: reporting session validity duration, capture time, and held cookies. It uses a specific verb ('reports') and resource ('stored Blackboard session'), and the title 'Blackboard session status' aligns with the description. It distinguishes itself from siblings by focusing on session diagnostics rather than course/content operations.

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 explicitly says when to call this tool: 'when other tools start failing with session errors.' This provides a clear trigger condition and implies it is a diagnostic tool rather than a primary operation. It doesn't need to name alternatives because the sibling list shows no other session-status tool, and the guidance is sufficient for an agent to select it.

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

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

The annotations already declare readOnlyHint and openWorldHint, so the description adds value beyond that by stating the tool groups by urgency, sorts by date, and spans all courses in one call. It does not contradict the annotations and reveals useful output behavior not available from structured fields alone.

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

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

Three sentences deliver the tool's purpose, usage context, and output ordering with no filler. The most important details are front-loaded, 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 list tool with all parameters documented in the schema, the description is complete enough for an agent to select and invoke it correctly. It states scope, grouping, sorting, and typical use cases, so nothing essential for correct usage 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?

Schema description coverage is 100%, with each parameter (days, lookBackDays, includeOverdue) already documented with type, bounds, and defaults. The tool description adds no additional parameter-level meaning, 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?

The description clearly defines a specific resource: the student to-do list, covering overdue, due-today, and upcoming items across all courses. It separates this tool from siblings like bb_calendar and bb_activity_stream by framing it as the answer to 'what do I have due?'. The scope and one-call nature are explicit.

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 usage context by naming the exact user questions it answers: 'what do I have due?', 'am I behind?', and 'what should I work on?'. It does not explicitly state when not to use it or name an alternative sibling, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful behavioral context beyond those annotations, including 'Cheap', 'in a single call', and 'across every course'. It is consistent with the annotations and gives a reasonable sense of scope and cost.

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

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

Two short sentences provide the output description, cost hint, and usage guidance with no wasted words. The core purpose is front-loaded and the guidance is immediately actionable.

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 count tool the description is largely complete: it covers output scope, cost, and call context. The only minor gap is that the title mentions 'notification counts' while the description emphasizes messages, but this does not prevent an agent from correctly selecting and invoking the tool.

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

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

The tool has zero parameters and the schema is empty, so there is nothing the description needs to explain about inputs. The baseline of 4 applies because parameter semantics are fully moot.

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 exactly what the tool returns: unread message counts across every course plus an overall messages summary. It clearly distinguishes itself from bb_list_conversations by focusing on aggregate counts rather than message contents.

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?

'Use it to decide whether reading messages is worth it before calling bb_list_conversations' explicitly states when to use this tool and names the relevant sibling alternative. The 'Cheap' qualifier also gives a clear cost-based reason to prefer it.

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

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

Annotations already mark readOnlyHint=true and openWorldHint=true pinning down the safety profile. The description adds value beyond annotations by naming the exact identity fields returned (name, username, student id, email) and the configured instance, plus its role as an auth check.

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

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

Two sentences, front-loaded with the return payload, and the usage hint is one short clause. 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 zero-parameter identity introspection tool with read-only annotations warning, this is nearly complete. It doesn't spell out error behavior on failed auth (e.g., returns null vs throws), but that's a minor gap.

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

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

The input schema has zero parameters desk definition is complete. Baseline 4 for a no-param tool. Nothing to add.

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

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

The description uses a specific verb ('Returns') with a clear resource (signed-in Blackboard user) and enumerates the exact fields returned (name, username, email, institution roles, instance). This is self-explanatory as a whoami operation and is plainly distinct from siblings like bb_session_status or bb_unread_counts.

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 explicitly states when to use it: confirm authentication is working before other calls. It doesn't name alternatives or exclusions, but for a whoami tool that's natural context. It gives a clear use-before-other-calls signal.

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