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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is covered. The description adds genuinely new context beyond that: the exact order index is managed automatically, and the posted column does not publish. It stops short of stating permission or failure semantics.

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 core action is front-loaded in the first clause, followed by parameter guidance and a caution note. Every sentence carries information, though the placement/status details make it slightly dense rather than maximally tight.

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 mutation tool with no output schema, the description covers behavior (auto-managed ordering, non-publishing posted column) and the key parameters adequately, against annotations that already cover idempotency and destructiveness. The unexplained brandId parameter is the main remaining gap.

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?

With 0% schema description coverage, the description carries the load and mostly succeeds: it explains the placement enum's meaning and default ('default bottom'), restates the status enum, and states the at-least-one-of constraint. brandId, a fourth parameter, is left entirely unexplained in both schema and description.

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 a specific verb and resource ('Move a content card on the kanban board') and precisely scopes the operation to column change (status) and/or intra-column reordering. That scope cleanly distinguishes it from siblings like reorder_contents (order only) and update_content (field edits).

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 gives a clear invocation condition ('provide at least one of status or placement') and warns that the 'posted' column does not publish anything, which heads off misuse. However, it never names or routes the agent away from alternatives such as reorder_contents, so guidance is present but not comparative.

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