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

Annotations already declare readOnlyHint and openWorldHint, and the description adds meaningful context beyond them: requests are made with the session cookies and auth headers (so auth is inherited, not supplied), and the body can be persisted to a workspace file. It does not say what a file save does to an existing file or how truncation behaves, but the auth and side-effect disclosures are the important ones.

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

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

Two sentences, zero filler, with the core action and the discovery workflow front-loaded. The leading 'Advanced:' label is slightly vague but does usefully set expectations about the audience.

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 openWorldHint read tool with annotations carrying the safety profile, so the bar is lower, but the description still leaves open how the response is shaped, what maxChars truncation does to it, and what happens on auth failure — all things an agent calling an arbitrary endpoint would want to know.

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

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

Only saveTo has schema documentation (33% coverage). The description covers url and saveTo in prose ('GET a platform endpoint', 'save the body to a file in the workspace'), but maxChars — a truncation limit with a default and a 200000 maximum — is explained nowhere, which matters because it silently bounds the returned body.

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 platform endpoint) and adds a key qualifier: the endpoint is one 'discovered with open_page', which separates it from the browser-navigation siblings (open_page, click) and the domain-specific readers (get_lesson, get_transcript). It lacks an explicit contrast statement with those siblings, so it stops short of 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?

'Advanced:' and the parenthetical tying it to open_page imply a two-step workflow (discover, then fetch), which is real usage context. But there is no explicit when-to-use-this-instead-of-open_page guidance and no stated prerequisites or failure conditions (expired cookies, unauthorized endpoints).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is largely covered. The description adds that it returns the new snapshot and is useful for expanding sections, but it does not disclose potential side effects of clicking, failure behavior, or what the snapshot contains.

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

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

Two tight sentences with the core action front-loaded and no wasted wording. The prerequisite and return behavior are stated efficiently.

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

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

Covers the main prerequisites, action, return value, and typical use case. Given that annotations declare readOnly/openWorld and the schema fully describes parameters, it is largely complete, though it omits failure handling and snapshot contents.

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

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

Schema description coverage is 100%, so all five parameters are documented in the schema. The description reinforces the text-vs-selector identification mechanism but adds no detail beyond the schema for nth, waitMs, or saveCaptures, so baseline 3 is appropriate.

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

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

States a specific verb and resource: click an element on a page opened with open_page, using visible text or CSS selector, and returns a new snapshot. It clearly distinguishes itself from open_page by naming it as the prerequisite, though it does not explicitly differentiate from the sibling download_by_click.

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 (expanding sections of a web app) and labels the tool as advanced, implying caution. It does not state when not to use it or explicitly compare it to alternatives like download_by_click.

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 and openWorldHint, so the safety profile is covered; the description adds value by disclosing the data source ('from the progress reported by the platform', i.e. platform-reported rather than computed) and by enumerating what the response contains in the absence of an output schema. 'Informational only' reinforces the non-mutating nature without contradicting annotations.

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

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

Three short sentences, front-loaded with what the agent gets back, followed by the omission default and a scope caveat. Minor redundancy between 'Informational only' and readOnlyHint, but nothing bloated.

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

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

With no output schema, the description carries the burden of describing returns and does so by naming the concrete progress elements. For a single-optional-parameter read tool this is essentially complete; only the aggregation behavior's output shape (e.g. grouping by course) 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 coverage is 100% and the schema already explains the course-code format, so the baseline is 3. The description adds genuine semantics beyond the schema by explaining what happens when the optional `course` parameter is omitted (aggregate over all started courses), which the schema does not state.

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 the specific resource (course progress) and enumerates the concrete outputs: remaining video time, unfinished lessons/paragraphs, and still-open self-assessment tests. That is far more specific than the vague title 'Viewing progress'. It does not explicitly distinguish itself from the sibling `status`, which is the only remaining ambiguity.

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

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

It states the default behavior when `course` is omitted ('summarizes every started course'), which is useful implied usage guidance. However, it never says when to prefer this over siblings like `status` or `list_lessons`, and gives no 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), and the description usefully adds that requests carry the student session and land in the workspace. It does not disclose what happens if the destination path already exists (overwrite vs. fail), nor what occurs with a non-platform URL — meaningful gaps for a write tool.

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?

One front-loaded sentence with the key constraint (direct platform URL, student session, workspace) stated up front and no waste. Slightly dense with parenthetical examples but efficient.

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

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

For a 2-parameter tool with annotations present this is roughly adequate, but with no output schema the description should say what comes back (e.g., the saved workspace path or confirmation) and how failures on bad URLs are surfaced. Those omissions keep it at minimum viable.

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 50%: `dest` is documented in-schema with an example, while `url` has only a `format: uri` constraint. The description partially compensates by constraining the URL to 'a direct platform URL' rather than arbitrary web addresses, but adds nothing about the return or destination-path semantics.

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

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

