Skip to main content
Glama

Undo or Redo Rack State Mutation

undo_redo

Revert the latest rack mutation or reapply a reverted change to rack.yaml atomically; use undo to roll back unintended batches and redo immediately after an undo.

Instructions

Traverse the per-project in-memory history ring buffer of up to 50 snapshots to revert the latest rack mutation or reapply a reverted mutation, updating rack.yaml atomically. Setting 'action' to 'undo' steps backward across rack-state mutations—excluding catalog-only define_custom_blueprint calls and read-only tools—and pushes the displaced state onto the redo stack, whereas 'redo' is available only immediately after 'undo' because any new rack mutation flushes the redo stack. Calling either action when its target stack is empty is a safe no-op returning applied=false without throwing. Use to roll back an unintended batch change or accidental init_rack reset; use modify_equipment or disconnect_cables instead to edit specific items without reverting intermediate steps.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "undo_redo"
  }
}

Input Schema

NameRequiredDescriptionDefault
actionYesHistory traversal direction: "undo" reverts the most recent state mutation, "redo" reapplies a reverted mutation.

Output Schema

NameRequiredDescriptionDefault
dataYesUndo/redo history traversal result payload.
issuesYesStructured diagnostic findings (ERROR, WARNING, INFO) with actionable remediation_suggestions.
statusYesDeterministic execution outcome: "VALID" when the operation succeeded with 0 validation errors; "INVALID" when precondition or engineering validation errors are present in issues[].
summaryYesConcise human- and agent-readable summary of the tool result and validation status.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.4.10
    • changedInput schema / properties / action / description
      Previous value: -"History traversal direction: undo reverts the previous mutation, redo reapplies it."New value: +"History traversal direction: \"undo\" reverts the most recent state mutation, \"redo\" reapplies a reverted mutation."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "data": {
      +      "additionalProperties": {},
      +      "description": "Undo/redo history traversal result payload.",
      +      "properties": {
      +        "action": {
      +          "description": "History traversal direction that was requested.",
      +          "enum": [
      +            "undo",
      +            "redo"
      +          ],
      +          "type": "string"
      +        },
      +        "applied": {
      +          "description": "True if a history snapshot was restored; false if the target history stack was empty.",
      +          "type": "boolean"
      +        },
      +        "ascii_elevation": {
      +          "description": "Updated ASCII front/rear rack elevation diagram after history traversal.",
      +          "type": "string"
      +        },
      +        "redo_available": {
      +          "description": "Number of remaining redo snapshots available in memory.",
      +          "maximum": 9007199254740991,
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "undo_available": {
      +          "description": "Number of remaining undo snapshots available in memory.",
      +          "maximum": 9007199254740991,
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "validation": {
      +          "additionalProperties": false,
      +          "description": "Updated 5-stage validation report for the restored rack state.",
      +          "properties": {
      +            "error_count": {
      +              "description": "Total number of blocking ERROR diagnostics.",
      +              "maximum": 9007199254740991,
      +              "minimum": 0,
      +              "type": "integer"
      +            },
      +            "is_valid": {
      +              "description": "True when zero ERROR-level diagnostic issues exist.",
      +              "type": "boolean"
      +            },
      +            "issues": {
      +              "description": "List of all detected ERROR, WARNING, and INFO diagnostic issues.",
      +              "items": {
      +                "additionalProperties": false,
      +                "description": "Single validation finding with deterministic self-correction feedback.",
      +                "properties": {
      +                  "affected_instances": {
      +                    "description": "Device instance IDs involved in this diagnostic issue.",
      +                    "items": {
      +                      "type": "string"
      +                    },
      +                    "type": "array"
      +                  },
      +                  "code": {
      +                    "description": "Machine-readable deterministic validation diagnostic code.",
      +                    "enum": [
      +                      "CHASSIS_COLLISION",
      +                      "PLUG_CLEARANCE_COLLISION",
      +                      "FRONT_DOOR_COLLISION",
      +                      "SLOT_DIMENSION_OVERFLOW",
      +                      "SLOT_INCOMPATIBLE",
      +                      "OUT_OF_RACK_BOUNDS",
      +                      "BLUEPRINT_NOT_FOUND",
      +                      "PORT_NOT_FOUND",
      +                      "PORT_ALREADY_OCCUPIED",
      +                      "CONNECTOR_INCOMPATIBLE",
      +                      "SIGNAL_PROTOCOL_INCOMPATIBLE",
      +                      "SPEED_MISMATCH",
      +                      "POE_BUDGET_EXCEEDED",
      +                      "POE_CLASS_EXCEEDED",
      +                      "UPS_OVERLOAD",
      +                      "UNPOWERED_DEVICE",
      +                      "TOP_HEAVY_RACK",
      +                      "NO_FRONT_TO_REAR_PORTAL",
      +                      "THERMAL_AIRFLOW_CONFLICT",
      +                      "THERMAL_HOTSPOT_STACKING",
      +                      "ACOUSTIC_NOISE_HIGH"
      +                    ],
      +                    "type": "string"
      +                  },
      +                  "message": {
      +                    "description": "Detailed engineering explanation with exact millimeter/watt figures.",
      +                    "type": "string"
      +                  },
      +                  "remediation_actions": {
      +                    "description": "Optional machine-actionable remediation descriptors.",
      +                    "items": {
      +                      "additionalProperties": false,
      +                      "description": "Structured self-correction action for autonomous agent remediation.",
      +                      "properties": {
      +                        "action_type": {
      +                          "description": "Recommended self-correction operation category.",
      +                          "enum": [
      +                            "move_device",
      +                            "change_cable_type",
      +                            "connect_power",
      +                            "disconnect_cable",
      +                            "redistribute_poe",
      +                            "add_portal_gap",
      +                            "change_rack_depth"
      +                          ],
      +                          "type": "string"
      +                        },
      +                        "description": {
      +                          "description": "Human- and agent-readable explanation of the remediation step.",
      +                          "type": "string"
      +                        },
      +                        "suggested_cable_type": {
      +                          "description": "Suggested replacement cable_type (e.g. angled plug or higher speed grade).",
      +                          "type": "string"
      +                        },
      +                        "suggested_face": {
      +                          "description": "Mounting or port face relative to the rack or chassis.",
      +                          "enum": [
      +                            "front",
      +                            "rear"
      +                          ],
      +                          "type": "string"
      +                        },
      +                        "suggested_u_positions": {
      +                          "description": "Candidate 1-indexed U positions that resolve the spatial conflict.",
      +                          "items": {
      +                            "exclusiveMinimum": 0,
      +                            "maximum": 9007199254740991,
      +                            "type": "integer"
      +                          },
      +                          "type": "array"
      +                        },
      +                        "target_cable_id": {
      +                          "description": "Cable connection cable_id targeted by this remediation action.",
      +                          "type": "string"
      +                        },
      +                        "target_instance_id": {
      +                          "description": "Device instance_id targeted by this remediation action.",
      +                          "type": "string"
      +                        }
      +                      },
      +                      "required": [
      +                        "action_type",
      +                        "description"
      +                      ],
      +                      "type": "object"
      +                    },
      +                    "type": "array"
      +                  },
      +                  "remediation_suggestions": {
      +                    "description": "Actionable self-correction instructions for the calling LLM agent.",
      +                    "items": {
      +                      "type": "string"
      +                    },
      +                    "minItems": 1,
      +                    "type": "array"
      +                  },
      +                  "severity": {
      +                    "description": "Severity level of the engineering constraint diagnostic.",
      +                    "enum": [
      +                      "ERROR",
      +                      "WARNING",
      +                      "INFO"
      +                    ],
      +                    "type": "string"
      +                  },
      +                  "stage": {
      +                    "description": "Validation pipeline stage (1..5) that produced this finding.",
      +                    "maximum": 5,
      +                    "minimum": 1,
      +                    "type": "integer"
      +                  },
      +                  "u_range": {
      +                    "additionalItems": false,
      +                    "description": "Inclusive [start_u, end_u] range where the issue occurs.",
      +                    "items": [
      +                      {
      +                        "maximum": 9007199254740991,
      +                        "minimum": -9007199254740991,
      +                        "type": "integer"
      +                      },
      +                      {
      +                        "maximum": 9007199254740991,
      +                        "minimum": -9007199254740991,
      +                        "type": "integer"
      +                      }
      +                    ],
      +                    "maxItems": 2,
      +                    "minItems": 2,
      +                    "type": "array"
      +                  }
      +                },
      +                "required": [
      +                  "code",
      +                  "severity",
      +                  "affected_instances",
      +                  "message",
      +                  "remediation_suggestions"
      +                ],
      +                "type": "object"
      +              },
      +              "type": "array"
      +            },
      +            "mechanical_summary": {
      +              "additionalProperties": false,
      +              "description": "Aggregated mechanical mass, center of gravity, thermal BTU/hr, and acoustic dB(A) metrics.",
      +              "properties": {
      +                "airflow_profile": {
      +                  "default": "uniform-passive",
      +                  "description": "Rack-wide thermal airflow regime classification.",
      +                  "enum": [
      +                    "uniform-front-to-rear",
      +                    "uniform-passive",
      +                    "hybrid-active-passive",
      +                    "mixed-conflict"
      +                  ],
      +                  "type": "string"
      +                },
      +                "available_portal_u_positions": {
      +                  "description": "1-indexed U slots that allow front-to-rear cable pass-through (open U or brush panel).",
      +                  "items": {
      +                    "maximum": 9007199254740991,
      +                    "minimum": -9007199254740991,
      +                    "type": "integer"
      +                  },
      +                  "type": "array"
      +                },
      +                "center_of_gravity_y_mm": {
      +                  "description": "Vertical Center of Gravity height from bottom of U1 in millimeters.",
      +                  "type": "number"
      +                },
      +                "combined_noise_db_a": {
      +                  "default": 0,
      +                  "description": "Logarithmic sum of acoustic noise emissions in dB(A) across all mounted devices.",
      +                  "type": "number"
      +                },
      +                "normalized_cog_y": {
      +                  "description": "Normalized vertical Center of Gravity ratio (0.0 = bottom, 1.0 = top; keep <= 0.50).",
      +                  "type": "number"
      +                },
      +                "total_thermal_btu_hr": {
      +                  "default": 0,
      +                  "description": "Total peak thermal dissipation in BTU/hr (1W = 3.41214 BTU/hr).",
      +                  "type": "number"
      +                },
      +                "total_weight_grams": {
      +                  "description": "Total mass of all mounted equipment in grams.",
      +                  "type": "number"
      +                }
      +              },
      +              "required": [
      +                "total_weight_grams",
      +                "center_of_gravity_y_mm",
      +                "normalized_cog_y",
      +                "available_portal_u_positions",
      +                "total_thermal_btu_hr",
      +                "combined_noise_db_a",
      +                "airflow_profile"
      +              ],
      +              "type": "object"
      +            },
      +            "power_summary": {
      +              "additionalProperties": false,
      +              "description": "Aggregated electrical and PoE DAG power analysis.",
      +              "properties": {
      +                "power_sources": {
      +                  "description": "Per-PDU and per-UPS electrical load breakdown.",
      +                  "items": {
      +                    "additionalProperties": false,
      +                    "description": "Load and capacity summary for a mounted PDU or UPS unit.",
      +                    "properties": {
      +                      "capacity_watts": {
      +                        "description": "Maximum rated output capacity of the power source in watts.",
      +                        "type": "number"
      +                      },
      +                      "role": {
      +                        "description": "Electrical source classification (\"pdu\" or \"ups\").",
      +                        "enum": [
      +                          "pdu",
      +                          "ups"
      +                        ],
      +                        "type": "string"
      +                      },
      +                      "source_instance_id": {
      +                        "description": "Instance ID of the upstream PDU or UPS unit.",
      +                        "type": "string"
      +                      },
      +                      "total_load_watts": {
      +                        "description": "Cumulative downstream system and PoE load in watts.",
      +                        "type": "number"
      +                      },
      +                      "utilization_percent": {
      +                        "description": "Percentage of rated watt capacity consumed (0..100+).",
      +                        "type": "number"
      +                      }
      +                    },
      +                    "required": [
      +                      "source_instance_id",
      +                      "role",
      +                      "capacity_watts",
      +                      "total_load_watts",
      +                      "utilization_percent"
      +                    ],
      +                    "type": "object"
      +                  },
      +                  "type": "array"
      +                },
      +                "pse_budgets": {
      +                  "description": "Per-switch PoE budget utilization breakdown.",
      +                  "items": {
      +                    "additionalProperties": false,
      +                    "description": "PoE budget utilization breakdown for a single PSE switch.",
      +                    "properties": {
      +                      "consumed_poe_watts": {
      +                        "description": "Total PoE power drawn by connected Powered Devices (PDs) in watts.",
      +                        "type": "number"
      +                      },
      +                      "downstream_devices": {
      +                        "description": "Instance or endpoint IDs of downstream PoE consumers powered by this switch.",
      +                        "items": {
      +                          "type": "string"
      +                        },
      +                        "type": "array"
      +                      },
      +                      "poe_budget_watts": {
      +                        "description": "Maximum rated PoE output power budget of the switch in watts.",
      +                        "type": "number"
      +                      },
      +                      "pse_instance_id": {
      +                        "description": "Instance ID of the PoE Power Sourcing Equipment (PSE) switch.",
      +                        "type": "string"
      +                      },
      +                      "remaining_poe_watts": {
      +                        "description": "Remaining available PoE power budget in watts (negative if overloaded).",
      +                        "type": "number"
      +                      }
      +                    },
      +                    "required": [
      +                      "pse_instance_id",
      +                      "poe_budget_watts",
      +                      "consumed_poe_watts",
      +                      "remaining_poe_watts",
      +                      "downstream_devices"
      +                    ],
      +                    "type": "object"
      +                  },
      +                  "type": "array"
      +                },
      +                "total_poe_watts": {
      +                  "description": "Total PoE power draw across all connected PoE devices and external drops in watts.",
      +                  "type": "number"
      +                },
      +                "total_system_watts": {
      +                  "description": "Total peak system power draw across all mounted equipment in watts.",
      +                  "type": "number"
      +                },
      +                "unpowered_active_instances": {
      +                  "description": "Active device instance IDs missing a valid AC, DC, USB-C, or PoE power input.",
      +                  "items": {
      +                    "type": "string"
      +                  },
      +                  "type": "array"
      +                }
      +              },
      +              "required": [
      +                "total_system_watts",
      +                "total_poe_watts",
      +                "pse_budgets",
      +                "power_sources",
      +                "unpowered_active_instances"
      +              ],
      +              "type": "object"
      +            },
      +            "status": {
      +              "description": "Overall rack validation state (\"VALID\" when error_count is 0).",
      +              "enum": [
      +                "VALID",
      +                "INVALID"
      +              ],
      +              "type": "string"
      +            },
      +            "warning_count": {
      +              "description": "Total number of non-blocking WARNING diagnostics.",
      +              "maximum": 9007199254740991,
      +              "minimum": 0,
      +              "type": "integer"
      +            }
      +          },
      +          "required": [
      +            "status",
      +            "is_valid",
      +            "error_count",
      +            "warning_count",
      +            "issues",
      +            "power_summary",
      +            "mechanical_summary"
      +          ],
      +          "type": "object"
      +        }
      +      },
      +      "required": [
      +        "action",
      +        "applied",
      +        "undo_available",
      +        "redo_available",
      +        "ascii_elevation",
      +        "validation"
      +      ],
      +      "type": "object"
      +    },
      +    "issues": {
      +      "description": "Structured diagnostic findings (ERROR, WARNING, INFO) with actionable remediation_suggestions.",
      +      "items": {
      +        "additionalProperties": false,
      +        "description": "Single validation finding with deterministic self-correction feedback.",
      +        "properties": {
      +          "affected_instances": {
      +            "description": "Device instance IDs involved in this diagnostic issue.",
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "code": {
      +            "description": "Machine-readable deterministic validation diagnostic code.",
      +            "enum": [
      +              "CHASSIS_COLLISION",
      +              "PLUG_CLEARANCE_COLLISION",
      +              "FRONT_DOOR_COLLISION",
      +              "SLOT_DIMENSION_OVERFLOW",
      +              "SLOT_INCOMPATIBLE",
      +              "OUT_OF_RACK_BOUNDS",
      +              "BLUEPRINT_NOT_FOUND",
      +              "PORT_NOT_FOUND",
      +              "PORT_ALREADY_OCCUPIED",
      +              "CONNECTOR_INCOMPATIBLE",
      +              "SIGNAL_PROTOCOL_INCOMPATIBLE",
      +              "SPEED_MISMATCH",
      +              "POE_BUDGET_EXCEEDED",
      +              "POE_CLASS_EXCEEDED",
      +              "UPS_OVERLOAD",
      +              "UNPOWERED_DEVICE",
      +              "TOP_HEAVY_RACK",
      +              "NO_FRONT_TO_REAR_PORTAL",
      +              "THERMAL_AIRFLOW_CONFLICT",
      +              "THERMAL_HOTSPOT_STACKING",
      +              "ACOUSTIC_NOISE_HIGH"
      +            ],
      +            "type": "string"
      +          },
      +          "message": {
      +            "description": "Detailed engineering explanation with exact millimeter/watt figures.",
      +            "type": "string"
      +          },
      +          "remediation_actions": {
      +            "description": "Optional machine-actionable remediation descriptors.",
      +            "items": {
      +              "additionalProperties": false,
      +              "description": "Structured self-correction action for autonomous agent remediation.",
      +              "properties": {
      +                "action_type": {
      +                  "description": "Recommended self-correction operation category.",
      +                  "enum": [
      +                    "move_device",
      +                    "change_cable_type",
      +                    "connect_power",
      +                    "disconnect_cable",
      +                    "redistribute_poe",
      +                    "add_portal_gap",
      +                    "change_rack_depth"
      +                  ],
      +                  "type": "string"
      +                },
      +                "description": {
      +                  "description": "Human- and agent-readable explanation of the remediation step.",
      +                  "type": "string"
      +                },
      +                "suggested_cable_type": {
      +                  "description": "Suggested replacement cable_type (e.g. angled plug or higher speed grade).",
      +                  "type": "string"
      +                },
      +                "suggested_face": {
      +                  "description": "Mounting or port face relative to the rack or chassis.",
      +                  "enum": [
      +                    "front",
      +                    "rear"
      +                  ],
      +                  "type": "string"
      +                },
      +                "suggested_u_positions": {
      +                  "description": "Candidate 1-indexed U positions that resolve the spatial conflict.",
      +                  "items": {
      +                    "exclusiveMinimum": 0,
      +                    "maximum": 9007199254740991,
      +                    "type": "integer"
      +                  },
      +                  "type": "array"
      +                },
      +                "target_cable_id": {
      +                  "description": "Cable connection cable_id targeted by this remediation action.",
      +                  "type": "string"
      +                },
      +                "target_instance_id": {
      +                  "description": "Device instance_id targeted by this remediation action.",
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "action_type",
      +                "description"
      +              ],
      +              "type": "object"
      +            },
      +            "type": "array"
      +          },
      +          "remediation_suggestions": {
      +            "description": "Actionable self-correction instructions for the calling LLM agent.",
      +            "items": {
      +              "type": "string"
      +            },
      +            "minItems": 1,
      +            "type": "array"
      +          },
      +          "severity": {
      +            "description": "Severity level of the engineering constraint diagnostic.",
      +            "enum": [
      +              "ERROR",
      +              "WARNING",
      +              "INFO"
      +            ],
      +            "type": "string"
      +          },
      +          "stage": {
      +            "description": "Validation pipeline stage (1..5) that produced this finding.",
      +            "maximum": 5,
      +            "minimum": 1,
      +            "type": "integer"
      +          },
      +          "u_range": {
      +            "additionalItems": false,
      +            "description": "Inclusive [start_u, end_u] range where the issue occurs.",
      +            "items": [
      +              {
      +                "maximum": 9007199254740991,
      +                "minimum": -9007199254740991,
      +                "type": "integer"
      +              },
      +              {
      +                "maximum": 9007199254740991,
      +                "minimum": -9007199254740991,
      +                "type": "integer"
      +              }
      +            ],
      +            "maxItems": 2,
      +            "minItems": 2,
      +            "type": "array"
      +          }
      +        },
      +        "required": [
      +          "code",
      +          "severity",
      +          "affected_instances",
      +          "message",
      +          "remediation_suggestions"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "status": {
      +      "description": "Deterministic execution outcome: \"VALID\" when the operation succeeded with 0 validation errors; \"INVALID\" when precondition or engineering validation errors are present in issues[].",
      +      "enum": [
      +        "VALID",
      +        "INVALID"
      +      ],
      +      "type": "string"
      +    },
      +    "summary": {
      +      "description": "Concise human- and agent-readable summary of the tool result and validation status.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "status",
      +    "summary",
      +    "data",
      +    "issues"
      +  ],
      +  "type": "object"
      +}
  2. Changed1 schema field changedv0.4.9
    • removedInput schema / additionalProperties
      Removed value: -false
  3. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Beyond annotations, the description discloses key behavioral traits: a ring buffer of up to 50 snapshots, atomic rack.yaml updates, redo-stack flushing on new mutations, and safe no-op behavior with applied=false when a stack is empty. These details materially help an agent understand the operation’s consequences and constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but tightly organized, with the core purpose front-loaded, followed by action semantics, edge cases, and alternatives. Every sentence contributes operational guidance for a complex history-traversal tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool’s complexity, single enum parameter, annotations, and existing output schema, the description is complete enough for correct invocation. It covers scope, exclusions, redo-stack constraints, no-op behavior, and when to prefer sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents the single action parameter with an enum and description, so baseline semantics are covered. The tool description adds useful operational meaning by explaining that undo traverses backward across rack-state mutations while redo reapplies a reverted mutation only when available.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: traversing a per-project in-memory history ring buffer to revert or reapply rack mutations. It clearly distinguishes this tool from siblings by describing undo/redo history traversal and naming alternatives like modify_equipment and disconnect_cables.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit conditions: use undo to roll back unintended batch changes or accidental init_rack resets, use redo only immediately after undo, and use modify_equipment or disconnect_cables instead for editing specific items without reverting intermediate steps. It also excludes catalog-only define_custom_blueprint calls and read-only tools from history traversal.

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