mark_course_self_completed

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 agent knows this is a mutating, non-idempotent operation. The description adds minimal behavioral context beyond that, merely implying a confirmation mechanism ('confirmed by Moodle and the user') without explaining side effects, what happens on success or failure, or what the confirmation token validates. It does not contradict annotations but adds little value.

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 very short (one sentence), which is concise, but it is underspecified—it does not include enough content to be considered appropriately sized. Information is not front-loaded because there is almost no information to load. Brevity is not a virtue here when critical details are missing.

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 mutation tool with two required parameters, no output schema, and zero schema coverage, the description is grossly incomplete. It fails to explain prerequisites, the confirmation flow, error behavior, or any postconditions. Without the description, an agent would have no idea how to correctly invoke this tool or interpret its result.

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 by explaining the parameters. It does not describe what course_id represents or what confirmation_token is, nor how they relate to the confirmation mechanism mentioned. The schema provides only names and types, leaving both parameters completely unexplained.

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 verb ('marks as completed') and a resource ('course'), but the target is ambiguous—'course propio' is vague and the phrase 'confirmed by Moodle and the user' is unclear. It does not clearly differentiate from the sibling tool update_activity_completion_status_manually, which also marks completion. The purpose is more than a tautology but lacks specific scope.

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?

No usage guidance is provided. There is no mention of when to use this tool versus the preview sibling preview_mark_course_self_completed or the related update_activity_completion_status_manually. The description does not state prerequisites, conditions, or when it is appropriate to call this mutation.

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