States a specific verb (download) and resource (file: PDF, slides) plus the destination scope (workspace), so the agent knows exactly what the tool produces. The phrase 'direct platform URL' implicitly distinguishes it from the click-based sibling download_by_click, but the sibling is never named.

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: 'direct platform URL' hints that this is the path when you already have a URL, versus download_by_click or open_page. No explicit when-to-use, when-not-to-use, or named alternative is given, leaving the agent to infer the routing against 11 siblings.

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 adds real context beyond the annotations by explaining that a click on the live page triggers the download and that this targets linkless buttons. It does not say whether the call waits for the download to finish, how failures or timeouts surface, or whether an existing file in destDir is overwritten — notable given idempotentHint=true on a write-to-disk operation.

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

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

One sentence, front-loaded with the action, with the qualifying condition placed in parentheses where it belongs. No filler.

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

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

For a 4-parameter, open-world interaction tool with no output schema, the description covers what it does and when, but leaves the agent guessing about completion semantics, return value (e.g., saved file path), and error/overwrite behavior.

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

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

Schema description coverage is 100%, so all four parameters (nth, text, selector, destDir) are already documented in the schema. The description adds no meaning about how text vs. selector interact or how destDir is resolved, so baseline 3 applies.

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

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

Specific verb+resource: it downloads a file, and the mechanism (clicking an element on the current page) is stated. The parenthetical 'download buttons without a direct link' implicitly separates it from the sibling `download`, though it never names that sibling.

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 parenthetical gives a clear triggering condition: use this for download buttons that lack a direct link. It does not explicitly name `download` or `click` as the alternatives to avoid, so the routing is inferred 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?

readOnlyHint=true and openWorldHint=true already establish the safe-read, external-network profile, so the description adds only the return-content inventory. It says nothing about auth requirements, failure modes for an invalid lesson number, or whether fields like self-test are always present. No contradiction with the 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?

One front-loaded sentence, with the core purpose first and field details after. The trailing clause 'watchUrl, the link to watch it on the platform' is slightly wordier than necessary but still 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?

There is no output schema, so enumerating the returned fields (objectives, teacher, paragraphs with duration/progress, handout URL, self-test, watchUrl) does real work. With only two schema-documented parameters, the definition covers what an agent needs in order to call and interpret the result.

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

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

Schema coverage is 100% and both parameters are documented, including that the course code comes from list_courses and the lesson number matches list_lessons. The description adds no further parameter meaning, so the baseline 3 applies.

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

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

A specific verb-plus-resource ('Full details of one lesson') that is clearly the detail counterpart to list_lessons, and it enumerates what the payload contains. It never explicitly names the sibling, so the distinction 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?

Usage is only implied: fetch a single lesson's details rather than a listing. There is no explicit when-to-use, no named alternative, and no preconditions such as needing a course from list_courses first.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful format details (subtitles to Markdown, objectives, paragraph sections), but omits operational behavior such as truncation via maxChars, paragraph selection semantics, and error cases.

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 concise sentences with the core content front-loaded and no wasted wording. The structure moves from what the tool returns to why an agent would use it.

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

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

With no output schema, the description does a fair job describing the Markdown structure, but it does not explain maxChars truncation, paragraph-only extraction behavior, or what happens when a lesson has no subtitles. For a four-parameter tool with no output schema, those are meaningful 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 coverage is 75%, with course, lesson, and paragraph documented in the schema. The description adds no parameter-level meaning, and maxChars remains undocumented in both schema and description, so the baseline of 3 is appropriate.

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

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

The description clearly states the resource and output: lesson text from video subtitles, rendered as Markdown with objectives and one section per paragraph. It distinguishes itself from downloading, but does not explicitly differentiate from the sibling get_lesson tool.

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

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

It gives clear usage contexts — study, summarize, or quiz — and notes that no download is needed. It still lacks explicit when-not guidance or a direct comparison to get_lesson, so it is clear but not fully routing-aware.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description still adds real behavioral value by disclosing the return shape (code, title, CFU, progress) and the null-progress semantics, which matter for a tool with no output schema. It omits ordering and pagination, keeping it short of 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?

A single sentence that front-loads the action and resource, then packs the returned fields plus the null edge case. Every clause carries information and there is no filler.

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

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

For a zero-parameter read tool with annotations covering safety and no output schema, the description supplies the field-level return contract an agent needs to interpret results. Missing only secondary details such as result ordering or empty-enrollment 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a 0-param tool is 4. The description correctly implies a no-argument call scoped implicitly to 'the student'.

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

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

