move_account

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

No annotations are provided, so the description carries full burden. It's clearly a mutation tool, and the description is honest about the operation. However, it doesn't disclose edge-case behaviors such as what happens to the account's transactions, whether the account GUID changes, child accounts' paths, or any hierarchy-cycle restrictions. For a mutation with no annotations, more behavioral disclosure is warranted.

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 description is compact and front-loaded with a clear one-sentence purpose, followed by a scannable Args list documenting accepted reference formats. No wasted words. Could argue for slightly more content on behavior, but as written it's tight and efficient.

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?

Has an output schema that presumably documents return value, so description needn't cover that. With 2 params and no annotations, description does reasonably document parameter formats. However, it leaves open important operational questions for a hierarchy-mutation tool (cycle prevention, descendant reparenting, transaction preservation) that reduce completeness for safe invocation.

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 0%, so the description must compensate. The Args section documents both parameter formats (full path, %short GUID, or full 32-char GUID), which is genuinely useful and adds meaning beyond the bare schema field names. However, it doesn't clarify semantics like whether 'name' is the current path before or after move, and doesn't explain expected new_parent format beyond reuse of the same reference formats.

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 clearly states the verb (Move) + resource (account) + effect (to a new parent in the hierarchy). It's distinct from update_account and delete_account siblings. However, it doesn't explicitly state scope limits like whether the move preserves children or affects descendant accounts.

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?

The description establishes clear context (moving accounts in hierarchy) and documents the two reference formats for both parameters in the Args block, which aids selection. However, it provides no when-not-to-use guidance or alternatives, and doesn't mention prerequisites (e.g., whether target parent must exist, whether moving to a descendant is prohibited).

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