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

With no annotations provided, the description carries the full burden and does well: it discloses the auth requirement, the workflow, and the rename behavior. It does not state whether an existing file at downloadPath is overwritten or what a successful response contains, which is a modest remaining gap.

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

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

Front-loaded with purpose, then prerequisites, then the interactive instructions. Every sentence earns its place, though the capitalized rename directive is slightly verbose for what it conveys.

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?

No output schema exists, but for a local-download tool the result is largely self-evident. The definition covers prerequisites, access control, and workflow; the only omission is explicit return/overwrite 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 description coverage is 100%, so baseline is 3. The description adds meaning by linking submissionId and fileId to their source tools and tying downloadPath/customFilename to the required user interaction (asking where to save, suggesting a filename), which goes 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?

States a specific verb (download) and a precise resource (a file from a student's or group's dropbox submission) with an explicit audience (instructor or TA). This distinguishes it from the generic download_file and from the read-only get_dropbox_* siblings without opening any schema.

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

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

Explicitly names the prerequisite tools (get_dropbox_submissions / get_dropbox_user_submissions) to obtain submissionId and fileId, states the access requirement (instructor or TA), and gives sequencing instructions (ask for save location first, then suggest a rename). Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does so: it explains inline vs disk consequences, what inline returns per file type (extracted text, image block, short description), size/character caps (10MB, 400,000 chars), the requirement to ask before writing to disk, and graceful behavior when a file isn't released yet (metadata-driven explanation). This is rich disclosure of behavior beyond the 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?

Purpose and mode choice are front-loaded, and most sentences carry actionable content. It is long, and the inline-mode explanation is repeated almost verbatim in both the main description and the downloadPath schema description, which is mild redundancy but not harmful.

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?

Despite having no output schema and no annotations, the description covers the input combinations, both return modes, size limits, and failure cases in enough depth for an agent to call it correctly. Nothing essential 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 coverage is 100%, so the baseline is 3, but the description adds practical meaning: it pairs newsId+fileId, ties fileId to submission/announcement context, and explains the intent of customFilename (suggest a clean readable name). It goes beyond restating the schema, though the downloadPath semantics are largely duplicated from the schema's own description.

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

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

States a specific verb+resource (download a file) and enumerates the three source scopes: course content, assignment/dropbox submissions, and announcement attachments. It also distinguishes the two operating modes, so an agent understands both what it does and how it returns results without opening the schema.

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

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

Explicitly names when to use each mode: inline is 'the right choice in clients like Claude Desktop,' disk requires asking the user for a path, and newsId+fileId come 'from get_announcements.' This gives concrete routing rules and cross-references a sibling tool rather than leaving selection to inference.

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

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

No annotations exist, so the description carries the burden, and it does much of that: it discloses the dual behavior (listing vs reading), that the response is the extracted text itself, and that a sibling should be used for on-disk saving. It omits prerequisites/permissions and rate considerations, so it stops short of full transparency.

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 usage rule and the two-step protocol are front-loaded, and every sentence contributes new information (what it reads, how to call it, when to use it, what it returns, when to use the alternative). 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 read tool with no output schema and no annotations, the description covers the return value ('Returns the text itself'), the listing behavior, and the sibling routing. Only minor gaps remain, such as permissions or what the listing mode returns in detail.

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 (including the omit-to-list semantics of newsId/fileId and truncation via maxChars) is already documented in the schema. The description reinforces the mode-dependent usage but adds no syntax or format detail beyond the schema, which is the baseline-3 case.

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 the files an instructor attached to an announcement') and gives concrete examples of such files. It is clearly distinguishable from the sibling get_assignment_files (assignments vs announcements) and 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?

Explicitly states when to use it ('Use this when the user asks what a file attached to an announcement says'), names the alternative download_file and the exact condition that selects it ('when the user wants the file saved to disk'). It also documents the two-step call pattern (courseId to list, newsId+fileId to read).

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?

