BearQ: Stop Workflow Run

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

The description says the tool 'Cancels a workflow run' and returns 'cancelled: true', i.e. it changes the run's state on the server, while annotations declare readOnlyHint=true. An agent trusting the annotation would treat this as a safe non-mutating read. The error conditions and return shape are genuinely useful, but the read-only claim is directly at odds with the described effect.

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?

Two tight sentences: effect and return shape first, failure conditions second, with zero filler. The trailing 'Toolset' and 'Parameters' blocks duplicate structured data but are clearly demarcated metadata rather than buried prose.

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?

With no output schema, the description correctly covers the return shape ({ runId, cancelled: true }) and the failure modes, which is what an agent needs for this one-parameter tool. The only real gap is that it never reconciles its mutating effect with the read-only annotation, leaving the safety profile ambiguous.

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 100% and the single runId property is already documented in the schema with the identical phrasing 'BearQ workflow run ID to cancel.' The description repeats rather than enriches it (no guidance on where to obtain a runId, e.g. from bearq_list_workflows or bearq_get_workflow_run), so it sits at the baseline for a fully documented 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 ('Cancels a workflow run that is in flight') and immediately clarifies the scope ('in flight'), which separates it from bearq_get_workflow_run (read) and bearq_run_workflow (start). An agent can distinguish it from every sibling without opening the schema.

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?

Names a concrete precondition and negative case: it 'Fails with an error when the run has already finished or does not exist,' which tells the agent when the tool is applicable versus pointless. It stops short of routing to an explicit alternative (e.g. bearq_get_workflow_run to check status first, or bearq_stop_task for tasks rather than runs), so it is clear context without exclusions.

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