move_message_to_folder

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

Annotations indicate readOnlyHint=false and destructiveHint=false, which the description doesn't contradict. The description adds context by specifying allowed message types (voicememo, prerecorded), which is useful behavioral information not covered by annotations. However, it lacks details on permissions, error handling, or side effects beyond the move operation.

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 front-loaded with the core action and includes necessary constraints in two sentences. It avoids unnecessary details, but could be slightly more structured by separating the move action from the constraints for clarity.

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?

Given the tool's complexity (mutation with constraints), annotations cover safety, and schema covers parameters well. However, without an output schema, the description doesn't explain return values or success/failure behavior. It adequately covers the move operation but lacks completeness for error cases or result interpretation.

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 100%, so the schema already documents all parameters. The description adds minimal semantics by reiterating the allowed message types for 'message_id', but this is redundant with the schema. No additional parameter meaning or usage context is provided beyond what's in the structured data.

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' and resource 'message to a folder by its ID', specifying the action and target. It distinguishes from siblings like 'move_folder' by focusing on messages rather than folders. However, it doesn't explicitly differentiate from other message-related tools like 'create_conversation_message' beyond the move action.

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 implies usage by stating 'Only allowed to move messages of type: voicememo,prerecorded', which provides some context for when to use this tool. However, it doesn't explicitly mention when not to use it or name alternatives among siblings, such as when dealing with other message types or operations.

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