Cancel a MELRA task

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context the annotations cannot convey: cancellation is 'cooperative' (a request rather than a forced kill) and applies only to running or pending tasks. It stops short of describing post-cancel state transition or returned status.

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?

One short, front-loaded sentence with no filler – the verb and scope appear immediately. It is efficient rather than excessive, though its brevity is close to under-specification for the usage question above.

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 single-parameter, well-annotated mutation the definition is close to sufficient, but it omits the task-versus-workflow-routing decision that the sibling list makes necessary, and says nothing about permissions or the result of a successful cancellation.

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?

There is a single parameter with 0% schema description coverage, so the description technically carries the full burden, but 'taskId' is self-documenting by name. The description adds nothing about the UUID format or the semantics of the identifier, leaving any added value to the schema's pattern alone.

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 names a specific verb (cancel) and resource (task), and the adverb 'cooperatively' plus the state qualifier 'running or pending' sharpen the scope beyond the bare title. It does not, however, distinguish itself from the sibling melra_workflow_cancel, leaving an agent to guess whether task-level and workflow-level cancellation are the same operation.

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 only usage signal is the implicit one embedded in 'running or pending' – there is no explicit when-to-use guidance, no statement about what happens if the task is already finished, and no mention of the alternative melra_workflow_cancel despite it being an obvious sibling for the cancellation use case.

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