Move up to 50 placements sequentially, returning per-item results and partial success while stopping on authentication or permission errors.
Move up to 50 placements sequentially. Each move is independent; returns per-item results and partial success, without cross-request atomicity. Stops on authentication or permission errors.
| Name | Required | Description | Default |
|---|---|---|---|
| moves | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantive traits beyond the annotations: sequential execution, per-item results, partial success, no cross-request atomicity, and halting on authentication or permission errors. These are exactly the failure-mode and consistency facts an agent needs before issuing a bulk mutation, and nothing contradicts the annotation set.
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 short sentences, front-loaded with the operation and size bound, then the concurrency/atomicity contract. No filler, and every clause carries load-bearing information.
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?
Covers the batch-level contract well enough for a safe call, but with no output schema and zero parameter documentation, the description should at least sketch what a 'per-item result' contains and what the item fields mean. For a mutation accepting a nested structure, that gap is material.
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 carry the burden, but it only restates the batch ceiling of 50. The nested item fields — placementId, parentPlacementId, and especially position with its default of 0 — are left entirely unexplained in both places, and position semantics (ordering vs. root-level) are genuinely ambiguous.
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 and resource ('Move ... placements') plus the batch bound of 50, so the agent knows this is a bulk relocation operation. It never mentions the sibling move_placement (singular), so the agent must infer the single-vs-batch split on its own.
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?
'Move up to 50 placements sequentially' implies this is the batch path, but the description never names move_placement as the alternative for a single move, nor states any exclusion or prerequisite. Usage is inferable rather than explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.