No annotations, so the description carries the full behavioral burden. It usefully discloses that attachments are listed per announcement and how to retrieve them, but says nothing about ordering, pagination behavior, auth requirements, or rate limits. Read-only nature is only implied by 'Fetch'/'get'.

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, front-loaded with the core action, then scope, then trigger phrases and routing. No filler; each 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 no-annotation, no-output-schema read tool, the description covers purpose, scope, triggers, and the attachment handoff well. It omits any note on result ordering or what the returned announcement objects look like, which the missing output schema would otherwise require.

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 count, courseId, and modifiedSince in detail (including the filtered-out reporting). The description only restates the courseId/all-courses distinction already present in the schema, adding no syntax or format detail beyond it.

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 ('Fetch recent announcements from your courses') plus scope ('filter to a specific course or get announcements across all courses'). An agent can distinguish it from get_announcement_files, download_file, and get_course_content from the description alone.

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

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

Gives explicit trigger conditions ('when the user asks about announcements, news, updates from instructors, recent posts, or what professors said') and routes the attachment sub-case to named alternatives: download_file (newsId + fileId) or get_announcement_files. This is precise sibling routing, not inference.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly states that the tool reads and 'Returns the text itself,' implying a read-only operation rather than a download. It does not mention auth requirements or unsupported file type edge cases, but core behavior is transparent enough for safe invocation.

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?

Every sentence earns its place: resource identification, call patterns, use cases, return behavior, and the sibling alternative are all covered in three compact sentences. The core purpose is front-loaded and there is no filler.

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

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

Given no output schema and no annotations, the description still covers the main invocation modes, the output nature, the supported file formats via schema, and the key sibling alternative. An agent has enough context to call this tool correctly without further investigation.

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 baseline is 3, but the description adds meaningful workflow semantics: 'Call it with just courseId to see which assignments have attachments, then with folderId and fileId to read one.' This clarifies parameter relationships beyond the schema field 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 opens with a concrete action and resource: 'Read the files an instructor attached to an assignment,' and names likely file types (PDF, workbook, rubric). It also distinguishes itself from the sibling download_file by contrasting reading versus saving, so an agent can tell them apart without opening schemas.

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 explicit when-to-use conditions: 'when the user asks what an assignment requires, what the instructions say, or to summarize a handout.' It also names the alternative: 'Use download_file instead when the user wants the file saved to disk.' It even prescribes a two-step call pattern, which 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?

With no annotations, the description must carry the burden, and it does disclose a non-obvious behavioral trait: the student's own graded outcome is returned only 'once it has been released,' which signals a conditional/latency facet an agent would otherwise miss. It does not mention permission requirements or behavior when no rubric is attached, but for a read-only fetch the disclosure is solid.

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, followed by when to use it. Every clause adds information (return shape, release gating, trigger questions) with no filler 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?

There is no output schema, so the description correctly compensates by enumerating the return payload and the conditional outcome field. It is complete for a two-parameter read tool, though it omits edge cases such as an assignment with no rubric attached and does not address the adjacent get_rubrics_for_object 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 description coverage is 100%, so both courseId and assignmentId are already documented in the schema (including the pointer to get_assignments). The description only restates the 'dropbox assignment' scoping already implied by the schema, adding no new format or constraint detail, so baseline 3 applies.

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

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

