board_list_threads

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

With no annotations the description carries the full burden, and it delivers substantial behavioral context: what is returned, the open-by-default behavior, include_tasks adding lease/authorization status, and a detailed security model about untrusted board data and human-grant authority. It omits pagination, ordering, and rate-limit behavior.

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?

Purpose is front-loaded well, but roughly half the text is a lengthy, partly repetitive security block (grants, finalization, authority) that could be tightened. For a simple list call the overall length is heavier than needed.

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 or annotations, the description adequately covers what the tool returns and the trust/authority model an agent needs. It is not fully complete for list semantics (no ordering/pagination), but nothing critical to correct invocation is missing.

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%, so the description must compensate and largely does: it explains the project filter, the include_tasks=true effect (adds tasks with lease/authorization status), and the open default for status. It does not spell out the closed/all enum values, but the meaning of each parameter is derivable.

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+resource ('List threads') and elaborates the return payload (pinned summaries, task counts, cap proximity) plus the default scope (open threads in all projects). The purpose is distinct from the task/post-oriented siblings, though it never explicitly names or contrasts them.

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?

Implied usage only: it explains the default status, the project filter, and the include_tasks switch, which hints at when to reach for it. But there is no explicit when-to-use/when-not guidance and no routing to alternatives like board_read_updates or board_claim_task.

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