Change a Trello card's position within its current list using top, bottom, or a numeric position; use card_move instead when changing lists or boards.
Use when changing only a card's position within its current list; use card_move when changing lists or boards too.
| Name | Required | Description | Default |
|---|---|---|---|
| pos | Yes | New position for the card within its current or destination list. | |
| cardId | Yes | Trello card id, short link, or Trello card URL. |
Changes observed during successful MCP inspections.
v1.0.4Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It clarifies scope (current list only) and the alternative, but does not state permissions, reversibility, side effects on other cards, or response behavior; for a mutation tool this is a significant gap.
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 compact sentence, front-loaded with the when-to-use condition and immediately followed by the alternative. No wasted text.
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?
The tool is simple with two well-defined required parameters, and the description adequately covers selection versus its sibling. It still lacks mutation behavior and return context, but given the simple schema and no output schema, it is mostly complete.
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 coverage is 100%, so cardId and pos are already documented, including the top/bottom/number position values. The description adds no parameter-specific detail beyond the current-list scope already implied.
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 names the action (changing a card's position) and scopes it to the current list, while explicitly distinguishing it from card_move for cross-list or cross-board moves. An agent can identify the tool without opening the schema.
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 an explicit when-to-use rule and names the alternative card_move for the opposite case. This directly routes the agent between the two sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.