revert_device_revision

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

With no annotations, the description carries the full burden and does so: it discloses the FMG_REVERT_SAFETY='strict' gate, that confirm=True is mandatory unless the env var is disabled, the exact blast radius (stored device DB only, not the device), and the honest caveat that it is not live-tested but mirrors the documented /deployment/revert request shape. This is exactly the context annotations would otherwise provide.

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 with the core action and safety of scope, then usage, then args. A few passages (the client.py reference, the not-live-tested aside) are slightly verbose, but each still conveys risk information an agent would want before a consequential write.

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?

A consequential mutation tool with no annotations and a 0%-coverage schema is fully covered: what it mutates, what it does not, how to propagate the change, the safety gate, the prerequisite revision history, and the return shape. Nothing needed to invoke it correctly is missing.

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%, yet all three parameters are explained with meaning beyond their types: device is the managed device name, revision points the agent to list_device_revisions for valid values, and confirm's interaction with FMG_REVERT_SAFETY (mandatory when strict, ignored when disabled) is spelled out.

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 specific verb+resource ('Revert a device's device DB to a past revision') and immediately scopes it: only FortiManager's stored copy is rewritten, the live FortiGate is untouched. This clearly distinguishes it from sibling revert_adom_revision, which it names by analogy.

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?

Explicitly tells the agent what to do after reverting (preview_install then install_device_settings), states the prerequisite that the device must have revision history (pointing at list_device_revisions), and states that confirm=True is required under the default safety mode. When-to-use and prerequisites are both covered.

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