uned_sincronizar

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

With no annotations the description carries the full burden, and it does disclose the significant side effects well: it writes into ~/UNED, extracts text from files, indexes for search, regenerates fichas/index/calendar, and returns a change report. It still omits auth requirements and whether the operation is reversible or how expensive it is, but the behavioral profile is substantially conveyed.

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

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

Front-loads the high-level action, then lists the pipeline steps, then tucks the parameter semantics at the end. Dense but no filler; the trailing parameter notes are slightly list-like but each earns its place.

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

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

An output schema exists, so the return format need not be fully described, and the description still summarizes the change report. For a complex, side-effecting sync orchestration with no annotations, coverage is solid, with auth prerequisites being the main missing piece.

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

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

Schema description coverage is 0% and there are no enums, so the description must compensate — and it does: asignatura is explained as partial name or id (empty = all), and forzar as re-download everything. Both parameters gain meaning unavailable in the bare schema, though the forzar explanation is terse.

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

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

Names a specific verb+resource and enumerates the full scope: downloads/updates materials, teaching guide, deadlines and announcements, then extracts, indexes, regenerates and reports. An agent can distinguish this sync/orchestration tool from read-oriented siblings like uned_materiales, uned_anuncios or uned_eventos without opening any schema.

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

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

Usage is implied by the sync semantics and the note that asignatura empty means 'all', which is useful scoping guidance. But it never states when to prefer this over alternatives such as uned_materiales or uned_anuncios, nor any prerequisites (e.g. needing login first), so the agent must infer the routing itself.

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