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

The annotations already declare readOnlyHint=false and idempotentHint=false; the description adds the reason — the tool writes a snapshot file and later calls compare against it, so repeat runs are stateful and non-idempotent by design. That is genuine context beyond the annotations, though the state location and whether a snapshot can be reset or inspected remain unstated.

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

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

Two short sentences with no filler, front-loaded with the primary action, and the supporting detail trails it.

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 four-parameter, stateless-looking tool with no output schema, the description explains the stateful baseline concept and the comparison result well enough to call it correctly. It could say more about where the snapshot lives or what happens on the first run, but the core mechanics are covered.

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 every parameter is already documented in the schema; the description only adds why includeFiles exists (hashing bytes). The baseline 3 applies because the schema does the heavy lifting and the description adds marginal meaning.

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 concrete verb pair (compare / create baseline) and a concrete resource pair (course content metadata vs. the tool's own snapshot), which is enough to distinguish it from the listing and reading siblings. It stops short of naming the alternative (e.g. fetch content directly) an agent should pick when it does not want drift detection, so it is clear but not fully differentiated.

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 a clear triggering condition — run this to detect changes since your last baseline — and a specific follow-up pattern (repeat calls share a snapshot). It does not state when a caller should prefer the read/list siblings, nor whether a first run must precede the comparison, which keeps it below 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, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description still adds real context beyond that: a data-quality warning that copied announcements may refer to older academic years or another class, which the agent would otherwise misattribute to the current term.

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 operation front-loaded and the caveat second; nothing is redundant and no sentence could be dropped without losing information.

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

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

For a read-only paginated list tool this is close, but with no output schema the description only hints at return contents via the date mention, leaving the agent to guess whether titles, bodies, or author fields come back. Pagination behavior is also unaddressed beyond the schema defaults.

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 (courseId pattern, limit max 100/default 50, offset default 0) is documented inline. The description adds no paging or ID formatting guidance, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Read course announcements') plus what the payload carries (publication/modification dates), which separates it cleanly from siblings like brightspace_get_assignments or brightspace_get_content. It stops short of explicitly naming alternatives, but the resource is 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?

Usage is only implied: an agent can infer this is the tool for pulling announcements for a courseId. There is no statement of when to prefer it over searching or checking updates (brightspace_check_updates), and no prerequisites such as needing enrollment or a valid course/org unit ID.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuine context beyond them: it enumerates the returned sub-resources (criteria, levels, points), scopes results to 'visible' assignments (an access constraint), and warns that responses may need completeness/warning checks. The only notable omission is pagination behavior, despite limit/offset parameters.

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 with the object of the call front-loaded, no restatement of the tool name. The closing clause 'Check completeness and warnings' is a slightly awkward directive and would read better as a description of response fields, but nothing is truly wasted.

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

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

With no output schema, the description usefully sketches what comes back (criteria, achievement levels, points) and warns about warnings/partial data. Combined with 100% schema coverage and read-only annotations, an agent has enough to invoke it correctly. The missing pieces are pagination semantics and the dependency on an assignment-listing call to obtain folderId.

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 courseId, folderId, limit and offset are already fully documented with patterns and defaults. The description contributes only the qualifier that the assignment must be 'visible', a mild semantic constraint on folderId, and says nothing about pagination or ID formats. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Read rubrics') plus the scope ('associated with a visible assignment') and names the payload ('criteria, achievement levels and points'). An agent can tell this is rubric retrieval distinct from siblings like brightspace_get_assignments or brightspace_get_grades, though it never explicitly says how it relates to those 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?

Usage is only implied: the agent must infer that this is the tool to call when it needs rubric detail for a specific assignment. There is no explicit when-to-use/when-not-to-use guidance, and nothing tells the agent that folderId must come from brightspace_get_assignments first, which is the main prerequisite for success.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. Beyond that, the description discloses a visibility filter on results and a meaningful caveat that a missing submission receipt leaves completion status unknown — behavior not encoded in any structured field.

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 what is returned, then the folderId behavior and the receipt caveat. Dense but slightly elliptical — 'check your own submission receipts' is not explained in terms of a parameter or field.

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

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

With no output schema, the description must carry the return-value burden, and it only loosely enumerates fields (instructions, dates, rubric metadata, receipts) without structure. The submission-receipt/completion sentence is ambiguous about where that data comes from, leaving a gap for a read tool with four parameters.

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

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

Schema coverage is 100%, so the schema already documents courseId, folderId, limit and offset including defaults and constraints. The description adds only that folderId returns a single *visible* assignment, which is a modest semantic addition over the schema's 'Optional assignment ID' text.

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

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

The description names a specific verb and resource ('Read assignment instructions, dates and available rubric metadata') and explains the folderId branch that returns a single assignment. It does not distinguish itself from the sibling brightspace_get_assignment_rubrics, which overlaps with the 'rubric metadata' claim, so an agent cannot fully rule out the alternative.

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?

There is an implied usage rule: omit folderId to list, supply it to fetch one visible assignment. However, no explicit when-to-use versus brightspace_get_assignment_rubrics or brightspace_get_deadlines is given, and no exclusions or prerequisites are stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: recurrence rules are not expanded (so recurring events appear as unexpanded entries) and calendar items are not deadlines — both are data-shape caveats an agent cannot get from structured fields.

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

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

Three short sentences, front-loaded with the purpose and followed by the two caveats that most affect interpretation. Nothing is wasted or repeated from the 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?

For a read-only listing tool with fully described parameters and annotations covering safety, the description supplies the two interpretive caveats that matter most. It does not describe the returned event shape or pagination behavior, but with no output schema that is a minor remaining gap rather than a blocking one.

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 limit, offset, start, end, and daysAhead all documented in the schema itself. The description adds no meaning about how start/end interact with daysAhead or the default window, so it sits at the baseline for a fully documented schema.

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

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

States a specific verb and resource ('Read your calendar events') scoped to one course, and the closing line implicitly separates it from the deadline-oriented sibling tool. It stops short of naming an alternative tool outright, but the scope is 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?

Usage is only implied: 'Calendar events are not automatically deadlines' hints that brightspace_get_deadlines is the right tool when the user wants due dates, but there is no explicit when-to-use/when-not-to-use statement or named alternative.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds genuinely new behavioral context: date-restriction bypass flags are never sent, implying content hidden by date restrictions may be omitted or restricted and cannot be overridden. It does not mention pagination behavior beyond what the schema states.

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 core action and no redundant wording. Every sentence carries information.

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

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

For a read-only list tool with full annotation and schema coverage, the essentials are present. However, there is no output schema, and 'flattened with paths' is the only hint at the return shape; it does not clarify whether the call recurses through all modules or whether limit/offset page over modules, topics or both.

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 courseId, limit and offset are fully documented in the schema. The description adds no parameter-level detail such as whether limit/offset apply to flattened results, so this sits at the 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?

States a clear verb and resource: 'List nested course modules and topics'. The 'flattened with paths' clause describes the output shape, which helps distinguish it from a plain course listing, though it never explicitly contrasts with siblings like brightspace_read_topic.

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?

No when-to-use or when-not-to-use guidance. The agent is not told how this differs from reading a single topic via brightspace_read_topic, nor what a typical caller would use the flattened tree for. Usage is only inferred from 'List'.

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

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

Annotations already establish readOnly, idempotent, non-destructive, open-world behavior. The description adds two genuinely useful behavioral facts: due dates and availability end dates are kept distinct (a real semantic trap for an agent summarizing deadlines), and results may have coverage gaps that must be reported. It does not describe what the merged result looks like (fields per item, source labeling) or how pagination interacts with the aggregation.

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

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

Three short sentences, front-loaded with the aggregation scope and then the two most consequential caveats. No filler. The final sentence is an output instruction to the agent rather than a description of the tool, but it earns its place by warning that coverage may be partial.

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 six-parameter, no-output-schema aggregator the description is lean but not complete: it never explains the shape of the returned records (source, title, type, date kind) or the default 14-day window, which matter for calling it correctly. Given no output schema exists, the return-format burden falls on the description and is left unaddressed.

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

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

Schema description coverage is 100%, so every parameter — start, end, daysAhead, limit, offset, courseIds — is fully documented in the schema itself. The description adds no parameter-level meaning beyond that, such as how daysAhead interacts with an explicit start/end or what happens when courseIds is omitted. Baseline 3 applies when the schema carries the load.

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

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

Names a specific action (aggregate structured dates) and explicitly lists the four sources it pulls from — assignments, quizzes, calendar, content — which distinguishes it from the per-source siblings like brightspace_get_assignments and brightspace_get_calendar. It never names a sibling directly, so differentiation is implied by scope rather than stated.

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?

Aggregation across sources implies the use case: a consolidated deadline view rather than a single-source listing. There is no explicit when-to-use versus when to call the narrower siblings, and no stated prerequisites (e.g., whether course IDs must be accessible or what happens when courseIds is omitted).

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: results are limited to the signed-in user's own released grades, and 'missing values are not zero' warns against misinterpreting absent data. It says nothing about return format or pagination, but limit/offset are schema-documented.

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, front-loaded with the core action and scope, with zero redundant wording. Every clause carries distinct information.

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

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

For a simple three-parameter read tool with full schema coverage and clear annotations, this is nearly complete. The remaining gap is the absence of an output schema combined with no description of what a grade record contains, which an agent might want before consuming results.

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 limit, offset and courseId are already fully documented in the schema. The description adds only the indirect constraint that values are scoped to the signed-in user's own released grades. 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?

It gives a specific verb ('Read') and resource ('released Brightspace grade values') plus a tight scope ('signed-in user's'), so an agent can distinguish it from siblings like brightspace_get_assignments or brightspace_get_assignment_rubrics. It stops short of naming an alternative tool, so it is clear but not sibling-routing.

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 single exclusion 'this does not read Osiris' is a useful when-not signal, and 'released' implies unreleased grades will not appear. However, no alternative tool or explicit when-to-use condition is offered, so usage is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile needs no restating. The description adds real value by disclosing what the call will not surface (attempts, questions, review windows, Remindo), preventing false expectations about depth. It stops short of describing what 'metadata and availability' actually contains or how results are ordered.

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 zero filler; the positive scope leads and the exclusion list follows. Every clause carries information an agent needs.

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 paginated read tool with full schema coverage and complete annotations, the description covers the one thing structured fields can't: the depth ceiling of the call. A brief note on what metadata fields are returned would close the remaining 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?

Schema description coverage is 100%, so courseId, limit, and offset are all documented in the schema with defaults and bounds. The description adds no meaning beyond that, which is acceptable given the coverage but earns only the 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?

States a specific verb ('Read') and resource ('quiz metadata and availability'), plus an explicit scope boundary. It doesn't name a sibling alternative, but no sibling is a competing quiz tool either, so the only missing piece is which quiz-related task maps here.

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 negative scoping ('Does not open attempts, questions, review windows, or Remindo') implicitly tells the agent when to look elsewhere, which is useful routing guidance. However, no positive when-to-use condition is given and no alternative tool is named for attempts or questions, so the agent must infer the fallback.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful pagination behavior by telling the agent to check 'sourceComplete' and 'nextOffset'. However, it never explains what those fields mean or what happens when sourceComplete is false, and it names two flags that are not in the schema.

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

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

Two short sentences with no filler, and the core purpose is front-loaded. The second sentence is cryptic shorthand ('Check sourceComplete and nextOffset') that does not earn its place without explaining what to do with those values.

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?

There is no output schema, so the description carries the burden of explaining return values. It gestures at sourceComplete and nextOffset but never defines them, and it omits what a course enrollment contains. The stray parameter names also create real ambiguity about how to call 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?

Schema coverage is 100%, so limit and offset are already documented with defaults and bounds. The description adds nothing about those two parameters and instead references 'activeOnly' and 'includeCourseIds', which do not exist in the schema, risking an agent attempting to pass unsupported arguments.

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

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

States a specific verb and resource: 'List accessible course enrollments'. That is clearly distinguishable from the get_* siblings, which fetch single resource types. The second clause muddies it by citing 'activeOnly and includeCourseIds', which are not parameters of this 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?

There is no when-to-use or when-not-to-use guidance and no reference to alternatives such as brightspace_search_course or brightspace_check_updates. An agent must infer that this is the enumeration entry point for a user's courses.

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, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds one genuinely new behavioral fact — that the listing is limited to CLI-imported snapshots rather than the filesystem — but says nothing about ordering, emptiness when no imports exist, or what an entry contains.

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, no redundancy, with the positive definition front-loaded and the scope exclusion second. Every clause earns its place.

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

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

With no output schema and no parameters, the description is the only source of information about the result set, and it never indicates what a listed snapshot looks like (name, path, import date) or whether results are ordered. For a simple enumeration tool that is an acceptable minimum, but not 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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a fully unscoped, return-everything listing, consistent with the empty 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?

Names a specific verb+resource: lists local Markdown/text snapshots, with the qualifier that they were 'explicitly imported through the CLI'. That qualifier implicitly separates it from the Brightspace API siblings (get_content, search_notes), but no sibling is named explicitly, so an agent must infer the boundary.

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

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

The second sentence gives a clear negative scope ('Does not read arbitrary local files'), which usefully rules out a plausible misuse. However, there is no positive when-to-use guidance and no reference to search_notes or read_note, which are the obvious alternatives for finding note content — the agent is left to work out that this tool enumerates and those retrieve.

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, idempotentHint, openWorldHint and destructiveHint=false, covering the safety profile. The description adds the 'visible' scoping constraint (only readable through a visible parent), but says nothing about extraction behavior, truncation notices when maxChars is hit, or OCR cost/latency for scans, which are the real unknowns for this operation.

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, zero filler, with the resource scope front-loaded ahead of the selection constraint. Every clause carries information an agent needs before calling.

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

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

For an 8-parameter read tool with no output schema, the description never says what comes back (extracted plain text? binary?), how truncation is signalled, or how OCR and section pagination differ in use. The rich schema compensates for parameter detail, but the return-shape gap leaves it merely 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?

Schema coverage is 100%, so the baseline is 3; the description earns a point by stating that exactly one parent must be supplied, making the folderId vs newsItemId mutual exclusivity explicit where the schema only lists both as optional properties. It adds no guidance on offset/maxChars paging semantics beyond the schema text.

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 resource ('Read a file') and bounds it to attachments of a visible assignment or announcement, which distinguishes it from siblings like brightspace_read_topic and brightspace_view_page. It does not explicitly name those alternatives, 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?

'Supply exactly one parent and its attachment FileId' gives a hard precondition, and 'visible assignment or announcement' establishes the context in which the tool applies. No explicit exclusion or alternative route is named for cases where the file is not an attachment, so it lacks the routing guidance 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new context beyond that: the note is an imported snapshot (not live content) and the snapshot date should be preserved when citing. It does not cover what happens when the requested range exceeds the note length or how truncated results surface.

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 compact sentences with the primary action front-loaded and the ID-vs-path disambiguation immediately following. The snapshot-citation advice is a second concern but is short enough not to dilute the lead.

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 full annotation coverage, a 100%-documented schema, and no output schema, the description only needs to fill interpretive gaps. It does so for identifier semantics and snapshot provenance, though it leaves return/truncation behavior unstated.

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 noteId, lineCount, and startLine are already documented with defaults and bounds. The description reinforces that noteId is an opaque ID rather than a path and that reads are line-bounded, but adds no format or edge-case detail beyond the schema.

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

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

States a specific verb ('read') and resource ('note') with the scope of the operation ('bounded line range') and clarifies the identifier type ('using its ID, not a filesystem path'). It partially differentiates from siblings like read_topic/read_attachment by calling the resource an 'imported note', though it does not name those alternatives explicitly.

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 (you must have a note ID, not a path) but never states when to choose this over read_topic, read_attachment, or view_page, nor when not to use it. The retrieval routing is only discoverable through the schema note that noteId comes from list_notes/search_notes.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the meaningful access precondition that the topic must be visible, but says nothing about pagination behavior, how OCR is triggered or costed, or what happens when a document is a scan rather than extractable text.

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 with the core action first and the supported formats as a compact qualifier. No filler, no repetition of the tool name, and nothing that could be cut without losing information.

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

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

With six parameters and no output schema, the definition should explain at least the shape of the returned text and how offset/maxChars chunk it, plus when a scan requires OCR instead of direct extraction. Those gaps remain, though the annotations and full schema coverage keep the tool callable without them.

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 every parameter including offset, section, ocrPage and maxChars is already documented in the schema. The description contributes no additional meaning about how these parameters interact or which to prefer, which is the expected baseline when the schema does the work.

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 resource ("Read text from a visible file topic") and enumerates the supported formats (PDF pages, PowerPoint slides and speaker notes, Word paragraphs, Excel rows). It is clearly distinguishable in intent, though it never names or contrasts itself with close siblings such as brightspace_read_attachment or brightspace_view_page.

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 "visible file topic" scoping and the format list, which tells an agent this is for extracting text out of file content items rather than notes, pages, or attachments. There is no explicit when-to-use/when-not statement and no pointer to the alternative tools for non-file content.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's job is to add operational context, which it does: files are searched by default, file matches carry slide/page/section references, and pagination continues via fileSearch.nextFileOffset. It stops short of disclosing cost/latency of file processing or the shape of metadata hits, which would complete the picture.

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

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

Three short sentences, front-loaded with the search scope before defaults and pagination. The trailing fragment 'Follow fileSearch.nextFileOffset.' is terse to the point of being cryptic, and 'a batch of visible files by default' is loosely worded, but nothing is padded.

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

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

For an 8-parameter search tool with no output schema, the description covers scope, the file default, and a pagination pointer. It does not describe the result structure for outline/announcement/assignment hits, how limit interacts with fileLimit, or what 'visible files' excludes, so an agent must discover returns empirically.

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

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

Schema coverage is 100%, so baseline is 3, and the description does add one genuinely new fact not in the schema: includeFiles defaults to true. The reference to 'fileSearch.nextFileOffset' also hints at the pagination loop, but it uses an output-field name that does not map cleanly onto the fileOffset parameter, so an agent still has to infer how to resume.

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 (Search) and enumerates the resources covered: course outline, announcements, assignments, and visible files. The scope is clear enough to distinguish it from single-resource getters like brightspace_get_assignments or brightspace_get_announcements, but it never names or contrasts those siblings explicitly.

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

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

Implies usage through the default-includes-files framing and the instruction to follow fileSearch.nextFileOffset, which tells an agent how to iterate. However, there is no explicit when-to-use versus brightspace_search_notes or the targeted getter tools, and no when-not guidance (e.g., disabling file search for cheap metadata-only queries).

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

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

Annotations already declare readOnly, idempotent, closed-world, and non-destructive behavior, so the safety profile is covered. The description adds valuable context beyond that: results are line-numbered snippets and the data source is locally imported static snapshots rather than live data, which warns the agent that results may be stale.

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

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

Two short sentences, zero waste, with the core capability front-loaded and the non-live caveat immediately following. 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 two-parameter read-only search tool with rich annotations, the description covers purpose, data source, and result format. Return-value detail is not needed beyond the mention of line-numbered snippets, so it is essentially 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 both 'query' (literal case-insensitive text) and 'limit' fully documented in the schema. The description adds only the notion of 'snippets' and does not elaborate on query syntax or limit behavior, 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 states a specific verb ('Search') and resource ('manually imported local school snapshots'), and adds that results come as line-numbered snippets. It implicitly distinguishes itself from live checks ('These are not live Brightspace checks') but never names the live sibling like brightspace_search_course, so the differentiation is not fully 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 line 'These are not live Brightspace checks' signals the appropriate context (searching imported snapshots rather than live data), which is useful implied guidance. However, it never states when to prefer this over brightspace_search_course or brightspace_read_note, leaving the agent to infer the 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered; the description adds genuinely new behavior — that the default path touches only local setup while verifyConnection triggers an authenticated network call. The secrecy guarantee ("without exposing secrets") is a useful, non-obvious disclosure, though nothing is said about what the check reports back.

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 compact sentences with the default behavior and the secrecy guarantee front-loaded, followed by the opt-in mode. 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?

For a zero-required-parameter, single-boolean tool with no output schema, this covers the essential behavior and the safety profile. The main omission is whether the local inspection surfaces configuration values or just a health verdict, which would help an agent interpret the result.

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

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

Schema coverage is 100%, and the schema text already explains that the flag makes an authenticated API call rather than only inspecting local setup. The description's framing ("verify the school API identity") adds a small amount of meaning — what is being verified — but largely restates the parameter.

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

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

The description names a concrete verb and resource: checking local configuration, with an explicit safety framing ("without exposing secrets"). It is unambiguously a diagnostic/status tool, distinct from every sibling (which all read course content, notes, or grades), though it never states that differentiation explicitly.

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 a clear trigger for the non-default mode ("Set verifyConnection=true to verify the school API identity"), which is real when-to-use guidance for the parameter. But there is no guidance on when to call the tool at all versus just calling an authenticated sibling, and no statement of what the local-only check is useful for.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value by stating the return is an MCP image rather than text and by explaining that `image` selects one embedded slide picture. It doesn't say what happens when the item is not a PDF or PowerPoint, or what errors occur for invalid page numbers.

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

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

Three short sentences, front-loaded with the return behavior and with no filler. Minor ambiguity remains because "Optionally supply image" doesn't spell out that the parameter applies only to slides.

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?

There is no output schema, and the tool has 7 parameters with multiple mutually exclusive ID sets, so the description should carry more weight. It covers the core read behavior and the selection rule but omits how to obtain the IDs, the supported file types, and error behavior.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns extra credit by stating the topic-vs-attachment selection rule, which the schema does not encode (there is no oneOf, and additionalProperties is false). The rule remains vague about which IDs pair with which path, keeping it below a 5.

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 and resource: it returns a rendered PDF page or PowerPoint slide as an MCP image, and the optional `image` parameter targets one embedded picture. It implicitly distinguishes itself from text-oriented siblings such as brightspace_read_topic and brightspace_read_attachment, but it never names them, so the differentiation is inferred rather than stated.

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?

"Choose a topic OR an assignment/news attachment" signals mutual exclusivity between input paths, which is useful guidance. However, it doesn't say which parameters realize each path (topicId vs. fileId plus folderId or newsItemId), and it doesn't say when to use this instead of brightspace_read_topic or brightspace_read_attachment.

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