States a specific verb ('Fetch') and a precise resource ('full grading rubric for a dropbox assignment'), and enumerates the returned structure (criteria groups, criteria, achievement levels, points, descriptions, plus the student's released outcome). It scopes itself with 'dropbox assignment,' which implicitly separates it from the generic get_rubrics_for_object sibling, but never names that alternative 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 second sentence gives concrete trigger scenarios: questions about what a rubric wants, how an assignment will be graded, or why a particular criterion score was received. That is clear when-to-use guidance, but it offers no exclusions or routing to the sibling get_rubrics_for_object for non-assignment or generic rubric lookups.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses critical tenant-specific data access limitations and instructs the agent to read submissionStatus/attemptStatus rather than raw submission fields, explicitly warning against misreporting 'unknown' items as missing. This is rich, actionable transparency beyond typical tool descriptions.

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, front-loaded with purpose, then return content, usage context, and a critical interpretation caveat. Every sentence earns its place with no redundancy or 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?

With no output schema and no annotations, the description adequately covers what the tool returns, when to use it, and how to interpret ambiguous status values. It is complete for a read-only, single-parameter tool that lists assignments and quizzes.

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% for the single courseId parameter, and the description only restates that omitting it returns all enrolled courses. It adds no new semantic detail (e.g., format, constraints) beyond what the schema already documents.

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 ('Fetch') and resources ('assignments and quizzes') with clear scope ('for a specific course or all enrolled courses'). It also describes returned content (dropbox submissions, due dates, status, rubric info), which differentiates it from narrower siblings like get_assignment_rubric or get_upcoming_due_dates.

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 lists user intents that should trigger this tool: 'assignments, homework, what to submit, quizzes, or assignment details and rubrics.' However, it does not name alternative tools or state when not to use this one, so it stops short of full 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?

With no annotations, the description carries the full burden and does disclose useful defaults (7-day window, from=now) and the reason includeGenerated is off by default. However it says nothing about ordering, pagination, result limits, or what an empty window returns, and doesn't address permission/auth needs. Solid on defaults, thin on output 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?

Front-loaded with the verb and resource, and the usage trigger comes after the scoping details. The long em-dash enumeration of event types is informative but slightly padded; a shorter list would carry the same routing 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?

For a read-only fetch tool with no output schema and no annotations, the description covers scope, defaults, and cross-tool routing adequately. It doesn't describe the shape of returned events, but the core calling decision is well supported.

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 four parameters including the ISO 8601 format and defaults. The description restates the 7-day default window but adds no format or syntax detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (Fetch) and resource (course calendar events), and enumerates the event types it returns (exams, midterms, labs, recitations, review sessions, schedule changes, instructor-typed deadlines). It also distinguishes the scope (all courses vs one course) from sibling list-style tools, so an agent can pick it without opening the schema.

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

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

Gives explicit trigger conditions: 'Use this when the user asks when an exam is, what's on their calendar, or what's happening this week.' The includeGenerated param description routes the agent away from this tool for assignment/quiz/discussion due dates toward get_upcoming_due_dates and get_assignments. Lacks an explicit 'when not to use' for the main calendar surface, but the routing 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?

No annotations provided; description fails to disclose authentication requirements, side effects, or any behavioral traits. It implies a read operation but without explicit statement, leaving the agent without critical safety cues.

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 fluff, front-loaded with purpose then usage scenarios. Every sentence adds 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?

Simple tool with one parameter. Description covers purpose and usage but omits return format (e.g., list of emails, comma-separated). Adequate but could improve.

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 covers the single parameter with a description. The tool description does not add additional semantic value beyond the schema, meeting baseline for 100% coverage.

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 fetches email addresses for all roles (instructors, TAs, students) in a course. It uses specific verb and resource, and distinguishes from siblings like get_roster by focusing solely on emails.

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

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

Provides explicit usage scenarios such as when the user wants a list of emails for a class. Lacks explicit when-not-to-use or alternatives, but the context is clear enough.

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 no annotations, the description carries the full burden and does well: it explains that unavailable modules/topics expose isAvailable/availabilityStatus/availabilityMessage (plus startDate/endDate) and that field absence means currently available — non-obvious return-shape behavior. It omits any note on response size, pagination, or auth expectations.

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

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

Front-loads the core fetch statement, then usage triggers, then parameter tips, then the availability caveat. Every sentence carries distinct information with no 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?

No output schema exists, so the description must convey return structure, and it names the node types and the availability-field convention. It is largely sufficient for a read-only fetch, though a fuller account of nesting/output shape would complete 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 coverage is 100%, so the schema already documents all five parameters (baseline 3). The description still adds value by giving concrete moduleTitle examples ('Labs', 'Staff', 'Homeworks') and framing maxDepth as a table-of-contents view, reinforcing the intended usage.

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 (fetch) and resource (the content tree for a course) and enumerates its shape — modules, topics, files, links. This lets an agent distinguish it from siblings like get_syllabus or get_my_courses without opening a schema.

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

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

Gives explicit positive triggers ('course materials, lecture slides, uploaded files, content structure, or what's in a course module') and tells the agent to use moduleTitle to target a single module rather than pulling the whole tree. It does not name a sibling tool as an alternative or state any when-not condition, so it stops short of the top score.

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?

No annotations provided. Description focuses on functionality without mentioning behavioral traits like read-only nature, authentication needs, or side effects. For a fetch operation, this is adequate but could be more 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 sentences. Front-loaded with purpose. No redundant information. Efficiently conveys parameter combinations and usage guidance.

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

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

Given 100% schema coverage, no output schema, and no annotations, the description is complete for a simple fetch tool. It covers all parameter scenarios. Lacks mention of return format or whether it's read-only, but these are not critical for this 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 already covers all parameters with descriptions. Description adds significant value by explaining how parameters interact hierarchically (e.g., just courseId lists forums, add forumId for topics, add topicId for posts). This clarifies usage beyond individual field 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?

Description clearly states the verb 'Fetch' and resource 'discussion board content for a course including forums, topics, and posts'. It distinguishes from sibling tools like get_announcements and get_assignments which cover different content.

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

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

Explicitly states when to use: 'when the user asks about discussion boards, forum posts, class discussions, or wants to see what's been posted.' Provides parameter usage patterns but does not mention when not to use.

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 no annotations, the description carries the full behavioral burden. It discloses the access requirement (instructor/TA) and the shape of the returned data, and 'Retrieve' implies a read-only operation, but it doesn't state what happens when no feedback exists or any error/permission-failure 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 efficient sentences with the core purpose front-loaded before the usage cue and access note. The field enumeration adds length but serves meaning; nothing is 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?

There is no output schema, so the description appropriately lists the returned fields itself, and it covers the access prerequisite. An agent has enough to call it correctly, though no note on empty results or pagination leaves 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?

Schema description coverage is 100%, so all four parameters (courseId, folderId, entityType, entityId) are already documented including the user/group enum. The description restates the user-or-group concept but adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (retrieve) and resource (existing saved feedback for a user/group in a dropbox folder) and enumerates the returned fields (score, graded state, feedback text, rubric detail). An agent can distinguish this from the many get_dropbox_* siblings that deal with submissions or folders rather than feedback records.

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 to use it 'before drafting new feedback to see what has already been recorded,' giving a clear usage context. It also states the access prerequisite (instructor or TA). However, it names no alternative tool or when-not-to-use condition.

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 no annotations present, the description carries the full burden and does so well: it discloses the permission model (reads the same folder listing a student client uses, unlike the gated submission/download tools) and enumerates the returned fields (folder ID, name, due/start/end dates, submission type, visibility, rubric attachment). Auth behavior and payload shape are both 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?

Three sentences, front-loaded with the core action, then return fields, then usage routing and the access nuance. The field enumeration is somewhat dense but earns its place given there is no output schema; no sentence is filler.

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

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

For a one-parameter read tool with no annotations and no output schema, the description covers purpose, return contents, downstream usage, and the permission caveat. An agent has everything needed to select and call it correctly without opening anything else.

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?

Only one parameter, courseId, and schema description coverage is 100%, so the schema already documents it fully. The description adds only the implied 'for a course' framing and no format or constraint details beyond the schema, 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?

States a specific verb and resource ('List all assignment/dropbox folders for a course') and immediately scopes the audience (instructor or TA). It is clearly distinguishable from the sibling submission/feedback tools, which operate on a single folder rather than listing folders.

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

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

Gives explicit routing guidance: use this to discover folderId values before calling get_dropbox_submissions, get_dropbox_user_submissions, get_dropbox_feedback, or get_rubrics_for_object. It also pre-empts a likely question by noting the tool is not gated to instructor/TA accounts the way those siblings are.

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 no annotations, the description carries the full burden and does so richly: instructor/TA-only access, a graceful 'clear note' for student accounts, limit capping (default 100, max 1000), explicit truncation signaling, and the side effect that feedback is only fetched for the returned slice. These are real behavioral traits an agent needs.

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

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

Front-loads the purpose, then sequencing, then access/behavioral and pagination constraints in tightly packed sentences. Every clause earns its place with no redundancy.

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

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

No output schema or annotations exist, yet the description covers access requirements, returned fields, the truncation/pagination model, and cross-tool sequencing. Nothing an agent needs to call it correctly 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%, so all five parameters (including activeOnly and ignoreFeedback semantics) are already documented in the schema. The description's limit note restates what the schema already says, so it adds little beyond 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 ('List') and resource ('every student's/group's submission to a dropbox folder') and enumerates the returned fields. It is clearly distinguishable from siblings like get_dropbox_user_submissions and get_dropbox_feedback, so an agent can select it without opening other schemas.

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 routes the agent: use get_dropbox_folders first to get folderId, and steers students to download_file / get_assignments for their own submission. Both the when-to-use and the when-not/alternative are named.

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?

No annotations are supplied, so the description carries the full behavioral burden. It discloses the permission requirement (instructor or TA access) and the read-only nature implied by 'Retrieve,' but says nothing about the response shape, volume/pagination, or how feedback data behaves relative to the ignoreFeedback flag.

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 compact sentences, with the core action and scope front-loaded before the usage hint and the access caveat. No sentence is 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 read-only retrieval tool with no output schema, the description covers purpose, scoping, prerequisite lookups, and access requirements. It stops short of describing what the response contains, but nothing essential for correct invocation 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%, so all four parameters are already documented, including the note that userId may be a group ID. The description restates this in prose ('student (or group)') but adds no syntax or format meaning beyond the schema, 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 gives a specific verb ('Retrieve'), a specific resource ('submissions made by one specific student (or group) in a dropbox folder'), and an explicit audience (instructor or TA). It clearly distinguishes itself from the sibling get_dropbox_submissions, which returns the unfiltered set.

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 states the scenario (reviewing one student's work before drafting feedback), names the alternatives for a prerequisite step ('Use get_dropbox_submissions or get_roster to find the userId first'), and gives the access condition. The agent knows both when to reach for this tool and how to obtain the required identifier.

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 no annotations, the description must carry the behavioral disclosure burden. 'Fetch' clearly indicates a read-only operation and 'your enrolled' defines scope, but it does not disclose authentication requirements, error behavior, or the fact that the result is a list. It is adequate but minimal.

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 redundancy. The first sentence states the core purpose, and the second provides actionable usage triggers. Every word 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 list tool with one optional parameter and no output schema, the description covers the essential context: what is returned and when to use it. It could mention that no other prerequisites exist or how results are ordered, but nothing critical is missing.

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

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

The single parameter activeOnly is fully described in the input schema, including its default behavior, so the schema covers the parameter semantics completely. The description adds no parameter-specific guidance, which is acceptable given 100% schema coverage.

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 action ('Fetch') and resource ('your enrolled Brightspace courses') and enumerates the fields returned (names, codes, IDs). It is unambiguously distinct from siblings like get_course_content or get_roster, so an agent can immediately tell what this tool does.

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 explicit triggers: user asks about courses, enrolled classes, this semester, or needs a course ID for other queries. It does not explicitly mention when not to use it or name alternatives, but the use cases are concrete and sufficient for most situations.

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?

No annotations provided, so description must disclose behavioral traits. It only mentions output format (points, percentages, comments) but does not state that it is a read-only operation, any permissions needed, or side effects.

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, both front-loaded with key information. No unnecessary words.

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 tool with one optional parameter and no output schema, the description provides adequate context: action, scope, output content, and usage hints. Missing explicit read-only declaration, but overall 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 coverage is 100%, with a clear description for courseId. The description adds context about the response but no additional parameter semantics. 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 fetches grade breakdowns for a specific course or all courses, with specific fields (points, percentages, comments). It distinguishes itself from sibling tools like get_assignments by focusing on 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?

Explicitly lists when to use: when user asks about grades, scores, marks, GPA, academic performance. Does not mention when not to use or alternatives, but the guidance is clear and sufficient.

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?

No annotations are provided, so the description carries the full disclosure burden. 'List' implies a read-only, current-user-scoped operation, and the description does state that member data is included in the result, but it says nothing about permissions, pagination, or what happens for a course where the user has no groups.

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 waste, with the capability stated first and the usage trigger second. Nothing to trim.

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 single-parameter read tool this is nearly complete: the description substitutes for the missing output schema by naming the return content (groups plus their members). It could still note permission expectations or empty-result behavior, but no critical information is missing for correct invocation.

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

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

Only one parameter and schema description coverage is 100%, so the schema already fully documents courseId. The description's 'in a course' phrasing confirms the scoping intent but adds no syntax or format 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 (list) and resource (current user's project/discussion groups in a course) and adds that members are included, which separates it from sibling roster/classlist tools that return whole-class data.

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

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

Explicitly says when to use it: 'when a student asks who is in their project group, lab group, or discussion group.' It gives clear triggering contexts but names no exclusions or alternative (e.g. get_roster for the full class), so it stops short of full 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals a key privacy-related default: 'By default returns only instructors and TAs for privacy' and explains that includeStudents provides the full class list. This goes beyond the schema's default value by adding rationale and context. It does not cover permissions or result formatting, but the central behavioral trait 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 sentences with no filler. The first sentence states the core operation and scope, the second gives concrete usage triggers, and the third explains the default and how to override it. Every sentence earns its place and key 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 fetch tool with no output schema and no annotations, the description plus fully documented schema covers the essential aspects: what is returned, default behavior, and when to use it. It does not mention truncation or search filtering, but those are already explained in the parameter descriptions. Minor gap: no explicit note about the response shape, but the content description suffices.

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 baseline is 3. The description adds marginal value by explaining includeStudents in terms of the default privacy behavior, but it does not elaborate on limit, searchTerm, or courseId beyond what the schema already provides. This is adequate but not exceptional.

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: 'Fetch the roster for a course' and enumerates the contents (instructors, TAs, optionally students) plus names, emails, and roles. It gives clear use cases (classmates, instructor contact info, TA emails, professor names), but does not explicitly differentiate from the sibling get_classlist_emails, so it falls short of a 5.

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 'Use this when the user asks about classmates, instructor contact info, TA emails, professor names, or who's in a class,' giving clear context for when the tool is appropriate. It does not name any alternative tool or provide exclusions, so it earns a 4 rather than 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?

No annotations exist, so the description carries the burden and does meaningfully address it: it discloses the data source (the folder listing's embedded rubric data) and the authorization profile relative to sibling tools. The phrase "for an instructor or TA" followed by "not gated to instructor/TA accounts" is slightly confusing, and it says nothing about the response shape or pagination.

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

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

Three sentences, front-loaded with the retrieval purpose, then the prerequisite, then access-control context. Each sentence contributes, though the closing gating sentence is somewhat dense and introduces the minor audience ambiguity.

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 enumerates the returned content (criteria, levels, point values) and covers prerequisites and access behavior. Complete enough to call correctly, with only minor gaps around return format and pagination.

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 folderId are already documented. The description adds only a discovery hint for folderId, which is more usage guidance than parameter semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb ("Retrieve") and resource ("full rubric table (criteria, levels, and point values) attached to a dropbox folder"), which distinguishes it from siblings like get_assignment_rubric and get_dropbox_folders. An agent can identify its scope without opening the schema.

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

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

Gives a clear prerequisite ("Use get_dropbox_folders first to find folderId") and positions the tool within the dropbox family by contrasting its gating with get_dropbox_submissions and get_dropbox_feedback. It lacks an explicit when-not rule versus get_assignment_rubric, which also returns rubric data.

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 no annotations, the description carries the full burden and does well: it discloses that it never contacts Brightspace and never returns secrets, and flags conditional fields (browser sign-in saved, when signed in). It stops short of stating response format or failure modes, but the safety profile is clearly communicated.

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

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

Content is not padded, but it is delivered as one very long run-on sentence enumerating many return fields, which is hard to scan. The headline (which version is running) is front-loaded, but the middle clumps together unrelated details.

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 enumerates the returned fields, which is exactly what an agent needs to interpret results. It covers version, environment, config, identity, and counters adequately for a diagnostic 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 takes zero parameters, so the baseline is 4. There is no parameter semantics to add, and the schema confirms an empty object.

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 ('Report') and enumerates exactly what is reported (server version, Node runtime, platform, config path, timezone, account identity, request counters). This is unmistakably distinct from the Brightspace data-retrieval siblings like get_my_courses or get_announcements.

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

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

Gives explicit triggers: troubleshooting, user asking which version they have, or checking what timezone/account dates compute against. It also implicitly routes away from the data siblings by noting it 'never contacts Brightspace', though it does not name an explicit alternative tool.

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?

Discloses that the tool returns markdown text, conditionally downloads attachments, and requires user consent for file saving. Without annotations, it covers key behaviors.

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, all essential: purpose, return format, conditional behavior, and critical usage note. No redundancy.

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

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

Covers all necessary information for a two-parameter tool: input, output format, conditional download, and user-consent requirement. No output schema needed.

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?

Adds value beyond schema by explaining that downloadPath triggers a download and that the text is markdown. Schema already describes both parameters fully.

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 'Fetch' and the resource 'syllabus/overview text and optional attachment', distinguishing it from sibling tools like get_assignments or get_course_content.

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

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

Provides explicit instruction to ask the user for file save location before using downloadPath, but does not explicitly state when not to use the tool or suggest alternatives.

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 no annotations, the description carries the full behavioral burden. It usefully discloses the data provenance (dropbox folders, quizzes, graded discussions, calendar events of type 'event'), which is real context, but says nothing about read-only safety, ordering, timezone handling, or pagination limits. Adequate but incomplete for a tool with zero 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?

Two sentences: the first front-loads the core action with provenance detail, the second handles usage. The source enumeration in sentence one is somewhat clause-heavy, but nothing is wasted and the order is sensible.

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 tool with no output schema and no annotations, the description covers what is fetched, from where, and when to call it. It does not hint at the returned structure (fields, sorting, time window defaults), which would help an agent interpret results, but the essentials are 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 both parameters (courseId, daysAhead) are already documented, setting the baseline at 3. The phrase 'across all your courses' does imply the unfiltered default behavior when courseId is omitted, which adds a small amount of meaning beyond the schema but not enough to raise the score.

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 (fetch upcoming due dates) and defines scope precisely: across all courses, derived from assignments, quizzes, graded discussions, plus calendar events of type 'event'. An agent can distinguish it from get_assignments or get_calendar_events because it is explicitly an aggregation across those sources.

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 concrete trigger phrases: deadlines, what's due, upcoming work, what they need to do this week. That is strong when-to-use guidance, but it never names an alternative (e.g., get_calendar_events for non-graded events) or states exclusions, so it stops short of the top score.

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 no annotations, the description carries the burden well: it declares read-only behavior ('never marks the video as watched'), enumerates supported platforms, and describes the unsupported-platform fallback message. It omits any auth/permission or rate-limit context, but covers the important side-effect disclosure.

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, front-loaded with purpose then call patterns then return/limitations/read-only. Every sentence earns its place with no redundancy.

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

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

No output schema exists, yet the description specifies return contents (timestamped transcript text, title, duration when available, truncation signal). Combined with platform and pagination notes, an agent has everything needed 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 coverage is 100%, so the schema already documents all five parameters (baseline 3). The description adds cross-parameter relationships — the courseId/topicId pairing vs. standalone videoUrl, and the offset/maxChars paging loop — giving meaning beyond isolated field docs.

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 (transcript of a video embedded in course content), scoping it to recorded lectures/clips. Clearly distinguishable from sibling content tools like get_course_content.

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

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

Gives explicit invocation paths: courseId+topicId sourced from get_course_content (typeFilter 'video'/'other'), or videoUrl directly. Names platform limits (Kaltura/YouTube only) and pagination via offset/maxChars.

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 no annotations, the description carries the full burden and does so well: it discloses the ranking algorithm (all-terms match > partial, title > body), graceful degradation ('If one source... can't be read, it's skipped and named in `note`'), and the performance cost of fanning out. It omits auth/permission requirements and whether results are paginated beyond `limit`, keeping it from a 5.

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, and the core purpose and examples are front-loaded. The opening sentence is heavily parenthesized, which slightly slows scanning, but there is no filler.

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

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

For a 3-param, no-output-schema tool, the definition covers purpose, trigger conditions, ranking semantics, partial-failure behavior and cost, which is everything an agent needs to choose and call it correctly. Return shape is inferable from the ranking/note discussion even without an output schema.

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 courseId, query and limit with its own examples. The description restates the keyword-style query but adds no new format, constraint, or syntax information beyond the schema, so the baseline 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?

Opens with a specific verb+resource ('Search a course's content... announcements, and discussion forums/topics by keyword') and enumerates exactly what is searched. It also distinguishes itself from siblings by contrasting the fan-out search with 'reading the whole content tree' and with get_course_content.

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

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

Explicitly states when to use it ('when the user wants to find something specific') with two concrete user-utterance examples. It also names an alternative path ('slower than calling a single tool like get_course_content directly'), giving the agent a real routing decision.

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