agent_backups_write

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds substantive detail the annotations cannot convey: which action overwrites the whole agent (restore) versus only the prompt (revert_prompt), that create captures the agent 'as it is now', and that set_prompt_caching affects cost/latency. It stops short of stating permissions, reversibility of a restore, or what a successful response returns.

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 warning about destructive overwrites is front-loaded, followed by a compact pipe-delimited action catalogue — no filler sentences. The single run-on caution sentence is dense but every clause carries distinct operational meaning.

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?

For a 6-parameter, destructive, no-output-schema tool, the description covers action semantics, prerequisites, ID sources, and user-confirmation requirements. The only omission is the 'mode' parameter's relevance to this tool's responses, which is a minor 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?

Schema coverage is 67%, and the description compensates well for the undocumented action and agentId fields by mapping each action to its required ID (backupId for restore, snapshotId for revert_prompt, enabled for set_prompt_caching). The one gap is 'mode', which is documented only in the schema and never mentioned in the description.

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 opening line states a specific verb pair and resource ('Back up or roll back an agent') and then enumerates all four actions with one-line summaries. It also differentiates from siblings by naming update_agent as the tool whose edits precede a backup and pointing to agent_backups_read / prompt_history as the sources of the required IDs.

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?

It gives explicit sequencing guidance ('Take a backup BEFORE large edits with update_agent') and an explicit caution for the destructive actions ('confirm with the user and create a backup first'). The action list tells the agent exactly which action to pick for each goal, with no reliance on inference.

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