List Subcolumns

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the burden. The description adds genuine behavioral value beyond annotations: the verbosity-dependent quirk (column_id set to parent at verbosity=max), the normalized return shape via simplifyColumn, and the empty-array edge case. No contradiction with annotations; the read-only framing is consistent.

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?

Four sentences, each earning its place: core action, concept example, behavioral quirk, and sourcing hint. The primary action is front-loaded, and there is no filler or repetition of schema content. The simplifyColumn reference is mild internal jargon but informative rather than padding.

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 simple, well-annotated list tool with 100% schema coverage, the description is nearly complete. It compensates for the absent output schema by describing the return shape (standard column shape, empty array behavior, column_id quirk at max verbosity). No critical information an agent needs to call it correctly appears to be 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 100%, so the baseline is 3 even without description-level param info. Both parameters are already fully documented in the schema, including the columnId sourcing hint. The description restates that hint and references verbosity=max behaviorally, but adds no syntax or format detail beyond what the schema provides.

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 the verb+resource pair directly ('List subcolumns of a parent column') and grounds the concept with a concrete example ('In Progress' → 'Implementation' / 'Review'). The conceptual explanation separates subcolumns from sibling column/lane tools, and the explicit reference to kaiten_list_columns anchors its place in the API without needing to name a sibling it is not.

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?

Provides sourcing guidance ('columnId from kaiten_list_columns') and expectation-setting ('Empty array if the column has no subcolumns — most boards don't use them'), which helps an agent decide when results will be meaningful. However, it never explicitly states when to prefer this over sibling tools like kaiten_list_columns or kaiten_list_lanes, leaving the routing implicit rather than explicit.

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