update_activity_completion_status_manually

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the mutation is known. The description adds the scope 'módulo propio confirmado' (confirmed own module), which is useful context beyond the annotations. However, it does not disclose the significance of confirmation_token, the exact side effects, or whether the action is reversible. The additional context is minimal but non-contradictory.

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 a single, front-loaded sentence with no filler words. It efficiently conveys the primary action without redundancy. However, given the lack of parameter explanations, the brevity is achieved at the cost of essential information, which keeps it from a perfect score.

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 write operation with destructive implications, four required parameters, and no output schema, the description is too skeletal. It does not explain what confirmation_token is, how to obtain it, what the expected result is, or any prerequisites. The annotations signal destructiveness but not the full operational context. The description leaves significant ambiguity for an agent trying to call the tool correctly.

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 full burden of explaining parameters. It does not mention any of the four parameters (cmid, completed, course_id, confirmation_token) or their roles. While parameter names are somewhat self-explanatory, the description fails to clarify the meaning of confirmation_token or the relationship between cmid and course_id. This is a major gap for a tool with all required parameters.

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 ('Marca o desmarca') and a specific resource ('la finalización manual del módulo propio confirmado'), making the tool's core function clear. It distinguishes from preview_update_activity_completion_status_manually implicitly by being the actual update rather than a preview, though it doesn't explicitly name the sibling. It is not a tautology and is specific enough for an agent to understand the intended action.

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 no guidance on when to use this tool versus alternatives. It does not mention the preview sibling (preview_update_activity_completion_status_manually) or any conditions that would select this tool over others. There is no indication that a preview step might be advisable or that this tool is for confirmed own modules only. An agent has to infer usage from the schema and annotations, which are insufficient.

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