guardar_cedulario

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the side effect of replacing the official cedulario in index, plan, and simulations, and explains the 'borrar: true' option to revert to official. It also mentions confirming transcription with the student, which is a behavioral safeguard. It does not mention permissions, failure modes, or return values, but covers the most critical 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?

The description is three sentences, efficient and front-loaded with the core action, then side effects, then parameter specifics. Every sentence adds value: the first states the purpose and impact, the second details the structure, and the third gives procedural and revert guidance. 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?

Given there is no output schema and the tool has significant side effects, the description covers the main aspects: what it does, side effects, how to obtain 'temas' ids, the confirmation step, and the revert option. It does not mention error scenarios, but for a save operation with clear side effects and a revert mechanism, it is adequately complete.

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

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

Schema description coverage is only 25% (only 'fuente' has a description). The description compensates significantly by explaining the structure of the 'cedulas' array: each cédula has número, tema, contenido literal, and 'temas' which are ids of the syllabus items to look up with buscar_temario. It also explains the 'borrar' parameter. This adds essential meaning beyond the raw schema for the most complex parameter.

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

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

The description clearly states the tool's purpose: saving a student's cedulario for a subject (rama), with explicit mention that it replaces the official version in index, plan, and mock exams. The verb 'Guarda' and resource 'cedulario' are specific, and the description distinguishes it from other tools by focusing on the save/update action rather than listing or reading.

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 provides context on when to use it (when transcribing an uploaded document) and gives a procedural instruction: confirm with the student before saving. It also references buscar_temario for finding the 'temas' ids, implying the need to use that tool beforehand. However, it does not explicitly state when NOT to use it or compare directly with alternatives like guardar_material, though the purpose is clear enough.

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