Restore OneDrive File Version

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

No annotations are provided, so the description carries the full burden. While 'restore' implies returning to a previous version, the description does not disclose that this overwrites the current version, is potentially irreversible, or requires specific permissions. This is a significant gap for a mutating operation, though the name gives a partial clue.

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 English sentence is concise and front-loaded, stating the action in one line. The additional Chinese intent list provides useful aliases for multilingual routing while remaining compact; no words are wasted.

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 (2 required params, no output schema), but because it performs a destructive restore and lacks annotations, the description should explain the effect on the current file and any prerequisites. The current description only states what it does, not the consequences, leaving a completeness 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?

The input schema already covers both parameters with clear descriptions (itemId and versionId from drive_list_versions), so the baseline is 3. The description adds no additional meaning beyond what the schema provides, merely referencing 'selected historical version' which maps to versionId.

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 uses a specific verb ('Restore') and resource ('historical version of a OneDrive file'), clearly distinguishing it from sibling tools like drive_list_versions or drive_download_file. The Chinese intent aliases reinforce routing without ambiguity.

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 provides no guidance on when to use this tool compared to alternatives like drive_list_versions or drive_download_file. It does not mention that a version must first be selected from drive_list_versions, nor any exclusions such as file types or permission requirements. This lack of usage context makes it difficult for an agent to decide between related drive operations.

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