actualizar-perfil

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

With no annotations, the description carries the full burden and does well: it discloses the dry-run default, that writes go through a backup in ~/.magneto/respaldos/, and critically that only ids listed in eliminar_ids are deleted. What is not stated is what the response looks like beyond a 'plan' or what happens if a section is empty.

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 dense sentences, front-loaded with the dry-run behavior before the write mode. Every clause carries operational value ('antes → después', backup path, delete scoping). Slightly packed with Spanish technical detail, 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?

For a 3-param, no-annotation mutation tool, this covers the essential gaps: dry-run default, safe-write backup, and delete scoping. The lack of an output schema is partly offset by describing the plan as 'antes → después', though more on the save response could help.

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 67% (seccion enum has no schema description), so the description meaningfully compensates: 'aplicar=true respalda... y guarda' explains semantics beyond the type, and 'Solo borra los ids indicados en eliminar_ids' clarifies the delete scope. Useful added meaning over schema.

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: 'Actualiza una sección de la hoja de vida desde el perfil maestro'. An agent can infer this derives a CV section from the master profile. It does not name a specific sibling for contrast, but the source relationship to perfil maestro implies a distinction from guardar-perfil-maestro/construir-perfil-maestro.

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 explains the two modes explicitly: without 'aplicar' it returns a plan to show the user, and with aplicar=true it backs up and saves after user confirmation. The 'para mostrarlo al usuario' and 'tras la confirmación del usuario' give clear workflow conditions, but no sibling alternatives are named.

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