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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds that the result contains item titles and messages rather than counts, which is genuine context beyond annotations, but says nothing about volume, pagination, or how far back events go despite an output schema existing.

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?

Very short and front-loaded, with the core statement first and the sibling comparison second. No wasted sentences, though the em-dash fragment is slightly loose in phrasing.

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 list/stream tool with one undocumented parameter, the description leaves the parameter unexplained and gives no sense of result scope or size. The presence of an output schema covers return-value structure, but the parameter gap and unquantified 'recent' keep this from being 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 0% and there is one optional parameter, only_active_courses, which the description never mentions. The description's 'recent Canvas events for the user' hints at scope but does not explain what flagging only_active_courses does or why one would set it, leaving that parameter's semantics entirely to its suggestive name.

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: a full activity stream of recent Canvas events for the user. It also names the sibling activity_stream_summary and explains the difference (actual titles and messages vs. just counts), which distinguishes it from that sibling, though not from the other ~45 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?

Implies usage by positioning itself as the detailed alternative to activity_stream_summary, but gives no explicit when-to-use or when-not-to-use guidance. An agent can infer 'use this for detail, use summary for counts' but nothing more, such as how many events are returned or how recent 'recent' is.

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

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

The annotations already declare readOnlyHint=true, non-destructive, and openWorld, so the safety profile is covered. The description adds genuine context beyond that: it is an aggregate count rather than a listing, it is explicitly a cheap call, and it names the concrete payload shape (unread_count plus total per type). It does not discuss data freshness or caching, which is the only notable 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?

Three short sentences, front-loaded with the core definition, then the payload shape, then the usage hook. No filler or repeated framing; 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?

With zero parameters, full annotations, and an output schema already documenting return values, the description only needs to explain what the aggregate represents and when to reach for it, which it largely does. The missing piece is an explicit contrast with activity_stream and whats_new, which share this tool's territory.

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. It correctly focuses on describing the output semantics instead of inventing parameter guidance.

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-and-resource pairing: 'aggregated unread counts by notification type,' and enumerates the actual types (Announcement, DiscussionTopic, Submission, Message, Conversation). It is clear what the tool returns, but it never names the sibling it differs from (activity_stream, whats_new), so an agent must infer the distinction itself.

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?

'Great for what changed since last check' implies a use case, and 'cheap call' signals it is a low-cost first probe. However, there is no explicit when-not guidance and no mention of alternatives such as activity_stream for item-level detail, leaving the routing decision implicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior – receipts are process-local and an unknown ID after restart is not evidence of write failure – which is valuable context beyond the annotations. However it says nothing about receipt lifetime, retention, or what the 'uncertain' state means operationally, keeping it at a solid 3.

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 core action and followed by the critical caveat about process-local receipts. No filler sentences, though the line-wrapping adds no structure and the middle and last sentences overlap slightly on the 'unknown ID' idea.

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?

An output schema exists, so return-value description is unnecessary, and the description focuses on the non-obvious operational hazard. The main omission is not telling the agent which tool produces the action_id, which matters for a one-parameter lookup 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 0% for the single action_id parameter, so the description must carry meaning and only partially does: 'unknown ID' implies the ID comes from a prior prepare/receipt, but it never says where to obtain it or its format. Baseline credit for a one-parameter tool, with a clear gap.

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 a prepared/completed/uncertain action receipt') and names the states the receipt can be in, which is concrete. It does not explicitly name the sibling tools it complements (canvas_execute_action, canvas_cancel_action, canvas_prepare_*), so sibling differentiation is only implied.

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 real usage direction: read the receipt 'without retrying a write', and 'inspect Canvas before preparing another action' when an ID is unknown. It stops short of naming the alternative tools (execute/cancel) or stating exclusions explicitly, so it's clear context rather than a full when/when-not map.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description earns credit for genuine additions beyond that: lists return next_offset, limit is bounded 1..100, quiz reads are metadata only, and a failed section is never presented as an empty list (error-vs-empty semantics). It still says nothing about the refresh parameter's effect or caching 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?

The core capability and the section list are front-loaded, followed by pagination and caveat notes. Dense but each sentence carries operational information; only the confidence-signal sentence about failed sections could be tightened.

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 an output schema present and annotations covering safety, the description need not explain return shapes, and it correctly focuses on scoping, pagination and known failure modes. The remaining gap is the unaddressed relationship to sibling list/module tools and the unexplained refresh parameter.

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

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

Schema description coverage is 0%, so the description must carry semantics, and it partially does: it names all section values and constrains limit to 1..100 while explaining that lists return next_offset for offset-based paging. It leaves 'refresh' and 'offset' entirely unexplained and does not describe course_id expectations, so the compensation is incomplete for a 5-parameter tool.

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 ('Browse a course section') and enumerates all nine sections the tool can return, so the agent knows exactly what is retrievable. It does not differentiate the tool from sibling list_* tools (list_modules, list_assignments, list_discussions, list_announcements) that overlap the same resources, leaving the relationship to inference.

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 section enumeration, and there is one explicit conditional path: when files enumeration is forbidden, follow the modules alternative returned in that case. However, there is no guidance on when to choose this unified browser over the granular sibling listers, and no prerequisites or exclusions 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 readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior — that offset windows are fresh reads that can shift as files change, and that download_file only persists files locally in stdio — but says nothing about pagination limits or auth/scope requirements. It also references a parent_folder_id field that appears nowhere in the input schema, which risks confusing the agent about where that value comes from.

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 core purpose, then the routing and caveats in short sentences with no filler. The parent_folder_id sentence is stranded, though, since it refers to something the input schema never defines.

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?

An output schema exists, so return values need not be described, and the read/download alternatives are covered. But for a five-parameter listing tool with zero schema descriptions, leaving kind and search_term undefined means an agent cannot confidently construct a filtered browse call from this definition alone.

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

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

Schema description coverage is 0%, so the description must carry the semantics, and it only partly does: folder_id (omit vs provide) and offset (fresh, unstable windows) are explained well, but kind (files vs folders enum), limit, and search_term are never mentioned. Two of five parameters remain semantically opaque.

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?

"Browse personal Canvas files or folders, including submission folders" names a specific verb and resource with scope (personal, submission folders), and the closing sentences explicitly separate this listing tool from canvas_read_file and download_file, which share the same file domain.

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 routing rules: omit folder_id to list personal files/all folders, supply it for immediate contents, use canvas_read_file to read, download_file to save an original. What's missing is guidance on the remaining modes (kind files vs folders, search_term) and any explicit 'don't use this for X' exclusion.

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

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

Beyond the annotations, it discloses that the discard is local-only and never contacts a Canvas write endpoint, and that already-executing actions are out of scope. It does not say whether a discarded action is recoverable or idempotent, which would complete the picture for a state-changing call.

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

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

Three short sentences with zero filler; the primary action is front-loaded and the negative constraints follow immediately after. Nothing is repeated from schema or annotations.

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?

An output schema exists, so return values need no explanation, and the annotations cover the safety profile. However, for a state-changing tool the definition leaves open the id's provenance and post-cancel state of the discarded action, which an agent still needs in order to call it safely.

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 0% for the single required action_id, so the description must carry the semantics. It only indirectly conveys that the id refers to a previously prepared action, without saying where the id comes from (prepare/status tools) or what happens with an unknown or stale id.

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?

Uses a specific verb and resource ('Discard a prepared action') and implicitly separates itself from canvas_prepare_* (create), canvas_execute_action (run), and canvas_action_status (inspect). An agent can tell what this tool does and does not do 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?

Gives a clear trigger condition ('if the user declines or no longer wants it') and an explicit exclusion ('an executing action cannot be cancelled here'), plus a redirect to inspect the receipt and Canvas state. It stops short of naming the sibling tools that provide those alternatives, but the routing intent is unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: results are deployment-level, still gated by account permissions and assignment restrictions, and are not evidence that any action succeeded — an important interpretive constraint for an agent.

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 core purpose, followed by two qualifiers that each carry real meaning. No filler, though the second and third sentences could be tightened into one.

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?

