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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds genuinely new behavior: the run is asynchronous, re-calling while status is 'running' is a wait rather than a second scan, results are deltas against the last committed check, and a commit step follows. The 14-day deadline window and dashboard-news inclusion further characterize the payload beyond anything in the structured fields.

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

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

The delta-return promise leads, then scope defaults, then the polling/commit lifecycle — a front-loaded ordering that matches call order. No sentence is padding; each carries either return semantics, a parameter rule, or a lifecycle step.

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 orchestration tool with no output schema, this covers the important ground: what comes back, how to poll, and what to do afterward. It falls just short of complete because `depth` and `wait_seconds` are undefined, and the shape of the status object behind the 'running' answer is only implied.

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 load: it explains the `section` fallback and gives concrete ref_id syntax for `exclude`. However `depth` (default 1) and `wait_seconds` (default 40) are never mentioned, leaving half the parameters with no semantic anchor anywhere.

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 every course of the current semester in one go') and narrows the output to a delta ('only what changed since the last committed check'), enumerating the categories returned. That scope statement lets an agent distinguish it from the per-course ilias_scan and from the ilias_list_* siblings without opening a schema.

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

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

Gives explicit operating instructions: the semester is derived from the newest dashboard section unless `section` is set, `exclude` takes ref_ids in either form, and after the scan the agent must call ilias_commit_scan(check_id). The one gap is that it never names when to prefer ilias_scan or ilias_list_courses over a full-semester sweep, so alternative selection is left to inference.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=false, so the description's 'local bookkeeping only; nothing is sent to ILIAS' largely reinforces the openWorldHint signal rather than adding new information. It does usefully confirm the write is purely local and non-destructive to remote state, but it never states what the write overwrites, i.e., that any existing baseline is replaced.

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

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

Two short sentences, front-loaded with the action and followed by the safety caveat. No filler, though the parenthetical about check_id would read better as an explicit statement about the parameter.

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?

Output schema exists, so return values need not be explained, and annotations cover the safety profile. The remaining gap is limited to the overwrite semantics of the baseline and the scan_id/check_id ambiguity, which are real but narrow for a one-parameter local bookkeeping 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?

With 0% schema description coverage, the description carries the full burden for the single scan_id parameter. It partly does so by implying the value is a scan or check identifier, but the parenthetical '(pass its check_id)' names the value differently from the schema's 'scan_id', leaving an agent unsure whether a check ID is a valid value for that field.

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 concrete verb ('make ... the new baseline') and names the two sibling tools whose output feeds it (ilias_scan and ilias_check_all), so an agent can tell this apart from the scan-generating tools. It is not a full 5 because the resource is only named indirectly ('a scan, or a whole ilias_check_all check') and the ID naming ('check_id' here vs. 'scan_id' in the schema) muddies what is being promoted.

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 this after running ilias_scan or ilias_check_all to promote the result to the baseline. There is no explicit statement of when not to call it, whether the referenced scan must already exist, or whether re-committing replaces a prior baseline.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false; the description adds real value beyond that by disclosing the no-clobber guarantee ("Never overwrites a different file") and the sandboxed root with its env var and default path. It omits what happens when an identical file already exists, 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?

Two short sentences, front-loaded with the action and immediately followed by the safety guarantee and path constraint. No filler; the only minor cost is the awkward line break mid-sentence.

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?

Output schema exists, so return values need no prose, and the mutation/safety profile is covered. The blocking gap is the undefined "target" parameter, which leaves the agent unable to form a valid call without trial and error.

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 two required parameters. The description clarifies dest_dir only indirectly (a folder under the download root) and leaves "target" completely undefined — no indication whether it is a file ID, an ILIAS URL, or a path, which is essential for correct invocation.

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 concrete verb+resource+destination: "Save a course file to a folder inside the configured download root." An agent can tell this writes a file locally, implicitly distinct from ilias_read_file, though 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?

No when-to-use or when-not-to-use guidance and no routing to alternatives such as ilias_read_file (view content without saving) or ilias_scan. The only constraint given is a location constraint, not a selection rule.

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 that this is a 'Show all' listing and what data classes it surfaces, but says nothing about pagination, failure modes, or what access/permissions are required for the exercise object.

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 compact fragment with the resource and returned fields front-loaded and no filler. It is terse to the point of being telegraphic, 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for an open-world listing tool with one required, entirely undocumented parameter, the definition leaves a real gap an agent must guess at before it can call the tool.

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

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

