aiworkhub_task_auto_pickup_dryrun

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

Annotations already declare readOnlyHint=true, but the description adds real value: it reports the candidate task_id, a compact card, and filtering counts; it avoids mutating the parent queue and the write gate; and it uses only the read-only export path. It does not describe error behavior or permission requirements beyond the write gate, keeping it shy of a 5.

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 safety guarantee is front-loaded in the first line, and the paragraph is generally tight. The closing sentences repeat the no-write-path idea ('provides no alternate write path and cannot bypass that gate') slightly redundantly, but the emphasis is defensible for a gated operation.

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 an output schema present, the description needn't document return values, yet it still names the key outputs (candidate task_id, compact card, counts). Annotations cover safety. The only gap is parameter behavior for the nullable topic, which an agent might need to call 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% for both parameters, so the description must carry the burden. It implies that 'runner' selects the runner and 'topic' filters by topic via 'runner/topic filtering counts', but it never explains accepted values, whether topic is optional (it is nullable/default null), or what omitting topic does. It adds some meaning but leaves the schema gap partially unfilled.

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 ('preview which task auto_pickup WOULD claim for a runner/topic') and explicitly names the write sibling it is not (aiworkhub_task_auto_pickup). An agent can distinguish this dry-run tool from the real claim path without opening either 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 the alternative write path, explains that it is gated behind AIWORKHUB_ALLOW_WRITES, and clarifies this preview offers no alternate write path. That gives clear context for choosing this tool over the real claim, though it never states an explicit 'use when' condition such as 'call before claiming' or 'use to debug runner/topic filtering'.

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