backup_restore

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that the restore runs asynchronously, which is critical behavioral info, and prominently warns about purgeExisting deleting all current data. This is a destructive operation (implied) and the warning is clear. It doesn't mention return value or whether restore overwrites rather than merges, but the async note and destructive warning are substantial disclosures.

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 sentences, front-loaded with the core action, then async behavior and status companion, then a clear warning. The warning is appropriately placed at the end as a caution. No wasted words, though the warning could arguably be more prominent given the destructive potential.

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 no output schema and no annotations, the description does well to disclose the async behavior, the status-check companion, and the destructive purgeExisting consequence. For a moderately complex tool (3 params, 1 destructive flag), this covers the essential operational contract. It could mention what happens to the ZIP after upload or whether a companyId override is required, but the core completeness is adequate.

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 all three parameters are documented in the schema itself, giving a baseline of 3. However, the description adds meaning only to purgeExisting (via the warning) and largely ignores filePath and companyId. The warning adds genuine semantic value for one parameter, but the other two receive no additional context beyond schema. Since the description overlaps heavily with schema without adding much, this sits slightly below baseline.

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 tool uploads a backup ZIP to restore company data, with a specific verb+resource. It distinguishes from siblings like backup_create, backup_status, backup_download, and backup_restore_status by clarifying this is the restore action. Could be slightly more explicit about the restore being the inverse of backup_create, but the purpose is clear.

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 clearly identifies when to use this tool (to restore company data from a backup) and references backup_restore_status for checking progress, which orients the agent on the companion tools. It doesn't explicitly state when NOT to use it or name alternatives, but it does mention the async pattern and points to the status-check sibling, providing reasonable usage context.

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