Schema coverage is 0% for the single required parameter 'target', so the schema supplies no meaning at all. The description never explains what 'target' refers to (exercise object ID, URL, alias?) or how to obtain it, leaving the only required input completely undefined.

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 (assignments of an exercise object) and enumerates the returned facets (deadlines, start, submission status, files), which lets an agent distinguish it from siblings like ilias_list_items or ilias_list_courses. It is a noun phrase rather than a verb phrase and does not name an alternative tool, but the operation is unambiguous.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives among the many sibling list tools. The parenthetical "('Show all' view)" hints at a view mode but never explains how it compares to other views or tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds useful context beyond annotations: the data source is the ILIAS dashboard and the results include ref_ids and semester sections. It does not address scoping questions such as whether all enrollments are returned or how results are ordered, and an output schema exists to cover return values.

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 short sentence with no filler, and the key qualifier (the user's courses and groups) is front-loaded. The sentence fragment lacks a verb, which costs a little at the margins but 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?

For a zero-parameter read tool with full annotations and an output schema, the description is minimally sufficient: it says what list is returned and what fields matter. It stops short of explaining how the returned ref_ids relate to downstream tools or whether the list is filtered to active enrollments, which would have made it complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The mention of ref_ids and semester sections describes returned content rather than inputs, which is harmless and slightly helpful framing.

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 ('the user's courses and groups from the ILIAS dashboard'), which is enough to distinguish it from siblings like ilias_list_assignments or ilias_list_news. It is a noun phrase with no verb, but the tool name supplies the 'list' action, so the overall purpose is clear 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?

There is no explicit guidance on when to call this versus the many sibling list tools, nor any stated preconditions. A weak usage signal is implied by mentioning ref_ids (i.e. call this first to obtain identifiers other tools need), but the agent must infer that rather than being told.

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 useful context that no thread bodies are fetched, but says nothing about pagination, result limits, or behavior for invalid targets.

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

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

Two short sentences, front-loaded with the resource and its scope, then the returned fields. 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?

An output schema exists, so return values need no explanation, and the field list is a bonus. The gap is the unexplained 'target' argument and the absence of any indication of result size or pagination for a list operation.

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

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

The single required parameter 'target' has 0% schema coverage and the description never explains what a target is or what form it takes (forum id, URL, title). With one undocumented parameter, the description should compensate and does not.

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

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

States a specific verb+resource: it lists forum threads and enumerates the returned fields (titles, authors, counts, last activity). The clause 'Threads are never opened' sharpens the scope by making clear this is metadata only, which separates it from any content-reading behavior.

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

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

Usage is implied by the name and by 'Threads are never opened', which tells the agent this is the discovery step before reading content. However, no alternative is named and no precondition is given (e.g. that a forum target is required to have been resolved 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 readOnly=true and destructive=false, so safety is covered. The description adds genuine behavioral detail beyond them: recursion is triggered by depth > 0, recursion is capped, and files expose an 'already_read' flag. However, '(max 3)' is ambiguous (max depth vs. max child items), which blunts the value of the added context.

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

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

Three short lines, front-loaded with the returned object shape and followed by the depth and read-state caveats. No filler sentences, though the parenthetical '(max 3)' could have been made precise at no extra length cost.

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 spending most of the description on returned fields (type, title, ref_id, version/date/size) partly duplicates structured data while the required 'target' argument is left undefined. For a 2-parameter listing tool with a read-only profile the definition is serviceable, but not complete enough to guarantee a correct first call.

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 bears the full burden. It partially explains 'depth' (values above 0 trigger recursion with a cap), but never clarifies the accepted format or scope of 'target' (ref_id? path? course id?), which is the required parameter. Half the parameter surface remains undefined.

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 makes clear it returns the objects contained in a course/folder/group/session and enumerates the key fields (type, title, ref_id, version/date/size), so an agent can tell this is a container-listing tool. It lacks an explicit verb and never distinguishes itself from siblings such as ilias_list_courses or ilias_list_assignments, which overlap in surface area.

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 other list_* siblings, nor any statement of prerequisites or exclusions. The only usage-like hint is the parenthetical about depth > 0, which describes behavior rather than when to use the tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the useful behavioral context that news can come from either the dashboard or a course page, but says nothing about defaults, pagination, ordering, or what happens when target is invalid.

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 short sentence with no filler, and the key distinction between dashboard and course-page news is front-loaded. It is efficient, though the extreme brevity contributes to the gaps in parameter guidance.

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

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

The tool is simple (one optional parameter) and an output schema exists, so return-value detail is unnecessary. The critical missing piece is how the nullable target argument maps to a course, which leaves the agent guessing for the only input that affects 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% for the single 'target' parameter, so the description must carry the burden. It only implies that target refers to a course page ('from a given course page') and that omitting it reads the dashboard, without specifying accepted formats (ID, URL, slug) or the default behavior explicitly.

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 identifies the resource ('News items') and the two sources it can read from (dashboard news page vs. a course page). The verb is implicit rather than stated, but the retrieval intent is unambiguous and distinguishable from sibling listing tools like ilias_list_courses or ilias_list_items.

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 indicates two usage contexts (dashboard-wide or a specific course page), which implies the optional target parameter selects the course scope. However, it gives no explicit when-to-use/when-not guidance, no prerequisites, and no hint about how to choose a target value.

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 the useful facts that output is paginated via offset/next_offset, which is beyond what annotations convey, but says nothing about truncation via max_chars or what links look like when included.

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

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

Two short sentences, front-loaded with the resource identification and followed by usage and pagination guidance. Tight and free of filler, though the parenthetical example list slightly dilutes the lead sentence.

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?

Output schema exists, so return values need not be explained. However, with a required 'target' parameter and three optional parameters at 0% schema coverage, the description leaves the agent guessing about input formats—the most consequential omission for a tool the agent will reach for as a fallback.

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 full burden, yet it only mentions offset pagination. It never explains what 'target' accepts (URL, ref ID, object id?), what max_chars does when exceeded, or what include_links changes. It also references 'next_offset', which is not an input parameter but a return field, muddying the signal.

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 ('Readable text') and resource ('any ILIAS page') with three illustrative examples of page types. It does not explicitly distinguish itself from the sibling ilias_read_file, which is the closest overlap, 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?

'Use when a structured tool misses something' is a genuine fallback cue, but it is vague about which structured siblings it backstops and under what conditions the fallback is preferable. No explicit when-not guidance or named alternative.

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

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

Beyond the readOnlyHint/openWorldHint/non-destructive annotations, the description exposes genuinely non-obvious stateful behavior: unread-page incremental reads, an 'already_read' status for unchanged fully-read files, and the fact that query snippets do not count as read. These are exactly the surprises an agent would otherwise stumble into.

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 what the tool returns, then one terse clause per behavior mode. No filler sentences and nothing 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 five-parameter, stateful read tool with an output schema already covering return shape, this is nearly complete. The gaps are the undocumented `max_chars` truncation behavior and the absence of explicit sibling routing for download versus text extraction.

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 does so for three of five parameters with real semantics ('2-4,7' page syntax, pipe-delimited keyword query, force re-read) plus the dual meaning of `target`. `max_chars` is never mentioned, leaving one parameter with no meaning beyond its 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?

The description names a specific resource (course file text) and enumerates the supported formats (PDF, PPTX, DOCX, text, ZIP), plus the identifier mode (ref_id or download URL). That distinguishes it in substance from ilias_download_file, but it never names a sibling explicitly, so the differentiation must be inferred from 'Text of'.

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, actionable guidance for each mode: default returns only unread pages, `pages` re-opens specific pages, `query` returns snippets, `force` re-reads everything. What it lacks is routing guidance against alternatives such as ilias_download_file or ilias_page_text, so an agent must decide on its own which tool to reach for.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description must add context rather than restate safety. It does: it discloses that results are relative to a previously committed baseline, that the call returns a scan_id, and that the baseline is only advanced by a separate commit call. Not disclosed: whether an uncommitted scan leaves any server-side state, or how large a crawl (depth) affects runtime.

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: what it does, what it returns, and the required follow-up. The diff behavior and the commit dependency are front-loaded with no filler or restated field names.

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 need not be described, and the stateful workflow is covered. For a crawl tool with four undocumented parameters, however, the undefined target format and depth semantics are real gaps an agent could get wrong on first invocation.

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

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

Schema description coverage is 0%, so the description carries the burden, and it only partially does so. 'One course' implies target is a course identifier, and the mention of assignments and forum threads maps loosely to include_assignments/include_forums, but neither the expected target format (ID vs. URL) nor the meaning of depth is explained anywhere.

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 ('crawl') plus resource ('one course') and a precise result definition (new/changed/removed items, assignments and forum threads versus the last committed scan). That diff-based, stateful framing distinguishes it from plain listing siblings such as ilias_list_items and ilias_list_courses, though it never contrasts itself with ilias_check_all, which is the nearest-looking alternative.

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

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

Gives a clear workflow obligation: after findings are recorded, call ilias_commit_scan so the next scan compares against this baseline. That is genuine when-to-use guidance and names the sibling. It does not, however, say when to prefer this over ilias_check_all or when a scan is unnecessary, so exclusions are absent.

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 covered, and the description usefully adds that the call performs no network I/O, which matters for latency and failure modes. It says nothing further about caching, staleness of the reported login state, or whether the read-only policy is a fixed config or a live server value, so it adds only modest context. Note the mild tension between 'No network' and openWorldHint=true, though openWorldHint concerns the external domain rather than this call's I/O.

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 terse fragments with no filler; the enumerated payload comes first and the operational caveat ('No network') is front-loaded at the end where it is easy to catch. Phrasing is telegraphic noun-list rather than a full sentence, which costs a little clarity but wastes no space.

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

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

With zero parameters and an existing output schema, the description need not explain return values, and the complexity is low. It communicates the payload categories and the offline nature of the call, which is enough for an agent to invoke it correctly; only the relationship to diagnostic siblings remains uncovered.

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 schema already conveys. Baseline 4 applies.

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

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

The description names the concrete contents returned — configuration, login state, request counter, read-only policy — so an agent knows this is a diagnostics/state report rather than a data-fetch tool. The verb 'reports/returns' is implied rather than stated, and it does not name a sibling it replaces, keeping it 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?

There is no explicit when-to-use statement and no alternatives named, even though siblings like ilias_check_all and ilias_scan plausibly overlap as diagnostic entry points. The 'No network' note hints that it is a cheap local preflight check, but that is left entirely to inference.

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