Specify Kanban task

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

The description discloses that it 'runs the triage specifier auxiliary LLM' (an important side effect — LLM invocation, cost/latency implications) and states it 'writes redacted receipts' (a side effect beyond the core operation). Annotations provide readOnlyHint=false, openWorldHint=true, and it's not destructive/idempotent, but the description adds meaningful behavioral detail about executing a nested LLM and writing receipts.

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 dense sentence that packs the endpoint type, operation, mechanism, effect, and a side effect (receipts). Efficient and informative, though slightly jargon-heavy ('triage specifier auxiliary LLM', 'redacted receipts' could use a touch of expansion). No wasted words.

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 a good description, 100% parameter coverage, an output schema present, and only 2 params, this is fairly complete. The description covers the mechanism, the state transition, and a notable side effect. Minor gaps: no mention of what 'receipts' are used for or potential failure cases when the auxiliary LLM output is low quality, but these aren't blocking.

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% — both id (task id format) and board (slug, default) are documented in the schema. The description mentions the endpoint path but adds no parameter semantics beyond what the schema already provides, which meets the baseline for full coverage.

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 the verb (specify/promote), resource (Kanban triage task), and key effect (flesh out a triage task and promote it to todo). It distinguishes from sibling hermes_kanban_task_create/update/decompose by describing the specific 'specify' pathway through the triage specifier LLM. However, it doesn't explicitly name a differentiated sibling function.

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 implies this is for triage tasks being promoted to todo via an auxiliary LLM, which gives some context. It does not state when NOT to use it versus task_update or task_decompose, nor when one would choose this over alternatives. The context is implied rather than explicit.

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