An output schema exists, so return values need not be explained, and the description covers what the output means and its limits. The remaining gap is relational — it never positions itself against the sibling capability/status tools — but for a zero-parameter introspection call this is close to 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 no parameter meaning for the description to supply; the baseline of 4 applies. Nothing in the description misleads about inputs.

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 ('Describe') and a specific resource ('this deployment's actual read, write, and local workspace capabilities'), which tells an agent exactly what it returns. It does not, however, distinguish itself from near-neighbours like canvas_document_capabilities or canvas_confirmation_capabilities, which also sound capability-oriented.

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 rather than stated: the caveats about account permissions and 'not proof that a particular action succeeded' hint that this is a pre-flight/awareness call, but the description never says when to call it or when a sibling is the better choice. With three capability-flavoured siblings present, an explicit routing sentence is missing.

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 the safety profile (readOnlyHint=true, destructiveHint=false), so the description's real contribution is the disclosure that this touches only local navigation cache and performs no upstream Canvas writes. It further characterizes the cache with a 90-second TTL, a 128-entry/8 MiB bound, and invalidation on credential replacement — concrete behavior not present 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?

Three short sentences, front-loaded with the action and its scope, then the two facts that most affect a decision to call it (TTL and bounds). No filler, no restating of the tool name, no redundant safety boilerplate.

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

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

For a zero-parameter tool with an output schema and full annotation coverage, this covers scope, safety boundary, and cache lifecycle well. The one gap is that it does not state the effect on in-flight or subsequent navigation calls (i.e., that the next call repopulates the cache), though the output schema carries return details.

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 no parameter meaning to convey; the baseline for a no-argument tool applies. The description correctly avoids inventing scope or filter options that the empty schema does not support.

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 with an explicit scope: "Clear this account's navigation cache." The scope qualifier ("this account's") and the note that it makes no upstream Canvas writes make it unmistakable against every sibling in the list, none of which touch local cache state.

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 explicit when-to-use clause and no named alternative, but the stated 90-second default TTL implicitly tells the agent that manual clearing is usually unnecessary and that waiting is a valid substitute. "Credential replacement creates a fresh cache" gives a second implicit condition under which calling this is redundant.

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 set readOnlyHint, destructiveHint=false, and openWorldHint, but the description adds meaningful behavior: no prompt or Canvas contact, no connector form or elicitation, and unchanged platform approvals. This clarifies the tool's safety and authorization side effects beyond the structured annotations, and it does not contradict the read-only and non-destructive annotations.

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

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

The description is short and front-loaded, with each sentence adding either scope or a behavioral constraint. The wording is dense but not wasteful, though the line breaks and abstract phrase 'conversational authorization policy' slightly reduce immediate clarity.

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

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

For a zero-parameter reporting tool with an output schema and read-only annotations, the description covers purpose, non-contact behavior, and authorization constraints well enough to invoke correctly. It could be stronger with explicit guidance on when to use it versus sibling capability tools.

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

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

The input schema has zero parameters and is fully self-contained, so the baseline is 4. The description adds no parameter meaning, but none is needed for an 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?

The description states a specific verb and resource: 'Report conversational authorization policy,' and adds a scope boundary: 'without prompting or contacting Canvas.' It does not explicitly differentiate this from sibling capability tools such as canvas_capabilities, 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?

No explicit when-to-use or when-not-to-use guidance is provided, and no sibling alternative is named. The statement that user authorization is still required describes a constraint rather than a rule for selecting this tool, leaving the agent to infer when to call it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: credentials are never exposed, errors propagate rather than being swallowed, and a generic health check is insufficient to prove Canvas auth. That last point is the most valuable disclosure and prevents false-positive verification.

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 short sentences, front-loaded with the core purpose and followed immediately by the trigger condition. 'Errors propagate.' is terse but earns its place as an explicit failure-mode contract. No padding or repetition.

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

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

For a zero-parameter, read-only diagnostic tool with an output schema already defined, the description covers everything an agent needs: what it verifies, when to call it, the credential-safety guarantee, the health-endpoint caveat, and error behavior. No meaningful gap remains.

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 schema imposes no semantic burden and the baseline of 4 applies. Nothing in the description is needed to explain inputs, and it correctly spends its words on behavior instead.

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

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

States a specific verb ('Verify') and specific objects ('configuration and live Canvas authentication'), with a scope note that it does so 'without exposing credentials'. It is clearly distinguishable from data-listing siblings like list_active_courses, though it doesn't explicitly contrast itself with the similarly-named canvas_capabilities or canvas_document_capabilities.

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 concrete triggers: 'Call when a tool fails with 401 or to check a fresh deployment.' That is a real when-to-use rule, not vague guidance. No explicit when-not-to-use or named alternative is provided, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: hidden and external tabs are preserved, and some views are reported as browser-required, which warns the agent that certain results cannot be rendered server-side. The instruction not to guess endpoint paths is a useful behavioral constraint on follow-up calls.

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 core action, with no filler. Minor ambiguity remains in the undefined phrase 'returned open objects', which assumes context the description never establishes, but the overall density is good.

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?

An output schema exists, so return values need no prose, and annotations cover the safety profile. The description adequately explains the resolution behavior and the browser-required caveat for a read-only navigation tool; the only substantive gap is the unexplained refresh parameter.

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

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

Schema description coverage is 0%, so both parameters (course_id and refresh) are undocumented in the schema, and the description does not mention either one. It never explains that course_id identifies the target course or what refresh does (e.g., bypass a cached Home view), leaving the agent to guess at a parameter that materially affects behavior.

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: opening a course's Home view plus the server-provided navigation tabs, and it clarifies that it resolves front-page content or a route into modules/assignments/syllabus. That is far more concrete than a sibling like get_course, though it never explicitly says how it differs from canvas_browse_course or get_course, so the differentiation is inferential 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?

It gives a clear usage rule for the result ('Follow returned open objects; do not guess endpoint paths'), which is genuinely actionable. However, it never states when to reach for this tool versus get_course, canvas_browse_course, or canvas_open_item, so the agent must infer the selection criteria from the sibling 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 cover read-only, open-world, non-destructive behavior, and the description adds real context beyond them: results carry fetched_at and cache_hit, and there is a short per-account memory cache that refresh=True bypasses. That cache-staleness detail is exactly the kind of trait annotations cannot express; only the precise shape of the "next-step navigation" payload is left 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?

Three compact sentences with the entry-point cue front-loaded, followed by the navigation model and then the caching note. No sentence is redundant, and the cache note is placed where it matters, next to the only parameter's behavior.

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 annotations, an output schema, and only one optional parameter, the definition covers what an agent needs: entry point, traversal model, freshness metadata, and cache override. Minor gaps remain, such as what qualifies as "active" and whether archived courses are excluded, but nothing blocking 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 0%, so the description must carry the meaning, and it does: refresh=True is explained as bypassing a short, per-account memory cache, which tells the agent both what it does and when a stale read is possible. The cache's "short" duration is not quantified, though the default-false behavior is clear from the schema.

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

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

The description states a concrete resource and scope: "active Canvas courses with explicit next-step navigation," plus an entry-point role ("Start here"). That distinguishes it from a bare lister, though it never names sibling tools like list_active_courses or canvas_course_home, so the boundary 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?

"Start here" gives implied orientation guidance for a first call, and the navigation chain suggests it is a stepping stone to deeper tools. However, with many overlapping siblings (list_active_courses, canvas_course_home, canvas_browse_course), no explicit when-to-use/when-not or alternative routing is provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description does add useful substance beyond that — it discloses that reading limits are 'bounded' and that OCR/conversion support is stated 'explicitly' — which tells the agent the response carries constraint information. It stops short of saying whether limits are per-file or per-account, or what happens when a document exceeds them.

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?

It is certainly short, but the brevity comes at the cost of structure: it is an unpunctuated nominal fragment rather than a front-loaded statement of action. Very little is wasted, yet the single clause does not orient the agent before it reads further.

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?

An output schema exists, so the description need not explain return values, and there are no parameters to document. What remains missing is the routing information — when this introspection tool is warranted relative to canvas_capabilities and the file-reading siblings — which is the main thing an agent needs here.

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 and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 applies for a no-parameter tool.

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 is a noun-phrase fragment ('Supported formats, bounded reading limits, and explicit OCR/conversion availability') with no verb, so the agent must infer that the tool reports capability metadata rather than manipulating documents. It also does not distinguish itself from the sibling canvas_capabilities or canvas_confirmation_capabilities, which sound nearly identical in scope.

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

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

There is no statement of when to call this tool, no prerequisite context, and no pointer to the closely named canvas_capabilities sibling as an alternative. The agent is left to guess whether this should be consulted before get_file, fetch_file_content, or canvas_read_file.

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 flag this as a destructive, open-world write, and the description adds substantial context beyond them: no server-side consent collection or confirmation form, client/platform approvals still apply, immutable bytes plus target/account/expiry checks and final verification remain enforced, and blind retries of completed/cancelled/uncertain writes are forbidden. This is exactly the operational and safety detail an agent needs for an irreversible action.

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 core action, then authorization prerequisites, then enforcement guarantees — a sensible order for a destructive tool. There is mild redundancy between "Do not ask again when the current conversation already supplies it" and "If unclear, ask the user before calling," and the trailing paragraph could be tightened, but nearly every sentence carries policy weight.

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?

An output schema exists, so return values need not be explained, and the description covers authorization, verification, expiry, and retry policy thoroughly. The remaining gap is provenance of action_id and what the agent should do if the action has expired or the server rejects it — presumably canvas_action_status / canvas_prepare_* again, but that routing is left implicit.

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

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

Schema description coverage is 0% for the single action_id parameter, so the description carries the burden. It implies the id refers to a previously prepared action and that expiry checks apply, which hints at lifetime, but it never says where action_id comes from (presumably canvas_prepare_upload / canvas_prepare_submission) or how to recover it. Partial compensation only.

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 ("Execute a prepared upload/submission") and makes clear it operates on an already-prepared action rather than creating one. It implicitly distinguishes itself from the prepare tools and from canvas_cancel_action / canvas_action_status, though it never names 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?

Explicitly states when to call (only after the user has authorized exact files, target course/assignment, and upload vs. final submission), when not to call (declined authorization, general setup requests, schedules, or content browsing), and what to do when ambiguous (ask first, otherwise cancel the prepared action). It even resolves a common failure mode by telling the agent not to re-ask when authorization is already present in the conversation.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the "this is read-only" sentence is largely redundant. The added value is the explicit note that it does not mark viewed/completed requirements — a real side-effect guarantee an agent would otherwise worry about, since some Canvas reads do advance progress. No disclosure of caching or the effect of the refresh 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?

The core capability is front-loaded in the first sentence and the remaining lines are short and functional. The enumerated asset types duplicate the schema enum, which is the only clearly non-earning content, but overall the text is tight.

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?

An output schema exists, so return-shape explanation is not required, and the read-only behavior is covered. Still missing for a tool of this specificity: the semantics of asset_id per asset type, refresh behavior, and the failure mode when an asset is not in any module — gaps the schema cannot fill at 0% coverage.

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

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

Schema description coverage is 0% for four parameters, so the description must compensate and it largely does not. It restates the asset_type enum (already in the schema) but says nothing about course_id, asset_id, or refresh — notably whether refresh forces a re-fetch past a cache, which is the only non-obvious 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 opening sentence names a specific verb (get) and a specific resource (Canvas module-item relationships) and scopes the result to previous/current/next, which is meaningfully different from a flat list tool like list_modules. The asset-type list further bounds what inputs are acceptable. It stops short of explicitly naming a sibling it replaces, but an agent can still distinguish it from list_modules.

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

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

"Use the returned sequence instead of assuming ID order" is a genuine usage cue about when this tool beats manual ordering inference. However, there is no when-not guidance, no mention of prerequisites (e.g., the asset must belong to a module), and no statement of what happens for un-moduled items, leaving the agent to infer the boundaries.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the description is not obligated to cover safety. It still adds real behavioral detail: module IDs vs page slugs, that module opens return paginated items even when Canvas omitted inline items, that module items resolve to their target with prerequisites, lock/completion state, external links, and sequence navigation preserved, and the important side-effect guarantee that reading never marks a module complete or starts a quiz. The limit/offset/refresh behavior (caching) is left unexplained, keeping it below 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?

The description is short and front-loads the resource list before the caveats, with each sentence carrying a distinct fact (identity source, pagination fallback, target resolution, side-effect guarantee). Only the vague 'use identities returned by navigation' phrase is filler that could be tightened.

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?

Because an output schema exists, the description need not explain return shapes, and the behavioral notes cover the trickiest resolution cases. Still, for a 7-parameter tool with zero schema coverage, the absence of any explanation for limit, offset, refresh, and module_id leaves an agent guessing on pagination and cache 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 0%, so the description must carry parameter meaning, and it only partially does. It clarifies that item_id may be a slug for pages and that module_id relates to module items implicitly, but limit, offset, and refresh — including the non-obvious caching implication of refresh — are never mentioned, and module_id is never explained.

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 opening sentence gives a concrete verb (open) and enumerates the exact resource types it handles (module, module item, page, assignment, file, quiz, discussion), which lets an agent match it to a request quickly. It stops short of differentiating itself from overlapping siblings like get_assignment, get_file, or canvas_browse_course, so the boundary 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?

'Use identities returned by navigation' gives a provenance hint for where the IDs come from, which is genuine usage context. However, there is no explicit when-to-use-this-vs-sibling guidance, no mention of when to prefer get_assignment or list_modules, and no stated prerequisites or error conditions.

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

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

Annotations already declare readOnly/openWorld/non-destructive, but the description adds real behavior: unsupported links are never fetched and the Canvas token is never forwarded, plus an untrusted-data warning against prompt injection from Canvas content. That is meaningful context beyond the annotations. It leaves the effect of the `refresh` parameter and any caching behavior undisclosed.

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 core action, then constraints, then the safety caveat; every sentence carries information. Slightly longer than necessary and the untrusted-data note, while useful, is a policy statement that could be condensed.

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?

An output schema exists, so return values need not be described, and the annotation set covers the safety profile. The remaining gap is the undocumented `refresh` flag, which is material for a tool that may otherwise re-fetch stale content.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It partially covers `url` by enumerating acceptable link types, but gives no format expectations, and the `refresh` boolean is never mentioned or explained anywhere. An agent cannot infer what refreshing does or when to set 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 ("Follow a supported Canvas link") and scopes it with the typed navigation allowlist, enumerating the accepted link kinds (course, section, page, assignment, file, quiz, discussion, module). An agent can tell this is a URL-resolution tool rather than a lister or fetcher. It does not explicitly contrast with the sibling canvas_open_item, which appears to overlap in intent.

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 positive condition (same-instance supported links) and a negative one (external/LTI/unsupported links return an explicit state without fetching). It stops short of naming an alternative tool for the unsupported case or stating when canvas_open_item should be preferred instead.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known; the description adds genuinely new behavior by enumerating the checks performed (allowed types/extensions, lock, attempts, current submission) and by stating explicitly that nothing is submitted. It does not describe what the check results look like or how failures are surfaced, but the output schema covers returns.

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, each earning its place: purpose, negative scope, checks, then the authorization precondition. The most important constraint ('Does not submit') is front-loaded right after the purpose.

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 annotations covering safety and an output schema covering returns, the remaining gap is provenance of upload_action_ids — which sibling (likely canvas_prepare_upload) produces the receipts. That missing link is the one thing an agent would still have to guess, so this is nearly but not fully complete.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It only partially does: 'verified upload receipts' implies upload_action_ids come from a prior upload step, and 'for that assignment' ties assignment_id, but course_id is never explained and there is no hint about the expected id format or ordering constraints.

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 ('Review a file submission') and immediately bounds the scope with 'Does not submit', which separates it from canvas_execute_action. An agent can tell what this tool does 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?

Clearly frames this as the pre-flight step before a 'separate execute step' and adds a real workflow precondition: 'Obtain user authorization in conversation before the separate execute step.' It stops short of naming canvas_execute_action explicitly or saying what to do when the checks fail, so it is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this consistently ('writes nothing to Canvas'), then adds non-obvious behavior the annotations cannot convey: payload size ceilings per transport, that a server path is never accepted over HTTP, and that assignment attachments do not constitute a submission. Permission/authentication requirements are the main thing not 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?

Very dense with no filler: the safety claim is front-loaded, then transport constraints, then the domain caveat, then the execution rule. Each sentence carries distinct information; the line-broken phrasing makes it slightly harder to scan than a cleaner sentence structure would.

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?

An output schema exists, so the description correctly avoids explaining return values and instead focuses on the prerequisite behavior (staging vs executing). It is nearly complete for a staging tool, with only the parameter-validity rules (e.g., when course_id/assignment_id are needed for destination='assignment') left to inference.

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

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

Schema description coverage is 0% across 6 parameters, so the description carries the burden. It does add real meaning for the two ambiguous transport parameters (source_path local-only at 25 MiB, content_base64 HTTP-only at 8 MiB) and hints at destination via the assignment-attachment caveat, but filename, course_id, and assignment_id are never explained, including which are required for the 'assignment' destination.

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?

Uses a specific verb+resource ('Stage immutable upload bytes and return the exact review') plus a scope boundary ('writes nothing to Canvas'), which distinguishes it from the actual-execution sibling canvas_execute_action. The phrase copy is slightly opaque about what the 'review' actually contains, keeping it short of a perfect 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?

Gives a concrete conditional rule for the follow-up step ('Execute the returned action only when the user wants this exact upload') and states which parameter to use per transport (local stdio vs base64 over HTTP). It does not explicitly name canvas_execute_action as the next tool, so the routing to the sibling is left implicit.

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?

Goes well beyond the readOnly/openWorld/destructive annotations: 50 MiB cap, SHA-256 hashing, bytes never rewritten, pagination state contract, source-change invalidation, tesseract/pdftoppm dependency, 5-page OCR limit, and the explicit safety claim that no macros, external resources, or embedded instructions are executed. This is exactly the kind of behavior an agent needs before calling a document reader.

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 pagination/OCR/safety details, mostly in compact imperative lines. A few fragments are terse to the point of being cryptic ('Both local and cloud MCP support this.', 'Inspect state, warnings, and coverage: old .doc/.ppt need conversion') and cost a little clarity.

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

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

For a 7-parameter, paginated, format-spanning reader, it covers safety profile, continuation protocol, OCR preconditions, and known limitations; the presence of an output schema removes the need to explain return values. The only meaningful omission is the meaning or effect of max_chars and max_units on result size.

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

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

Schema description coverage is 0%, so the description must carry the load, and it explains ocr (semantics, prerequisite binaries, page cap), offset/char_offset (via next_offset and next_char_offset resume protocol), and expected_sha256 (staleness check). max_chars and max_units are never mentioned, and file_id is only implicitly understood, so one gap remains.

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 and resource ('Read current Canvas ... document content') plus the supported format list, so the agent knows exactly what the tool does. However, it never distinguishes itself from close siblings such as fetch_file_content, get_file, or download_file, leaving the agent to infer which one to pick.

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 concrete operating guidance: follow next_read, resume with next_offset AND next_char_offset plus expected_sha256 and the same ocr setting, and restart if the source changed. It also states when to set ocr=True (local, English, image-only PDF pages or image files) with the 5-page cap. It stops short of saying when to prefer this over fetch_file_content or download_file.

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?

Despite annotations already declaring the safety profile, the description adds substantial context the agent could not infer: the operation is local-only and cannot be invoked from a remote cloud server, dry-run is the default, existing drafts are never overwritten, no schedule is created, and partial coverage/failed sources are possible outcomes. It even warns that 'failed sources do not mean no work,' which is exactly the kind of non-obvious behavioral caveat that prevents misreads of results.

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

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

The content is dense and mostly earns its place, but the structure is poor: it opens with a semicolon fragment, then stacks constraints and caveats in hard-wrapped lines with no hierarchy. 'Remote cloud servers cannot write to your Mac' restates 'LOCAL STDIO ONLY' and could be merged, and the actual operation is never stated up front.

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?

An output schema exists, so return values needn't be described, and the safety/scope caveats are well covered. However, for an 8-parameter tool with zero schema descriptions, the absence of any explanation for course selection and the four limit parameters is a real completeness gap that the description should have closed.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it only covers two of eight parameters: output_root ('must be an absolute private coursework directory outside connector source') and apply (dry-run vs write). The six remaining parameters — course_ids, all_active, max_files, max_file_mb, max_total_mb, max_operations — get no explanation at all, leaving the agent to guess at scoping and throttling behavior from bare titles.

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 opening sentence gives a specific verb+resource ('Plan or update separate per-class folders') and immediately distinguishes the tool from write-capable siblings with 'never write to Canvas.' It is not maximally crisp because the purpose is buried in a fragment followed by a wall of constraints, and 'sync' never appears explicitly, but an agent can identify what the tool does.

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

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

The apply semantics are spelled out clearly: 'Default apply=false discovers changes without local writes. apply=true preserves original bytes, versioned hashes, extraction previews, manifests...' — that is genuine when-to-use guidance for the primary mode switch. It falls short of a 5 because it never routes the agent to or away from any named sibling tool, and the 'LOCAL STDIO ONLY' precondition is stated but not connected to a 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=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context about what is aggregated and that it includes a template summary suitable for direct output. It does not disclose that a full fan-out digest is likely expensive/slow or that a course_id must resolve — meaningful gaps for an open-world aggregator.

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 blocks: a front-loaded one-line framing followed by a scannable enumeration of contents. Every sentence carries information and 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?

An output schema exists, so return-value detail need not be re-explained, and the safety annotations cover the mutation question. The remaining gap is the time-window parameters, which are undocumented anywhere and are central to controlling this digest's scope.

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

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

Schema description coverage is 0% and there are three parameters, so the description must carry the burden — but it never mentions course_id, lookback_days, or lookahead_days by name. 'Upcoming' and 'recent' faintly gesture at the lookahead/lookback windows, but defaults (14/7 days) and units are left entirely to the schema titles, which convey nothing.

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 ('rich per-course digest — what is going on in this class') and enumerates the exact payload (grade, upcoming work, missing/overdue, announcements, discussions, grader feedback, module progression). The 'per-course' scoping distinguishes it from cross-course siblings like whats_new or canvas_dashboard, but it never explicitly names the nearest siblings such as missing_work_audit or canvas_course_home, so differentiation is only partial.

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 phrase 'what is going on in this class' and by the enumerated contents, which suggest a broad orientation request rather than a targeted lookup. However, there is no explicit statement of when to prefer this over canvas_course_home, missing_work_audit, or whats_new, and no stated exclusions or prerequisites.

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 a non-destructive write, but the description adds real context: it affects only the private planner, is invisible to teachers and classmates, creates no attempt count or public post, and is fully reversible via delete_planner_note. That is meaningful disclosure of side effects and blast radius beyond the structured hints, though permissions or verification behavior are not 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 short sentences, front-loaded with the core action and then the safety scoping. No filler, though the quoted "safe write" framing is slightly informal for a tool definition.

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?

An output schema exists, so return-value explanation is unnecessary, and the description fully covers visibility and reversibility for a simple write. The gap is parameter documentation, which leaves the agent to infer the role of course_id and todo_date from the schema alone.

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

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

Schema description coverage is 0% across four parameters, and the description never mentions title, details, course_id, or todo_date. The required title and the date-scoping field todo_date are especially opaque, and the description does not hint at what course_id associates the note with.

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 precise verb+resource: "Create a personal reminder in the user's planner." That clearly distinguishes it from read-oriented siblings such as list_planner_notes or planner_items, though it never explicitly names the create-vs-list 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?

Usage is implied by "personal reminder" and the point about it not being visible to teachers or classmates, which tells the agent this is for private self-notes. The only explicit alternative routing is to delete_planner_note for reversal; no guidance is given on when to prefer this over planner_items or other note-creating paths.

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 destructiveHint=true and readOnlyHint=false, and the description adds genuinely new context by explaining that Canvas soft-deletes, so the note is recoverable. That value is undercut by the vague hedging 'Safe, reversible-ish' and by the absence of any detail on whether the note disappears from list_planner_notes or how long the soft-delete window lasts.

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 action and scope front-loaded and no wasted framing. The colloquial 'reversible-ish' costs a little precision but not length.

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?

An output schema exists, so return values need not be described, and the soft-delete note covers the main behavioral question for a destructive tool. Still missing is how to obtain a valid note_id and what error behavior to expect, which matters even for a one-parameter deletion.

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

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

Schema description coverage is 0% for the single required note_id parameter. The description only restates 'by ID', adding no information about where the ID comes from (planner_items or list_planner_notes), its type, or what happens when an unknown ID is supplied, so it fails to compensate for the schema gap.

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?

Uses a specific verb plus resource ('Delete a personal planner note') and scopes it to 'personal', which cleanly separates it from create_planner_note and list_planner_notes. It stops short of explicitly naming those siblings, so an agent must infer the routing from the verb 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?

There is no when-to-use or when-not-to-use guidance and no mention of alternatives such as create_planner_note or mark_planner_item_complete. The only usage signal is implied by the verb 'Delete'.

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 only declare the safety profile (not read-only, not destructive, open-world), so the description carries the meaningful semantics: the item is hidden from 'what's on my plate' rather than completed, and the effect is private to the user. It omits reversibility — whether a dismissed item can be restored.

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?

Short, front-loaded, and every sentence contributes: definition, then effect, then use case. Slight redundancy in restating 'planner view' and 'what's on my plate' but nothing wasteful.

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

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

The presence of an output schema means return values needn't be explained, and the safety profile is covered by annotations. However, for a state-changing tool with two undocumented required parameters and no note on reversibility, the definition has a clear 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 0% for both required parameters. plannable_type is a bare string with no enum, and the description never states what type values are accepted (assignment, quiz, etc.) or how plannable_id relates to plannable_type, leaving the agent to guess the accepted vocabulary.

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 ('Dismiss a planner item from the user's planner view') and immediately scopes it as private. The clause 'without marking it complete' explicitly separates it from the sibling mark_planner_item_complete.

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 use case ('items the user has decided they don't need to do, e.g. optional revisions') and implicitly routes away from mark_planner_item_complete. It stops short of an explicit when-not-to-use or a stated way to undo a dismissal.

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

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

The annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, and the description is consistent with them by framing the tool as a local write. It adds useful context that the write target is the user's own machine rather than Canvas, but it omits important behavior: whether an existing file at destination_path is overwritten, whether parent directories are created, and whether large files are streamed or size-limited.

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 purpose statement is front-loaded in a single sentence, and the Args/Returns blocks are compact and each line earns its place. The docstring-style formatting is slightly mechanical but does not add waste. Nothing is buried or repeated.

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 two-parameter write tool this covers the essentials, and an output schema exists so the description's Returns line is supplementary rather than load-bearing. However, the absence of any overwrite/error behavior and of routing guidance against the many sibling file tools leaves real gaps for a mutating, open-world operation.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does: file_id is identified as a Canvas file ID and destination_path as an absolute local path. The absolute-path requirement is genuinely useful meaning not present in the schema. It does not clarify whether the path must already exist or whether it may point to a directory, which keeps 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 first sentence states a specific verb and resource ('Download a file') plus the target location ('to a local path on the user's machine'), which is enough for an agent to distinguish it from read-only siblings such as get_file or fetch_file_content. It stops short of naming those siblings explicitly, so the differentiation is implied 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?

There is no guidance on when to use this tool versus the several file-related siblings (get_file, fetch_file_content, canvas_read_file, canvas_browse_files). The description never says, for example, that this is the tool for persisting bytes to disk while fetch_file_content returns content inline. An agent must infer the choice from the name alone.

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 (readOnlyHint true, destructiveHint false, openWorldHint true), so the description's added value is the inline-vs-disk behavior and the small-file caveat. It also documents the response payload shape, though it gives no concrete size threshold for what counts as "small" or what happens on a very large file.

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 and the key usage decision in two short sentences, then structured Args and Returns blocks that are easy to scan. The Returns block is somewhat verbose given an output schema exists, but it remains informative rather than redundant 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 two-parameter read tool with annotations and an output schema, the description covers purpose, parameter meaning, and return shape adequately. The only material gap is the undefined notion of "small files" and any size or rate limits an agent should respect before calling.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does: file_id is identified as a Canvas file ID, and as_text is explained as UTF-8 decoding versus base64-encoded bytes. This adds meaning well beyond the bare boolean/integer schema types.

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 a file's bytes inline") and immediately contrasts with the disk-writing alternative ("rather than save to disk"), which distinguishes it from siblings like download_file and get_file. An agent can identify the tool's role 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?

It gives a clear usage condition: small files where the agent needs to read content directly rather than persist it. The alternative behavior (save to disk) is named conceptually, though the specific sibling tool that does that is not named, and no explicit when-not-to-use boundary is drawn.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the ordering is depth-first and every entry carries a `depth` field so indentation can be reconstructed without re-walking the tree. It does not mention pagination or size limits for large threads, which is the main 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?

Three short sentences, front-loaded with the core behavior, then the output detail, then the motivating use case. No filler, though the second sentence is somewhat explanatory rather than essential.

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?

An output schema exists, so return values need not be explained, and the description explains the ordering semantics well. The notable hole is the two undocumented required parameters, which for a tool that cannot be called without them is a meaningful omission.

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

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

Schema description coverage is 0% — course_id and topic_id have bare integer types with no titles beyond the property names. The description never mentions either parameter, so it does nothing to compensate for the coverage gap, and an agent gets no guidance on what a topic_id means relative to a course.

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 plus the transformation applied: returns a discussion as a flat depth-first list instead of a nested tree. That distinguishes it in output shape from the sibling get_discussion_thread, though the sibling is never named 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 implies usage (reading a discussion end-to-end rather than expanding 'show replies' node by node), which is a reasonable when-to-use signal. However, it never states when to prefer get_discussion_thread or list_discussions instead, leaving the routing decision 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious behavior: the response includes the user's submission and the description field is HTML containing embedded file links, rubric criteria, and linked resources — prompting follow-up calls like get_file or fetch_file_content.

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, front-loaded sentences with no filler; the key mutation-relevant detail (HTML description containing links) is placed immediately after the purpose statement.

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?

An output schema exists, so return shape needs no explanation, and the description correctly flags the submission inclusion and the HTML payload. The gap is the absence of any parameter context for a 0%-documented schema, which for a simple two-integer read tool is a minor omission rather than a blocker.

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

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

Schema description coverage is 0%, so the description carries the burden, and it says nothing about course_id or assignment_id. The parameter names are close to self-explanatory, but there is no statement of relationship (e.g., that assignment_id must belong to course_id) or validation behavior.

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: 'Get full detail on a single assignment including the user's submission,' which is clearly narrower than the sibling list_assignments. It does not explicitly distinguish itself from get_my_submission, which overlaps on the 'user's submission' aspect, so an agent must infer the split.

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: 'single assignment' suggests fetching one item after list_assignments surfaces an id, but no when-not or alternative is named. The second sentence gives guidance on how to mine the returned content, not on when to choose this tool over get_my_submission.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value by enumerating what the response includes (syllabus body, teachers, term, grading periods, progress), which helps the agent anticipate payload weight. It says nothing about enrollment or permission prerequisites, nor whether a missing or inaccessible course errors.

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 purpose front-loaded and the returned contents following immediately. Nothing is redundant or 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?

An output schema exists, so return values need not be fully explained, and the description's field list is a useful complement. However, with an undocumented required parameter and a crowd of similar course-level siblings, the definition leaves out the ID source and the routing rationale an agent needs to call it confidently.

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

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

Schema description coverage is 0% for the single required parameter course_id, so the description must carry the burden. It only says 'by ID' and never states what kind of ID this is or where to obtain it, for example from list_all_courses. This is a meaningful gap for the one parameter the agent must supply.

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: 'Get detailed info for a single course by ID.' The singular 'single course by ID' implicitly distinguishes it from the many list_* siblings such as list_all_courses and list_active_courses, but no sibling is named 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?

There is no guidance on when to choose this tool over near neighbors like canvas_course_home, canvas_browse_course, or catch_me_up_on_course, all of which also surface course-level detail. The use case is only implied by the phrase 'single course by 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower, and the description adds genuinely new behavior: the tree is cached server-side and includes participants, entry ratings and unread flags. It stops short of saying how stale the cache can be or whether a refresh is possible.

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 action and its output shape, then the follow-up tool. Slight overlap between 'full threaded view' and 'the nested view' but 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?

For a simple two-parameter read with an output schema present, the description covers purpose, payload contents and the natural next step. The one real gap is the unmentioned required parameters, which matters because the schema documents nothing about 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 0% and both parameters (course_id, topic_id) are bare integers with no titles beyond their names. The description never mentions either parameter, so an agent gets no confirmation that topic_id is scoped to course_id or what a valid topic id looks like; it relies entirely on the self-explanatory naming.

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 ('Get a discussion topic's full threaded view') and immediately scopes the result as the cached server-side tree with participants, ratings, unread entries and nesting. That is clearly distinguishable from list_discussions (which lists topics) and from flatten_discussion_thread (which post-processes this output).

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 chaining guidance: use flatten_discussion_thread on the returned view to get a flat depth-annotated list, which tells the agent when this tool is the wrong choice. It does not say when to prefer this over list_discussions or note any prerequisites such as enrollment/access to the course.

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, non-destructive), but the description adds genuine behavioral context beyond them: the signed `url` downloads with the bearer token, there is a `preview_url` where applicable, and access is described as 'reliable across permission levels'. That auth/entitlement detail is real value; it does not, however, discuss rate limits or what happens for inaccessible IDs.

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, then the return shape, then the alternative routing. Nothing is redundant given the output schema exists, and 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 single-parameter read tool with an output schema and full annotation coverage, this is close to sufficient: purpose, return shape, auth behavior, and the key alternative are all stated. The one gap is that it never says where a file_id comes from or what happens with an invalid/unauthorized ID.

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

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

Schema description coverage is 0% and the single `file_id` parameter has no description in the schema, so the description carries the burden. 'By ID' only confirms the identifier role and adds no format, source, or validity guidance (e.g., where to obtain the ID).

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 first sentence names a specific verb and resource ('Get metadata for a single file by ID') and the closing sentence distinguishes it from the sibling that returns bytes. An agent can tell it apart from download_file, fetch_file_content, and canvas_read_file 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?

It gives explicit routing guidance ('Use download_file to get actual bytes'), which is exactly the confusion an agent would have with three file-related siblings. It stops short of addressing the other file siblings (fetch_file_content, canvas_read_file) or stating any exclusion beyond that one case.

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

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

The description earns credit beyond the annotations by disclosing the side effect that governs the read-state behavior: auto_mark_as_read defaults to False so 'programmatic browsing preserves unread state'. That non-obvious consequence explains why readOnlyHint is false without destructiveHint, which the schema alone would not convey. It does not cover return shape, but an output schema exists so that burden is carried elsewhere.

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 core purpose is front-loaded in one sentence, followed by a compact Args block. The wrapped parenthetical is slightly awkward for a passage this short, but no sentence 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?

For a two-parameter read tool with an output schema, the essentials are present, including the read-state side effect. What is missing is the provenance of conversation_id and any hint about large threads or paging, which are the likely friction points for an agent calling this cold.

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?

With 0% schema description coverage, the description must compensate, and it partially does: it identifies conversation_id as a 'Canvas conversation ID' and explains the rationale behind the auto_mark_as_read default. The conversation_id note adds little beyond the integer type and title, so the compensation is incomplete rather than thorough.

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

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

The description opens with a specific verb and resource: 'Get full messages in a single inbox thread.' This distinguishes it clearly from list_inbox (which lists threads) and from get_discussion_thread (a different resource family). It stops short of naming those siblings explicitly, so it is clear but not maximally 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?

There is no statement of when to choose this over list_inbox to enumerate threads first, nor any note that conversation_id comes from that listing. Usage is only implied by the words 'single inbox thread', leaving the agent to infer the sequencing on its own.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral content beyond that: submission_comments, submission_history and rubric_assessment are returned by default, and grading feedback may live in comments rather than score fields — a non-obvious trait an agent could not infer from structured data.

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 is front-loaded in the first sentence, followed by the high-value default-fields warning. The teacher-specific aside ('e.g. Rettberg in DLS') is slightly anecdotal but motivates the critical instruction, so it mostly 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?

An output schema exists, so return values needn't be described, and the tool is simple with only two required params. The remaining gap is that with 0% schema coverage the description does nothing to explain the required identifiers, leaving an agent unsure how to obtain valid course_id/assignment_id values.

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

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

Schema description coverage is 0%, so the description carries the full burden for course_id and assignment_id, yet it never mentions either parameter, its type, or where the ids come from (e.g., list_all_courses / list_assignments). The two required ids are left entirely to guesswork beyond their names.

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 and resource — 'Get the user's submission for an assignment' — and scopes it with 'full detail.' It does not distinguish itself from siblings like get_assignment or canvas_prepare_submission, so an agent must infer that this one returns the caller's own submission rather than assignment metadata.

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 a clear directive on how to use the result ('an agent surfacing a submission must include comments as first-class feedback'), which is real usage guidance. However, there is no explicit when-not clause and no named alternative (e.g., use get_assignment for the spec, canvas_prepare_submission to submit), so selection between siblings remains 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by saying results include grade and enrollment details, but it never defines what 'active' actually means (unpublished vs. concluded courses, current term only?) nor mentions pagination or result limits, which matters for a user with many enrollments.

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 core action, then guidance, which is the right order. The middle sentence enumerating returned fields (id, name, course_code, term, grade, enrollment) is partly wasted since an output schema already exists, but it is short and oriented toward the right decision.

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

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

For a zero-parameter, read-only discovery tool with an output schema and full annotation coverage, the description supplies nearly everything needed: purpose, return shape, and call-ordering advice. The one real gap is the undefined semantics of 'active,' which determines whether the agent should also call list_archived_courses or list_all_courses.

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; the baseline of 4 applies. Nothing in the description contradicts or confuses the empty argument 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 and scoped resource: 'List the user's currently active Canvas courses.' The word 'active' implicitly separates it from list_all_courses and list_archived_courses in the sibling set, but those siblings are never named, so the 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?

'Use this to discover what classes the user is currently enrolled in before querying anything else course-specific' gives clear positive routing: call this first as the entry point for course-scoped work. It stops short of an explicit exclusion (e.g., 'use list_archived_courses for past terms'), leaving the sibling choice 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?

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: results include archived courses, meaning the output can contain stale or inactive enrollments, which matters for downstream reasoning. It says nothing about result volume or ordering, though the output schema covers return shape.

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 scope statement comes first, followed immediately by the decision rule for using it. Every clause earns its place and nothing is repeated from the schema or annotations.

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

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

For a zero-parameter list tool with an output schema and full annotation coverage, the description supplies what structured fields cannot: the active-plus-archived scope and the selection rule. The remaining gap is routing to list_active_courses and list_archived_courses, which an agent must infer from their names alone.

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 beyond what the empty schema already states; baseline for a no-parameter tool is 4. The description correctly implies no filtering is possible, which is the one semantic point worth conveying.

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

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

The description names a specific verb ('List') and resource ('the full enrollment history'), and the phrase 'active plus archived courses' makes the scope precise. It does not name the obvious siblings list_active_courses and list_archived_courses, so differentiation is left to inference 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?

It gives a concrete when-to-use condition: 'when you need to find a course across semesters without knowing whether it is currently active.' That effectively implies the narrower siblings are for the cases where you do know, but the alternatives are never named or explicitly excluded.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered without the description. The description does add real behavioral value by disclosing the effective default time windows (14 days back, 28 days forward), which are not visible in the schema where both dates default to null. It says nothing about pagination, result ordering, or how many courses can be batched per call.

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 is front-loaded in the first sentence, followed by a compact Args block with one line per parameter and no filler. The docstring-style Args formatting is slightly redundant with the schema keys but is dense rather than wasteful.

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?

An output schema exists, so return-value explanation is not required, and the date defaults make the temporal window usable. For a multi-course listing call, however, it omits what an agent still needs: whether the date filter is on posting date, any cap on course_ids length or pagination behavior, and timezone handling for the YYYY-MM-DD bounds.

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 0% and the schema types are untyped strings with null defaults, so the description carries the full burden — and it does: it states the date format (YYYY-MM-DD) and, critically, the actual effective defaults (14 days ago / 28 days forward) that contradict the null defaults in the schema. It does not clarify whether start_date applies to posting date, timezone, or what happens if only one bound is supplied.

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?

"List announcements across one or more courses" gives a specific verb and resource plus the batching scope (multiple courses at once), which is exactly the detail an agent needs. It stops short of distinguishing itself from nearby read tools such as list_discussions or whats_new, so it is clear but not sibling-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?

There is no guidance on when to choose this tool over the many other read/feed tools in the namespace (list_discussions, activity_stream, whats_new, list_inbox). The usage is only implied by the tool name and the phrase "across one or more courses"; no exclusions, prerequisites, or alternative routing 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real behavioral context the annotations cannot: archived course IDs are interchangeable with active ones for assignments, modules and files, which changes how the agent can reuse the returned IDs. It says nothing about pagination or result volume.

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 purpose is front-loaded in the first sentence, and the parenthetical German I/German II example earns its space by making the tutoring scenario concrete. The third sentence about downstream tool compatibility is slightly tangential to 'list' but pays off in usefulness, so the small length cost is justified.

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

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

The tool is simple (no params, output schema present, annotations present), and the description covers scope, motivation and downstream compatibility. It omits whether archived results can be empty or how they're ordered, but with an output schema in place those gaps are minor.

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?

With zero parameters and 100% schema coverage there is no parameter meaning to add, so the baseline applies. The description doesn't invent parameters or ambiguities, and it correctly frames the tool's only real input as implicit: the authenticated user.

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

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

The description opens with a specific verb and resource ("List ... archived courses") and pins the scope to "past-semester (archived)", which contrasts with the active-courses sibling. It stops short of naming list_active_courses or list_all_courses, so an agent must infer the split from the word 'archived' rather than being routed 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 supplies a concrete when-to-use scenario (tutoring across semesters, e.g. last semester's German I for German II), which is genuine selection guidance. It gives no explicit when-not-to-use rule or named alternative, so the agent still has to decide on its own whether list_active_courses or list_all_courses would be a better fit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds one piece of behavior beyond that — that submission state flags (submitted/graded/late/missing) are returned per item — but says nothing about pagination, result limits, or whether the list is scoped to the caller's enrollment.

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 is front-loaded in the first sentence, followed by a compact args block and a one-line return note. No filler, though the docstring formatting ('Args:') is a little mechanical.

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?

An output schema exists, so return shape needn't be re-explained, and the annotations cover the safety profile. With all three parameters documented and the enum values supplied where the schema omits them, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 0%, so the description carries the burden and does so well: it enumerates the seven valid bucket values, which the schema itself leaves as an unconstrained string, and defines search_term as a partial name match. Only course_id is given a thin gloss ('Canvas course ID'). This is a real value-add over the raw schema.

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

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

The opening line states a specific verb and resource: 'List assignments in a course.' That is enough to separate it from get_assignment (single item) and from audit-style siblings like missing_work_audit, though those alternatives are never named. It is clear but does not explicitly differentiate from siblings.

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

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

No explicit when-to-use or when-not-to-use guidance is given, and no sibling is named as an alternative. The bucket filter list implicitly signals intended scenarios (e.g. 'ungraded'/'missing' work review), but the agent must infer that a per-assignment lookup belongs to get_assignment instead.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds a useful behavioral detail — that each topic carries unread_count indicating new activity — which goes beyond annotations. It does not mention pagination or result limits, so the addition is modest.

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

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

Three short sentences, front-loaded with purpose and then the filter guidance; nothing is redundant. The stray line breaks are cosmetic and do not harm readability.

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

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

The tool is simple (two params, one required) and an output schema exists, so return values need not be spelled out — yet the description still explains the key field unread_count. What remains missing is any cross-reference to the announcement and thread siblings, which matters given the overlap.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does explain only_announcements (filter to announcements, with the literal True), but course_id is never described beyond its name. That covers one of two parameters, adequate but incomplete for a zero-coverage 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 with scope: 'List discussion topics in a course.' An agent can immediately tell this is a read/list operation over discussion topics. It stops short of naming the close sibling list_announcements, which overlaps with the only_announcements filter described 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?

Gives one concrete usage cue: 'Pass only_announcements=True to filter to announcements.' However, it never explains when to use this versus list_announcements (which appears to do the same thing) or get_discussion_thread for reading a single thread. Usage is implied rather than routed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: no pagination behavior, no ordering, no indication of what a scope of None actually returns in volume, and no note about network/rate-limit implications of an open-world read.

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 one-line summary is front-loaded and followed by a compact Args block, with no filler. The docstring formatting is slightly raw but costs almost nothing in length.

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?

An output schema exists, so return values need not be explained, and the single optional parameter is documented. However, for an open-world read tool with a sibling that fetches a single thread, the definition omits result-set size, ordering, and selection guidance, leaving modest gaps.

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

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

Schema description coverage is 0% and the schema itself declares 'scope' only as a bare string with no enum, so the description does real work by enumerating the accepted values (unread, starred, archived, sent, None) and clarifying that None means all. It stops short of stating the default's effect explicitly or whether other values are errors.

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 ('List Canvas inbox threads'), which is immediately distinguishable from the sibling 'get_inbox_thread'. It does not explicitly contrast with that sibling, but the plural/list framing makes the distinction clear.

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

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

Usage is only implied: an agent can infer this is the tool for enumerating inbox threads, and the scope argument hints at filtering. There is no explicit guidance on when to prefer this over 'get_inbox_thread', nor any stated preconditions such as authentication or empty-inbox behavior.

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

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

The annotations already cover safety (readOnlyHint true, destructiveHint false) and open-world access, so the description's real contribution is the payload shape — items with due dates and lock status — plus the non-obvious failure mode where file enumeration 403s for students but module items remain reachable. That second point is exactly the kind of hidden behavior an agent could not infer from annotations. It stops short of pagination or size expectations, keeping it at 4 rather than 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 short sentences in a deliberate order: what it returns, why to trust it, then what to use instead and why. The opening sentence carries the core purpose and the qualification follows, so nothing important is buried, and no wording is redundant.

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?

An output schema exists, so return values need no prose, and the description fills the remaining gaps that matter for a single-parameter read-only listing tool: payload contents, ranking among siblings, and a known authorization quirk. The only omission is any hint about how to obtain the course_id, a minor gap given the surrounding course-scoped siblings.

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?

There is a single required parameter, course_id, and schema description coverage is 0%, so the schema itself says nothing about its meaning or accepted values. The description only implies it via "in a course," adding no format, range, or source guidance (e.g., where to obtain a course id). Baseline 3 is appropriate for one obvious identifier with no compensating detail.

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

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

The first sentence gives a specific verb and resource ("List modules in a course") and immediately states the scope twist that items and content details are inlined. That phrasing separates it from list_course_files and canvas_module_sequence without the agent needing to open 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?

It explicitly ranks itself ("the most reliable 'what is in this course' query") and names a concrete alternative to avoid ("Prefer this over list_course_files for file discovery") with the reason why. Both the when-to-use and the when-to-use-something-else conditions are stated outright.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered by structured data. The description adds that results are limited to the user's own notes, which is genuine scope context, but says nothing about ordering, volume, or pagination 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?

A single front-loaded sentence with no filler; the scope qualifier arrives immediately. The parenthetical adds clarification rather than restating the name verbatim, though it is close to redundant with "personal."

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 parameters, an output schema, and annotations covering the safety profile, the definition supplies nearly everything needed to invoke it. The remaining gap is how this differs from planner_items, which matters given how many planner siblings exist.

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 no parameter semantics to explain and the baseline is 4. Nothing in the description misleads about inputs.

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 pairs the verb "List" with a specific resource, "the user's personal planner notes," and the parenthetical "(reminders they created)" narrows the scope. It does not name the closely related sibling planner_items, so an agent must infer the distinction rather than being told it.

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 phrase "personal planner notes" suggests this returns user-authored notes rather than the full planner feed, but no explicit when-to-use condition or alternative (e.g. planner_items) is named. There are also no stated exclusions or prerequisites.

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 this as a non-read-only, non-destructive mutation, so the description's job is to explain the blast radius — and it does: the change is confined to 'the user's private planner view' and explicitly does not submit work. It does not say whether the override is reversible or idempotent, which would round out the mutation profile.

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

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

Front-loaded with the scope-limiting sentence, then the usage guidance, then args — a sensible order with no filler prose. The Args block is somewhat redundant in formatting but each line contributes parameter meaning not found in the bare 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?

With an output schema present, return values need no explanation, and annotations cover the safety profile. That leaves scope, side effects, and both parameters — all addressed — so little an agent needs in order to call this correctly is absent.

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 0%, so the description carries the full burden and largely meets it: plannable_type is illustrated with concrete values ('assignment', 'quiz', 'planner_note') and plannable_id is identified as the target item's Canvas ID. It still doesn't establish whether the accepted type strings are a closed set or how they map to the tool's own naming.

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 first sentence names a specific verb and resource ('mark a planner item as complete') and immediately qualifies the mechanism ('via a planner override'). It also draws a crucial boundary — 'This does NOT submit the work' — which separates it from submission tools. It does not explicitly name the nearest sibling (dismiss_planner_item), so the distinction from dismiss-versus-complete is left implicit.

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

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

"Use to silence 'you still have to do this' reminders when the work is actually done" gives a concrete triggering condition plus a real example (paper assignments submitted offline). What's missing is an explicit when-not or a named alternative, e.g. that dismissing is for work you won't do while completing is for work already done.

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 (readOnlyHint true, destructiveHint false), yet the description adds real behavior: it scans every active (not archived) course, filters out excused assignments, and includes a template summary in the payload. That goes beyond the annotations. It doesn't mention cost or latency of fanning out across all courses, though openWorldHint is set.

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

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

The description is short and front-loads the what and the scope in the first sentence, then layers the return shape. The line break mid-sentence between the title line and 'Walks every active course' slightly hurts flow, but no sentence 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?

For a no-argument aggregate tool with an output schema, the description supplies what the schema cannot: which courses are included, which assignments are excluded, and the shape of the per-course breakdown. Only the cost/fan-out behavior of scanning all courses is left 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?

There are zero parameters, so the schema carries nothing to interpret and a 4 baseline applies. The description's mention of scope filtering ('active course', excused filtered out) effectively explains the implicit filtering behavior of a no-arg call.

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

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

The description opens with a specific verb and resource plus its scope: 'Cross-course missing/late assignment scan' and 'Walks every active course'. That distinguishes it from per-course siblings such as list_assignments and get_my_submission without needing 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?

The word 'cross-course' and 'walks every active course' imply this is the bulk/aggregate option, but the description never states when to prefer it over per-course tools like list_assignments or get_assignment, and names no exclusions. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavior beyond that: chronological unification across item types, pre-computed submission state per item, and the default date window of today through seven days. It does not discuss pagination or result limits, which keeps 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?

The lead sentence front-loads the core identity, and the Args block is compact and scannable. The informal 'what's on my plate' framing is slightly loose but earns its place by conveying scope quickly; nothing is redundant.

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 an output schema present, the description needn't explain return values, and it covers all four parameters plus the aggregation behavior. It is nearly complete for a read-only feed tool; only edge behavior like empty windows or result caps is 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 0%, so the description must carry the parameter burden, and it largely does: it gives the YYYY-MM-DD format and default window for start_date/end_date, an example value for context_codes, and the meaning of filter_new_activity. The only soft spot is 'fresh updates' for filter_new_activity, which is not precisely defined.

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 resource (a unified planner feed) and enumerates exactly what it aggregates: assignments, quizzes, discussions, announcements, calendar events, and user notes, unified chronologically with submission state pre-computed. This clearly distinguishes it from siblings like list_assignments or list_announcements, which return single item types.

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

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

The phrase 'One call returns...' implicitly positions this as the aggregate alternative to the per-type list tools, giving an agent a clear reason to pick it. However, it never explicitly states when NOT to use it or names a sibling alternative, so the routing guidance is inferred rather than spelled out.

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

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

Annotations already cover the safety profile (readOnlyHint true, destructiveHint false, openWorldHint true), so the description need not restate that. It adds genuine context by describing the aggregation scope and the template-generated `summary` string in the typed response. It omits cost or latency implications of an open-world multi-source aggregation, which is the main 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?

The digest purpose is front-loaded in the first line, followed by the source list and the sibling routing advice in a logical order. The sentence about being the 'main catch me up tool' slightly repeats the opening purpose statement, but the description contains no substantial waste.

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?

An output schema exists, so return values need no explanation, and the annotations plus the aggregation list cover behavior well. For a two-parameter tool at 0% schema coverage, however, leaving both time-window parameters undefined is a material omission in an otherwise complete definition.

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

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

Schema description coverage is 0%, so the description carries the full burden for `lookback_days` and `lookahead_days`. 'Since last check' loosely implies a backward window, but the description never explains the unit, the default of 14, or what `lookahead_days` (default 7) controls, so an agent must guess whether future planner items are included.

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 ('what is new since last check' digest) and enumerates the sources it aggregates: activity stream, inbox unread, planner, announcements, recent feedback, and missing work. It also distinguishes itself from siblings by naming activity_stream_summary and planner_items as things it replaces.

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

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

It gives clear positive routing ('the main catch me up tool') and an explicit preference over manually stitching together activity_stream_summary, planner_items, and missing work. It does not state when not to use it, for example when a learner wants a single-course view.

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