Reorder a list

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

With no annotations, the description carries the full burden and does substantial work: it reveals a non-obvious constraint that both neighbours must be lists on the same board in their current left-to-right order, and that archived/closed lists still occupy a slot. It does not disclose what happens on invalid neighbour IDs, permission requirements, or side effects such as activity logging.

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?

Three sentences, front-loaded with the action and then the two parameter definitions, closing with a constraint. Every clause carries load-bearing information, and the LEFT/RIGHT framing is far clearer than naming the parameters again.

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 three-parameter mutation tool with no annotations and no output schema, the definition supplies the ordering model, the edge-case nulls, the same-board constraint, and a pointer to the tool that yields the current order. Only error behaviour on invalid neighbours is left unstated.

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 define all three parameters and it effectively does: beforeId as the list immediately LEFT, afterId as immediately RIGHT, null semantics for the board edges, and the same-board/current-order constraint. The required `id` is implicitly the list being moved, which the opening sentence establishes.

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?

"Move a list (column) to a new position on its board" gives a specific verb plus resource and disambiguates the term "list" as a kanban column. It is clearly distinct from kanbini_move_card by resource type, though it never explicitly separates itself from kanbini_update_list (rename/edit) which an agent could confuse with repositioning.

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?

It tells the agent exactly how to use the two anchor parameters, including the edge case that omitting or passing null targets the far left or far right. It also points to kanbini_get_board as the source of the current ordering. No explicit "don't use this when" guidance is given, but the operating context is clear.

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