restore_backup

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

With no annotations, the description carries the full behavioral burden. It does disclose two important traits: the operation is atomic, and the target is destructively overwritten. However it is silent on whether the backup file is consumed or left in place, whether a pre-restore snapshot is taken, permission/auth requirements, and failure/rollback behavior.

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?

Front-loaded one-line summary carries the essential action and the atomicity constraint; the Args block is compact and adds direction semantics rather than padding. Slightly machine-generated in layout and the param list partly duplicates the schema, keeping it out of 5 territory.

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?

Return values need not be explained since an output schema exists, and both parameters are meaningfully described. But for a destructive, unannotated mutation tool, the description omits prerequisites, side effects on the backup file, and failure semantics an agent would need before invoking it.

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 schema offers only bare 'Backup Path'/'Target Path' titles. The description compensates by giving direction (restore *from* vs. overwrite) and expected file types (.bak vs. .xlsx/.xlsm), which is real meaning the schema lacks. It stops short of documenting path format or relative-vs-absolute resolution.

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 precise verb and resource ('Restore a backup file over a target workbook'), plus the atomicity guarantee. No sibling tool performs a restore or backup operation, so an agent can immediately distinguish this from workhorse siblings like write_cells or create_workbook.

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 says what the tool does but never states when to reach for it, what precondition must hold (e.g. target file must already exist, backup must have been produced by this server), or what alternative to use for non-restore recovery. Nothing about when-not-to-use is offered.

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