States a specific verb ('List') and resource ('the student's enrolled courses'), and enumerates the returned fields (code, title, CFU, progress). This clearly separates it from list_lessons and get_lesson, 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?

Usage is implied: call it to enumerate the student's enrolled courses, and the 'null if not started' note hints at the no-activity case. There is no explicit when-to-use vs. when-not, and no routing away from the overlapping sibling course_progress.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real value beyond that by disclosing what the response contains (teacher, progress, video paragraphs, PDF handout presence) and how the compact flag changes the payload — important since there is no output schema.

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

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

Two sentences, zero filler, with the response-content summary front-loaded and the compact behavior stated second. Every clause earns its place.

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

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

With no output schema, the description usefully sketches the return shape and ties the course parameter back to list_courses. Minor gaps like pagination or ordering across lessons are not addressed, but nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented. The description still adds actionable meaning by framing compact as an opt-in switch ("Set compact=false for objectives and media URLs"), telling the agent when flipping it is worthwhile rather than just what it does.

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

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

States a specific verb and resource ("List the lessons of a course") and enumerates the returned fields. It does not explicitly distinguish itself from the sibling get_lesson, though the singular/plural split is reasonably obvious.

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 usage guidance is only implied: listing lessons for a course is clearly the batch counterpart to get_lesson, and the course code reference to list_courses hints at a prerequisite. There is no explicit when-to-use or when-not-to-use statement.

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 readOnly and openWorld, but the description adds real substance: it runs under the student session, returns a composite payload including captured JSON API calls, and actively blocks tracking requests with a blockedRequests list. Those are behavioral traits the annotations cannot express.

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

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

Two sentences, front-loaded with the action and immediately followed by the return shape and the tracking-block caveat. No filler, though the 'Advanced:' qualifier could have been expanded into an actual usage condition rather than a bare label.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating text, links, iframes, API calls and blockedRequests. Parameters are fully covered in schema, so the only gap is guidance on when this beats sibling 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?

Schema coverage is 100% and the url parameter's default (portal home) and saveCaptures' privacy warning are documented there. The description only implies that 'url' is a platform URL, adding little beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('open a platform URL') and specifies what comes back (text, links, iframes, JSON API calls). The 'Advanced:' prefix signals it is a lower-level fallback relative to siblings like click or api_get, though it never names those alternatives.

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?

'Advanced:' implies it is a reserve tool for cases where simpler tools fail, but no explicit when-to-use or when-not-to-use condition is stated and no sibling is named. An agent must infer the routing from the prefix 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?

The readOnlyHint=true annotation already establishes this as a non-mutating read, and the description adds a genuine privacy disclosure ('Returns no personal data') that annotations do not cover. It omits what the response actually looks like (a validity flag plus expiry timestamp) and what happens when no session is saved.

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 waste; the core check (validity) is front-loaded ahead of the secondary detail (token expiry) and the privacy note.

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

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

With no output schema, the description carries the burden of describing return values, and it does so only partially — an agent knows it gets validity and expiry, but not the shape of the response or how the 'not logged in' case is reported. Adequate for a simple zero-param status probe, but not complete.

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

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

The tool takes zero parameters, which is the baseline-4 case. There is no parameter syntax to explain, and the description correctly does not invent any.

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: check the saved platform session's validity and access-token expiry. Neither the name nor the title alone would convey the token-expiry aspect, so the description adds real information, and no sibling tool overlaps with this diagnostic role.

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 usage is implied — an agent would naturally call this to verify session state before other browser-backed calls — but the description never says when to use it, when not to, or what to do on an invalid result. There are no sibling alternatives to route to, which limits how much guidance is even possible.

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 idempotentHint=true, destructiveHint=false and openWorldHint=true; the description adds real value beyond them by explaining that existing files are preserved unless force=true and by enumerating the files written to disk. It does not mention rate limits, auth, or failure behavior for an invalid course code.

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

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

Two sentences, both front-loaded with the destination layout first and the overwrite rule second. No filler text.

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

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

For a four-parameter download tool with no output schema and solid annotations, the description covers destination, artifacts and overwrite policy. Minor gap: no mention of what happens when the course code is invalid or when transcripts=false.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema; the description only reinforces the force/default-keep semantics. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb (download), a specific resource (every PDF handout and lesson transcript of a course), the exact destination path (<folder>/risorse/) and the side artifacts (indice.md, corso.json). This is clearly distinguishable from single-item siblings like download, get_lesson and get_transcript.

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 bulk nature of the operation implies when to use it versus the single-file download tools, and the force=true clause tells the agent how re-runs behave. However, it never explicitly names the alternative tools or states when not to use this one.

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