Skip to main content
Glama

Connect and Route Inter-Device Cables

connect_cables
Idempotent

Connect or update up to 128 power and network cables between mounted device ports in the active rack, with 3D routing, length bins, and PoE or power budget validation.

Instructions

Connect or update a batch of up to 128 power and network cables between mounted device ports in the active rack, computing 3D Catmull-Rom splines, commercial length bins, and PoE or power budgets. Each entry in 'cables[]' upserts in place by 'cable_id' while leaving all other cables and mounted equipment untouched, pushes a recoverable undo snapshot, and persists rack.yaml atomically; port, speed, PoE, or clearance violations return status 'INVALID' with remediation_suggestions instead of throwing. Within each cable, endpoint 'face' is required only on pass-through couplers such as patch panels exposing identical 'port_id' values on both faces, 'preferred_portal_u' applies only to front-to-rear transitions, and 'vlan_id' or 'ip_cidr' annotate logical network links. Use when both endpoint devices are mounted inside the rack; use disconnect_cables to remove cables, or plan_external_endpoints to terminate incoming building cable drops on a patch panel.

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": {
      "cables": "<cables>"
    },
    "name": "connect_cables"
  }
}

Input Schema

NameRequiredDescriptionDefault
cablesYesBatch of one or more cable connections to upsert by cable_id, route in 3D, and validate (max 128 per call).

Output Schema

