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

With no annotations, the description carries the full burden; it does disclose the meaningful side effect (writes the file into MIeL's local folder) and the return shape (path). It is silent on overwrite behavior, permissions/auth needs, error conditions (missing materia or archivo_id), and whether the download is idempotent — gaps that matter for a tool with a filesystem side effect.

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 destination, then the return value, then the parameter provenance hint. Nothing is padded 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?

Adequate for a two-parameter tool: the effect and return value are covered even without an output schema. But for a tool that writes to local storage, the absence of any note on overwriting, error handling, or the meaning of `materia` leaves real holes an agent would need to guess at.

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 compensate; it does explain where `archivo_id` comes from, which is genuinely useful and not in the schema. However, `materia` is left completely undefined — neither the schema nor the description says whether it is a name, slug, or ID, and both parameters are required, so the compensation is only partial.

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 ("Descarga un archivo de una materia") plus the destination (local MIeL folder) and the return value (the path). It also implicitly separates itself from the sibling `listar_archivos` by declaring that `archivo_id` is obtained there, so an agent can tell listing from downloading.

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 the purpose-driven use case ("para poder leerlo después") and the prerequisite for the key parameter ("`archivo_id` sale de listar_archivos"), which effectively routes the agent to the right sibling first. It stops short of stating when NOT to use it (e.g., re-downloading an already-synced file) or what happens if the file already exists locally.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It does a good job by stating the return contents and, importantly, disclosing the side effect that reading the topic "puede marcarlo como leído en MIeL"; it does not cover permissions, pagination, or error behavior, but the side effect disclosure is significant.

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 two sentences and front-loads the purpose before adding parameter provenance and the read-marking side effect. Every sentence adds useful information without unnecessary padding.

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 description partially compensates for the lack of annotations and output schema by listing returned fields and warning about the read-marking side effect. However, it leaves `materia` semantically unexplained and does not address pagination, permissions, or error behavior, so it is only adequate for a two-required-parameter 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%, so the description must compensate for both parameters. It explains where `tema_id` comes from, but it does not explain what `materia` means or how it relates to the topic, leaving one of two parameters undocumented in both schema and description.

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

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

The description states a specific verb and resource: it returns the messages of a forum topic, and it explicitly lists the message fields returned. The phrase "`tema_id` sale de listar_temas_foro" also distinguishes this tool from the sibling that lists topics rather than reading a topic's messages.

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

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

The description gives useful usage context by noting that `tema_id` comes from `listar_temas_foro`, implying this tool is used after listing topics. However, it does not explicitly say when to use this tool versus alternatives, nor does it state exclusions or prerequisites beyond parameter provenance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It conveys listing and filtering, but does not state read-only safety, permissions, pagination, or what the returned file/link entries look like.

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, front-loaded with the core operation, and the Args block efficiently documents each input. Every sentence adds useful 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?

Parameters are adequately documented despite zero schema coverage. However, with no output schema and no annotations, the description should say more about the return shape (what fields a file/link entry has) and usage relative to 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?

Schema description coverage is 0%, so the description must explain parameters, and it does: 'materia' accepts an id or partial name with an example, 'tipo' lists allowed values, and 'buscar' is an optional keyword filter. Some nuance is missing, such as case sensitivity or exactly what 'buscar' searches.

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 ('Lista') and resource ('contenidos (archivos y enlaces) de una materia'), making the operation clear. It does not explicitly distinguish itself from siblings like listar_materias or descargar_archivo, but the resource scope is unambiguous.

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

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

The purpose implies when to use it: browsing files/links for a subject. However, it gives no explicit when-to-use guidance, no exclusions, and does not name alternatives such as descargar_archivo for downloading a specific 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?

No annotations are supplied, so the description must carry the behavioral load. It implies a read-only listing and helpfully discloses the shape of the data returned (unread forum counts, available tools per course), but says nothing about authentication, whether results are cached or require sync first, or about side effects.

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

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

It is a single compact sentence, front-loaded with the verb and resource, with the return fields grouped in a parenthetical list. There is no filler, though the field enumeration partly duplicates what the existing output schema already documents.

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 return-value enumeration is somewhat redundant, but the description still omits the parameter behavior and any notion of when the listing should be preferred over its siblings. Adequate for a simple zero-required-parameter list call, 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 single parameter, incluir_ocultas, has 0% schema description coverage, so the description was the only chance to explain it. It does not mention the parameter at all, leaving the agent to guess that hidden courses are excluded by default. This is the clearest gap given the 1-parameter surface.

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 ("Lista las materias del alumno") and enumerates the payload: commission id, code/commission detail, available tools, and unread forum messages. That is far more informative than the name alone. It never contrasts itself with the sibling tools (listar_temas_foro, novedades, listar_archivos), so the differentiation is only implicit in the resource noun.

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 statement, no prerequisite, and no named alternative. A user could reasonably confuse this with novedades or listar_temas_foro when looking for course-related information, and the description never resolves that ambiguity.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses what the response contains (message counts, last message timestamp, unread count), which signals a read operation, but says nothing about pagination, result limits, ordering, or permission requirements — meaningful gaps for a list 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?

A single well-formed sentence that front-loads the action and folds the return payload into the same clause. No filler and nothing buried.

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

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

With no output schema and no annotations, the description does a fair job of outlining returned fields, but leaves the parameter format and pagination/ordering behavior unspecified. For a simple one-parameter list tool this is adequate but has clear 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% for the single required parameter 'materia'. The description only restates that it operates on a subject, without clarifying whether the value is a name, ID, slug, or code — exactly the detail an agent needs to supply a valid argument.

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 ('Lista los temas del foro') scoped to a subject, and even enumerates the returned fields (message count, last message date, unread count). It implicitly distinguishes itself from leer_tema_foro by operating at the topic-list level, but never names that sibling 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 purpose implies when to use it — browsing a subject's forum before opening a topic — but there is no explicit when-to-use, when-not, or reference to siblings like leer_tema_foro or sincronizar_materia. The agent must infer the routing.

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

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

With no annotations, the description carries the full burden and it discloses the critical stateful trait: the first call marks everything as seen and returns the initial state, meaning it advances an internal cursor. It does not state whether subsequent calls also mutate the cursor or what happens on errors, but the most important non-obvious behavior is explicit.

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 delta semantics and followed by the important first-run caveat. Every sentence carries information an agent needs, with 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 structure needn't be explained, and there are no parameters to cover. The description supplies the stateful delta behavior and first-run semantics. It could still clarify what counts as an 'active' materia and whether the last-check state is per-user or global, but nothing essential is missing for correct invocation.

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

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

The tool takes zero parameters, so there is nothing for the schema or description to disambiguate. The baseline for a parameterless tool applies; the description correctly implies no input is needed.

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: it shows what changed since the last check in each active materia, and enumerates the change types (new files, forum topics with new messages). This distinguishes it from the sibling listar_* tools, which enumerate full collections rather than a delta, though no sibling is named directly.

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 poll for updates, and use listar_archivos/listar_temas_foro for full listings. However, the description never says when not to use it or names an alternative, so the agent must infer routing from the sibling names.

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

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

With no annotations, the description carries the behavioral burden and discloses important traits: it downloads only new files to a local folder, lists external links without downloading them, and syncs all active subjects when `materia` is empty. It does not cover permissions, overwrite behavior, or error handling, but the core side effects are transparent.

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

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

The description is two sentences, front-loaded with the main action and followed by the key scope and exclusion. Every sentence adds useful information without 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 one-parameter sync tool with an output schema, the description covers the essential invocation semantics and the main behavioral caveat about external links. It leaves out some operational details such as destination folder handling and permissions, but is otherwise complete enough to select and 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 description coverage is 0%, so the description must compensate for the single `materia` parameter. It usefully explains that an empty value means all active subjects, but it does not clarify the expected format of a non-empty subject value, such as ID versus 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 uses a specific verb and resource: 'Descarga solo los archivos nuevos de una materia'. It clearly scopes the operation to new files and explains the all-subjects case, though it does not explicitly contrast itself with sibling tools such as descargar_archivo or listar_archivos.

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 explains when the empty `materia` value applies: all active subjects are synced. However, it does not state when to use this bulk sync tool versus alternatives like descargar_archivo or listar_archivos, so usage guidance is implied rather than explicit.

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