rca_graph_restore_version

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

Despite destructiveHint=true already being declared in annotations, the description adds substantial behavioral context: the restore is itself snapshotted and undoable by restoring forward again, confirm=false yields an 'aborted' error, and the graph_versioning feature is required. It also discloses what the operation returns (graph_id, restored_from, node/edge counts). No contradiction with annotations.

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 description is front-loaded with the core purpose in the first sentence, followed by behavioral nuance, requirements, and a structured Args/Returns breakdown. It is longer than strictly necessary — the Args list partially recapitulates the schema — but every section earns its place by adding error semantics or return-shape information.

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 destructive version-restore operation, the description covers prerequisites, sequencing (list_versions first), the confirmation gate, failure mode, undoability, and the return payload, which is ample given an output schema exists. Minor gaps remain: the required token's role and client_id default are left to the schema, and no limits on which historical versions can be restored are stated.

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?

With schema description coverage reported at 0%, the description compensates meaningfully for three of five parameters: graph_id (target), version_id (tied to rca_graph_list_versions), and confirm (must be true or an 'aborted' error is returned). It omits token and client_id, though those are self-evident in the schema's own descriptions and default value.

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 states a specific verb and resource — 'Restore a causal graph to a specific historical version' — and sharpens the scope with the snapshot semantics ('creates a new current state from the version snapshot... the version history itself is preserved'). This clearly distinguishes restore from siblings like rca_graph_get, rca_graph_delete, and rca_graph_list_versions, especially by naming list_versions as the source of version_id.

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 gives clear operational context: 'Use rca_graph_list_versions first to find a version_id', plus the confirm=true gate and the Starter+ feature prerequisite. It does not explicitly state when-not-to-use or contrast against a competing tool, but for a version-restore operation the sequencing and prerequisites are concrete and actionable.

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