NameRequiredDescriptionDefault
dataYesCable connection and 3D routing 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. Changed10 schema fields changedv0.5.0
    • changedInput schema / properties / cables / description
      Previous value: -"Batch of one or more cable connections to upsert by cable_id, route in 3D, and validate."New value: +"Batch of one or more cable connections to upsert by cable_id, route in 3D, and validate (max 128 per call)."
    • addedInput schema / properties / cables / items / properties / cable_id / maxLength
      Added value: +128
    • addedInput schema / properties / cables / items / properties / from / properties / instance_id / maxLength
      Added value: +100
    • addedInput schema / properties / cables / items / properties / from / properties / port_id / maxLength
      Added value: +128
    • addedInput schema / properties / cables / items / properties / ip_cidr / maxLength
      Added value: +64
    • addedInput schema / properties / cables / items / properties / label / maxLength
      Added value: +240
    • changedInput schema / properties / cables / items / properties / preferred_portal_u / maximum
      Previous value: -9007199254740991New value: +60
    • addedInput schema / properties / cables / items / properties / to / properties / instance_id / maxLength
      Added value: +100
    • addedInput schema / properties / cables / items / properties / to / properties / port_id / maxLength
      Added value: +128
    • addedInput schema / properties / cables / maxItems
      Added value: +128
  2. Changed2 schema fields changedv0.4.10
    • changedInput schema / properties / cables / description
      Previous value: -"List of cable connections to route and validate."New value: +"Batch of one or more cable connections to upsert by cable_id, route in 3D, and validate."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "data": {
      +      "additionalProperties": {},
      +      "description": "Cable connection and 3D routing result payload.",
      +      "properties": {
      +        "connected_cables": {
      +          "description": "Computed 3D spline route metrics and commercial SKU length bins for the connected cables.",
      +          "items": {
      +            "additionalProperties": {},
      +            "properties": {
      +              "assigned_ducts": {
      +                "description": "Cable ducts traversed along the route.",
      +                "items": {
      +                  "type": "string"
      +                },
      +                "type": "array"
      +              },
      +              "cable_id": {
      +                "description": "Unique cable identifier.",
      +                "type": "string"
      +              },
      +              "cable_type": {
      +                "description": "Standardized physical cable and connector assembly type.",
      +                "enum": [
      +                  "cat6a",
      +                  "cat6a-angled",
      +                  "cat6",
      +                  "cat6-angled",
      +                  "cat5e",
      +                  "cat5e-angled",
      +                  "sfp-plus-dac",
      +                  "sfp-plus-dac-angled",
      +                  "fiber-lc-duplex",
      +                  "fiber-lc-duplex-angled",
      +                  "rj45-serial-rollover",
      +                  "rj45-serial-rollover-angled",
      +                  "power-c13-c14",
      +                  "power-c13-c14-angled",
      +                  "power-schuko-c13",
      +                  "power-schuko-c13-angled",
      +                  "power-dc-5525",
      +                  "power-dc-5525-angled",
      +                  "power-usb-c",
      +                  "power-usb-c-angled"
      +                ],
      +                "type": "string"
      +              },
      +              "portal_u": {
      +                "description": "1-indexed U position of the front-to-rear cable portal if traversed.",
      +                "type": [
      +                  "number",
      +                  "null"
      +                ]
      +              },
      +              "raw_arc_length_mm": {
      +                "description": "3D Catmull-Rom spline arc length in mm.",
      +                "type": "number"
      +              },
      +              "recommended_commercial_mm": {
      +                "description": "Standard commercial patch cable length bin in mm.",
      +                "type": "number"
      +              },
      +              "required_length_mm": {
      +                "description": "Required length including slack in mm.",
      +                "type": "number"
      +              },
      +              "route_case": {
      +                "description": "Computed 3D spline routing topology class.",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "cable_id",
      +              "cable_type",
      +              "route_case",
      +              "raw_arc_length_mm",
      +              "required_length_mm",
      +              "recommended_commercial_mm"
      +            ],
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "total_cables": {
      +          "description": "Total number of active cables in the rack project.",
      +          "maximum": 9007199254740991,
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "validation": {
      +          "additionalProperties": false,
      +          "description": "Updated 5-stage validation report including port, speed, PoE budget, and plug clearance checks.",
      +          "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": [
      +        "connected_cables",
      +        "total_cables",
      +        "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"
      +}
  3. Changed10 schema fields changedv0.4.9
    • removedInput schema / additionalProperties
      Removed value: -false
    • removedInput schema / properties / cables / items / additionalProperties
      Removed value: -false
    • removedInput schema / properties / cables / items / properties / from / additionalProperties
      Removed value: -false
    • addedInput schema / properties / cables / items / properties / preferred_portal_u / maximum
      Added value: +9007199254740991
    • addedInput schema / properties / cables / items / properties / routing_mode
      Added value: +{
      +  "default": "shortest-direct",
      +  "description": "Optional routing strategy override: defaults to shortest-direct (shortest collision-free path); set to left-duct or right-duct only when the user explicitly requests routing via a side cable duct.",
      +  "enum": [
      +    "shortest-direct",
      +    "left-duct",
      +    "right-duct"
      +  ],
      +  "type": "string"
      +}
    • removedInput schema / properties / cables / items / properties / to / $ref
      Removed value: -"#/properties/cables/items/properties/from"
    • addedInput schema / properties / cables / items / properties / to / description
      Added value: +"Source or destination port endpoint of a physical cable."
    • addedInput schema / properties / cables / items / properties / to / properties
      Added value: +{
      +  "face": {
      +    "description": "Explicit rack face selector (used to distinguish front vs rear connections on passthrough couplers).",
      +    "enum": [
      +      "front",
      +      "rear"
      +    ],
      +    "type": "string"
      +  },
      +  "instance_id": {
      +    "description": "Target device instance_id (top-level or child sub-module).",
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "port_id": {
      +    "description": "Target port_id on the device.",
      +    "minLength": 1,
      +    "type": "string"
      +  }
      +}
    • addedInput schema / properties / cables / items / properties / to / required
      Added value: +[
      +  "instance_id",
      +  "port_id"
      +]
    • addedInput schema / properties / cables / items / properties / to / type
      Added value: +"object"
  4. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Goes well beyond the annotations: discloses upsert-by-cable_id semantics, that other cables and mounted equipment are untouched, the recoverable undo snapshot, atomic rack.yaml persistence, and that violations return status INVALID with remediation_suggestions rather than throwing. This is exactly the mutation/error-contract context an agent needs; only minor gaps remain (e.g., what happens on partial batch failure).

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

Conciseness4/5

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

Front-loaded with the action and scope, then behavior, then per-field caveats, then alternatives. Dense but nearly every clause carries information; the middle sentence is long enough that a reader must parse carefully, costing it the top mark.

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?

For a batch mutation tool with an output schema, the description covers mutation semantics, error contract, idempotency, persistence, and sibling routing. An agent has everything needed to decide and call correctly without consulting anything else.

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?

Schema coverage is 100%, so baseline is 3, but the description adds real conditional semantics: 'face' is required only on pass-through couplers exposing identical port_id on both faces, 'preferred_portal_u' applies only to front-to-rear transitions, and vlan_id/ip_cidr are logical annotations. These sharpen the schema's per-field text rather than restating it.

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?

States a specific verb pair (connect/update) and resource (batch of up to 128 power and network cables between mounted device ports in the active rack), plus the derived computations (splines, length bins, PoE budgets). It is clearly distinguishable from disconnect_cables and plan_external_endpoints, which are named.

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?

Explicitly states the qualifying condition ('Use when both endpoint devices are mounted inside the rack') and names two alternatives with their selecting conditions (disconnect_cables for removal, plan_external_endpoints for building cable drops). Nothing is left to inference.

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