Skip to main content
Glama

Retrieve Hardware Device Blueprint Details

get_device_blueprint
Read-onlyIdempotent

Retrieve a single catalog blueprint by exact slug to get complete hardware specs, port coordinates, PoE ratings, and slot geometry needed for mounting equipment or connecting cables.

Instructions

Retrieve the complete hardware specification, millimeter port coordinates, electrical and PoE ratings, and carrier slot geometry for a single catalog blueprint. The 'slug' parameter requires a case-sensitive exact match in lowercase kebab-case vendor-model-variant format against the built-in or session custom catalog; partial substrings or uppercase characters do not match. Returns the full blueprint in one unpaginated payload with repeating port_groups pre-expanded into up to 256 flat ports[] entries, or returns status 'INVALID' with a BLUEPRINT_NOT_FOUND issue and candidate slugs instead of throwing. Use when you already know the target slug and need exact port_id or slot_id values for mount_equipment or connect_cables; use search_catalog instead to discover unknown slugs by criteria.

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": {
      "slug": "<slug>"
    },
    "name": "get_device_blueprint"
  }
}

Input Schema

NameRequiredDescriptionDefault
slugYesExact lowercase kebab-case hardware catalog blueprint slug to retrieve (discoverable via search_catalog).

Output Schema

NameRequiredDescriptionDefault
dataYesBlueprint lookup 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. Changed24 schema fields changedv0.7.8
    • addedInput schema / properties / slug / maxLength
      Added value: +100
    • addedOutput schema / properties / data / properties / blueprint / properties / ports / items / properties / coordinates / properties / x_mm / maximum
      Added value: +2000
    • addedOutput schema / properties / data / properties / blueprint / properties / ports / items / properties / coordinates / properties / x_mm / minimum
      Added value: +-2000
    • addedOutput schema / properties / data / properties / blueprint / properties / ports / items / properties / coordinates / properties / y_mm / maximum
      Added value: +3000
    • addedOutput schema / properties / data / properties / blueprint / properties / ports / items / properties / coordinates / properties / y_mm / minimum
      Added value: +-3000
    • addedOutput schema / properties / data / properties / blueprint / properties / power_and_thermal / properties / idle_watts / maximum
      Added value: +100000
    • addedOutput schema / properties / data / properties / blueprint / properties / power_and_thermal / properties / max_system_watts / maximum
      Added value: +100000
    • addedOutput schema / properties / data / properties / blueprint / properties / power_and_thermal / properties / noise_db_a / maximum
      Added value: +200
    • addedOutput schema / properties / data / properties / blueprint / properties / power_and_thermal / properties / pdu_capacity_watts / maximum
      Added value: +100000
    • addedOutput schema / properties / data / properties / blueprint / properties / power_and_thermal / properties / poe_budget_watts / maximum
      Added value: +100000
    • addedOutput schema / properties / data / properties / blueprint / properties / power_and_thermal / properties / ups_capacity_watts / maximum
      Added value: +100000
    • addedOutput schema / properties / data / properties / blueprint / properties / slots / items / properties / accepted_slot_type / maxLength
      Added value: +100
    • addedOutput schema / properties / data / properties / blueprint / properties / slots / items / properties / max_dimensions_mm / properties / depth / maximum
      Added value: +2000
    • addedOutput schema / properties / data / properties / blueprint / properties / slots / items / properties / max_dimensions_mm / properties / height / maximum
      Added value: +3000
    • addedOutput schema / properties / data / properties / blueprint / properties / slots / items / properties / max_dimensions_mm / properties / width / maximum
      Added value: +2000
    • addedOutput schema / properties / data / properties / blueprint / properties / slots / items / properties / offset_mm / properties / x / maximum
      Added value: +2000
    • addedOutput schema / properties / data / properties / blueprint / properties / slots / items / properties / offset_mm / properties / x / minimum
      Added value: +-2000
    • addedOutput schema / properties / data / properties / blueprint / properties / slots / items / properties / offset_mm / properties / y / maximum
      Added value: +3000
    • addedOutput schema / properties / data / properties / blueprint / properties / slots / items / properties / offset_mm / properties / y / minimum
      Added value: +-3000
    • addedOutput schema / properties / data / properties / blueprint / properties / slots / items / properties / offset_mm / properties / z / maximum
      Added value: +2000
    • addedOutput schema / properties / data / properties / blueprint / properties / slots / items / properties / offset_mm / properties / z / minimum
      Added value: +-2000
    • addedOutput schema / properties / data / properties / blueprint / properties / slots / items / properties / slot_id / maxLength
      Added value: +100
    • addedOutput schema / properties / data / properties / blueprint / properties / visuals / properties / stl_mesh_path / anyOf
      Added value: +[
      +  {
      +    "maxLength": 512,
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedOutput schema / properties / data / properties / blueprint / properties / visuals / properties / stl_mesh_path / type
      Removed value: -[
      -  "string",
      -  "null"
      -]
  2. Changed41 schema fields changedv0.5.0
    • addedOutput schema / properties / data / properties / blueprint / properties / description / maxLength
      Added value: +2000
    • changedOutput schema / properties / data / properties / blueprint / properties / geometry / properties / depth_mm / description
      Previous value: -"Physical chassis depth in millimeters along the Z-axis."New value: +"Physical chassis depth in millimeters along the Z-axis (max 2000mm)."
    • addedOutput schema / properties / data / properties / blueprint / properties / geometry / properties / depth_mm / maximum
      Added value: +2000
    • addedOutput schema / properties / data / properties / blueprint / properties / geometry / properties / front_protrusion_mm / maximum
      Added value: +500
    • changedOutput schema / properties / data / properties / blueprint / properties / geometry / properties / height_mm / description
      Previous value: -"Physical chassis height in millimeters."New value: +"Physical chassis height in millimeters (max 3000mm)."
    • addedOutput schema / properties / data / properties / blueprint / properties / geometry / properties / height_mm / maximum
      Added value: +3000
    • addedOutput schema / properties / data / properties / blueprint / properties / geometry / properties / rear_protrusion_mm / maximum
      Added value: +500
    • changedOutput schema / properties / data / properties / blueprint / properties / geometry / properties / u_height / description
      Previous value: -"Nominal height in Rack Units (1U = 44.45mm)."New value: +"Nominal height in Rack Units (1U = 44.45mm, max 60U)."
    • addedOutput schema / properties / data / properties / blueprint / properties / geometry / properties / u_height / maximum
      Added value: +60
    • addedOutput schema / properties / data / properties / blueprint / properties / geometry / properties / weight_grams / maximum
      Added value: +500000
    • changedOutput schema / properties / data / properties / blueprint / properties / geometry / properties / width_mm / description
      Previous value: -"Physical chassis body width in millimeters."New value: +"Physical chassis body width in millimeters (max 1000mm)."
    • addedOutput schema / properties / data / properties / blueprint / properties / geometry / properties / width_mm / maximum
      Added value: +1000
    • addedOutput schema / properties / data / properties / blueprint / properties / manufacturer / maxLength
      Added value: +160
    • addedOutput schema / properties / data / properties / blueprint / properties / model / maxLength
      Added value: +160
    • addedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / capabilities / maxItems
      Added value: +32
    • changedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / count / description
      Previous value: -"Total number of ports to generate in this group."New value: +"Total number of ports to generate in this group (1..128)."
    • changedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / count / maximum
      Previous value: -9007199254740991New value: +128
    • changedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / grid / properties / columns / description
      Previous value: -"Number of horizontal port columns in the matrix."New value: +"Number of horizontal port columns in the matrix (1..64)."
    • changedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / grid / properties / columns / maximum
      Previous value: -9007199254740991New value: +64
    • addedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / grid / properties / origin_x_mm / maximum
      Added value: +2000
    • addedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / grid / properties / origin_x_mm / minimum
      Added value: +-2000
    • addedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / grid / properties / origin_y_mm / maximum
      Added value: +3000
    • addedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / grid / properties / origin_y_mm / minimum
      Added value: +-3000
    • addedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / grid / properties / pitch_x_mm / maximum
      Added value: +500
    • addedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / grid / properties / pitch_x_mm / minimum
      Added value: +-500
    • addedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / grid / properties / pitch_y_mm / maximum
      Added value: +500
    • addedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / grid / properties / pitch_y_mm / minimum
      Added value: +-500
    • changedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / grid / properties / rows / description
      Previous value: -"Number of vertical port rows in the matrix."New value: +"Number of vertical port rows in the matrix (1..16)."
    • changedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / grid / properties / rows / maximum
      Previous value: -9007199254740991New value: +16
    • addedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / id_prefix / maxLength
      Added value: +64
    • addedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / label_prefix / maxLength
      Added value: +96
    • changedOutput schema / properties / data / properties / blueprint / properties / port_groups / items / properties / start_index / maximum
      Previous value: -9007199254740991New value: +10000
    • addedOutput schema / properties / data / properties / blueprint / properties / port_groups / maxItems
      Added value: +16
    • addedOutput schema / properties / data / properties / blueprint / properties / ports / items / properties / capabilities / maxItems
      Added value: +32
    • addedOutput schema / properties / data / properties / blueprint / properties / ports / items / properties / label / maxLength
      Added value: +160
    • addedOutput schema / properties / data / properties / blueprint / properties / ports / items / properties / port_id / maxLength
      Added value: +128
    • addedOutput schema / properties / data / properties / blueprint / properties / ports / maxItems
      Added value: +256
    • changedOutput schema / properties / data / properties / blueprint / properties / printable_metadata / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "fasteners": {
      -        "description": "Optional specification of required mounting screws and cage nuts.",
      -        "type": "string"
      -      },
      -      "filament_grams": {
      -        "description": "Estimated filament mass in grams.",
      -        "minimum": 0,
      -        "type": "number"
      -      },
      -      "heat_set_inserts": {
      -        "description": "Optional specification of required brass heat-set inserts.",
      -        "type": "string"
      -      },
      -      "material_recommendation": {
      -        "default": "PETG",
      -        "description": "Recommended 3D printing filament material (e.g. \"PETG\", \"ABS\", \"ASA\").",
      -        "type": "string"
      -      },
      -      "printables_url": {
      -        "description": "Optional reference URL to an upstream 3D model repository.",
      -        "format": "uri",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "filament_grams",
      -      "material_recommendation"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "fasteners": {
      +        "description": "Optional specification of required mounting screws and cage nuts.",
      +        "maxLength": 256,
      +        "type": "string"
      +      },
      +      "filament_grams": {
      +        "description": "Estimated filament mass in grams.",
      +        "maximum": 50000,
      +        "minimum": 0,
      +        "type": "number"
      +      },
      +      "heat_set_inserts": {
      +        "description": "Optional specification of required brass heat-set inserts.",
      +        "maxLength": 256,
      +        "type": "string"
      +      },
      +      "material_recommendation": {
      +        "default": "PETG",
      +        "description": "Recommended 3D printing filament material (e.g. \"PETG\", \"ABS\", \"ASA\").",
      +        "maxLength": 128,
      +        "type": "string"
      +      },
      +      "printables_url": {
      +        "description": "Optional HTTPS reference URL to an upstream 3D model repository.",
      +        "maxLength": 512,
      +        "pattern": "^https?:\\/\\/",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "filament_grams",
      +      "material_recommendation"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedOutput schema / properties / data / properties / blueprint / properties / slot_compatibility / maxLength
      Added value: +100
    • addedOutput schema / properties / data / properties / blueprint / properties / slots / maxItems
      Added value: +32
    • addedOutput schema / properties / data / properties / blueprint / properties / slug / maxLength
      Added value: +100
  3. Changed2 schema fields changedv0.4.10
    • changedInput schema / properties / slug / description
      Previous value: -"Exact hardware catalog blueprint slug to retrieve."New value: +"Exact lowercase kebab-case hardware catalog blueprint slug to retrieve (discoverable via search_catalog)."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "data": {
      +      "additionalProperties": {},
      +      "description": "Blueprint lookup result payload.",
      +      "properties": {
      +        "blueprint": {
      +          "additionalProperties": false,
      +          "description": "Complete hardware blueprint specification with port_groups pre-expanded into flat ports[].",
      +          "properties": {
      +            "category": {
      +              "description": "Primary functional category of the hardware unit.",
      +              "enum": [
      +                "switch",
      +                "router",
      +                "compute-node",
      +                "mini-pc",
      +                "sbc",
      +                "nas",
      +                "patch-panel",
      +                "pdu",
      +                "ups",
      +                "modular-carrier",
      +                "brush-panel",
      +                "blanking-panel",
      +                "blank-panel",
      +                "shelf",
      +                "keystone-module"
      +              ],
      +              "type": "string"
      +            },
      +            "description": {
      +              "description": "Human-readable explanation of what the device is, its role in the rack, and its physical mounting method (e.g. native rack ears vs. 3D-printed carrier/cradle).",
      +              "type": "string"
      +            },
      +            "geometry": {
      +              "additionalProperties": false,
      +              "description": "Physical 3D bounding dimensions and mass specification.",
      +              "properties": {
      +                "depth_mm": {
      +                  "description": "Physical chassis depth in millimeters along the Z-axis.",
      +                  "exclusiveMinimum": 0,
      +                  "type": "number"
      +                },
      +                "ear_mount_style": {
      +                  "default": "flush-front",
      +                  "description": "Mounting ear geometry relative to the vertical rack rails.",
      +                  "enum": [
      +                    "included-19inch-ears",
      +                    "included-10inch-ears",
      +                    "included-6inch-ears",
      +                    "flush-front",
      +                    "recessed-20mm",
      +                    "sub-module-clip",
      +                    "rear-rail-mount",
      +                    "none"
      +                  ],
      +                  "type": "string"
      +                },
      +                "front_protrusion_mm": {
      +                  "default": 0,
      +                  "description": "Protrusion in front of Z=0 (handles, ears, knobs) in mm.",
      +                  "minimum": 0,
      +                  "type": "number"
      +                },
      +                "has_cable_pass_through": {
      +                  "description": "True if cables can pass front-to-rear through this unit.",
      +                  "type": "boolean"
      +                },
      +                "height_mm": {
      +                  "description": "Physical chassis height in millimeters.",
      +                  "exclusiveMinimum": 0,
      +                  "type": "number"
      +                },
      +                "rear_protrusion_mm": {
      +                  "default": 0,
      +                  "description": "Protrusion behind depth_mm (fans, PSU handles) in mm.",
      +                  "minimum": 0,
      +                  "type": "number"
      +                },
      +                "u_height": {
      +                  "description": "Nominal height in Rack Units (1U = 44.45mm).",
      +                  "minimum": 0,
      +                  "type": "number"
      +                },
      +                "weight_grams": {
      +                  "default": 0,
      +                  "description": "Total device mass in grams for Center of Gravity calculation.",
      +                  "minimum": 0,
      +                  "type": "number"
      +                },
      +                "width_mm": {
      +                  "description": "Physical chassis body width in millimeters.",
      +                  "exclusiveMinimum": 0,
      +                  "type": "number"
      +                }
      +              },
      +              "required": [
      +                "u_height",
      +                "width_mm",
      +                "height_mm",
      +                "depth_mm",
      +                "ear_mount_style",
      +                "front_protrusion_mm",
      +                "rear_protrusion_mm",
      +                "weight_grams"
      +              ],
      +              "type": "object"
      +            },
      +            "is_passthrough_coupler": {
      +              "description": "True if the entire unit acts as a passive front-to-rear feedthrough patch panel.",
      +              "type": "boolean"
      +            },
      +            "manufacturer": {
      +              "description": "Hardware manufacturer name.",
      +              "minLength": 1,
      +              "type": "string"
      +            },
      +            "model": {
      +              "description": "Hardware model name or part number.",
      +              "minLength": 1,
      +              "type": "string"
      +            },
      +            "mount_type": {
      +              "description": "Physical form factor and mounting mechanism.",
      +              "enum": [
      +                "rackmount-19",
      +                "rackmount-10",
      +                "rackmount-6",
      +                "sub-module",
      +                "shelf-standing"
      +              ],
      +              "type": "string"
      +            },
      +            "port_groups": {
      +              "default": [],
      +              "description": "Optional repeating port grid macros expanded into flat ports[] upon registration.",
      +              "items": {
      +                "additionalProperties": false,
      +                "description": "Declarative port matrix macro expanded into flat PortDefinition items on load.",
      +                "properties": {
      +                  "capabilities": {
      +                    "default": [],
      +                    "description": "Capabilities assigned to every port generated by this group.",
      +                    "items": {
      +                      "description": "Supported electrical, optical, or PoE protocol capability.",
      +                      "enum": [
      +                        "100base-tx",
      +                        "1000base-t",
      +                        "2500base-t",
      +                        "5gbase-t",
      +                        "10gbase-t",
      +                        "10gbase-sr",
      +                        "10gbase-lr",
      +                        "10gbase-dac",
      +                        "25gbase-dac",
      +                        "poe-out",
      +                        "poe+",
      +                        "poe-out-af",
      +                        "poe-out-at",
      +                        "poe-out-bt-type3",
      +                        "poe-out-bt-type4",
      +                        "poe-in-af",
      +                        "poe-in-at",
      +                        "poe-in-bt-type3",
      +                        "poe-in-bt-type4",
      +                        "ac-mains",
      +                        "dc-power",
      +                        "usb-pd",
      +                        "usb-3.0",
      +                        "usb-3.1",
      +                        "audio-analog",
      +                        "serial-rs232",
      +                        "passthrough-coupler"
      +                      ],
      +                      "type": "string"
      +                    },
      +                    "type": "array"
      +                  },
      +                  "connector_type": {
      +                    "description": "Physical connector interface type.",
      +                    "enum": [
      +                      "rj45",
      +                      "rj45-serial-console",
      +                      "sfp-plus",
      +                      "iec-c13",
      +                      "iec-c14",
      +                      "schuko-cee7",
      +                      "dc-5525",
      +                      "usb-c",
      +                      "usb-a",
      +                      "audio-35mm"
      +                    ],
      +                    "type": "string"
      +                  },
      +                  "count": {
      +                    "description": "Total number of ports to generate in this group.",
      +                    "exclusiveMinimum": 0,
      +                    "maximum": 9007199254740991,
      +                    "type": "integer"
      +                  },
      +                  "direction": {
      +                    "description": "Signal or electrical power flow direction.",
      +                    "enum": [
      +                      "input",
      +                      "output",
      +                      "bidirectional"
      +                    ],
      +                    "type": "string"
      +                  },
      +                  "face": {
      +                    "description": "Mounting or port face relative to the rack or chassis.",
      +                    "enum": [
      +                      "front",
      +                      "rear"
      +                    ],
      +                    "type": "string"
      +                  },
      +                  "grid": {
      +                    "additionalProperties": false,
      +                    "description": "2D grid layout parameters for automatic port matrix expansion.",
      +                    "properties": {
      +                      "columns": {
      +                        "description": "Number of horizontal port columns in the matrix.",
      +                        "exclusiveMinimum": 0,
      +                        "maximum": 9007199254740991,
      +                        "type": "integer"
      +                      },
      +                      "origin_x_mm": {
      +                        "description": "X coordinate of the first port (column 0) in mm.",
      +                        "type": "number"
      +                      },
      +                      "origin_y_mm": {
      +                        "description": "Y coordinate of the first port (row 0) in mm.",
      +                        "type": "number"
      +                      },
      +                      "pitch_x_mm": {
      +                        "description": "Horizontal center-to-center spacing between adjacent columns in mm.",
      +                        "type": "number"
      +                      },
      +                      "pitch_y_mm": {
      +                        "description": "Vertical center-to-center spacing between adjacent rows in mm.",
      +                        "type": "number"
      +                      },
      +                      "rows": {
      +                        "description": "Number of vertical port rows in the matrix.",
      +                        "exclusiveMinimum": 0,
      +                        "maximum": 9007199254740991,
      +                        "type": "integer"
      +                      }
      +                    },
      +                    "required": [
      +                      "origin_x_mm",
      +                      "origin_y_mm",
      +                      "columns",
      +                      "rows",
      +                      "pitch_x_mm",
      +                      "pitch_y_mm"
      +                    ],
      +                    "type": "object"
      +                  },
      +                  "id_prefix": {
      +                    "description": "Prefix for generated port_id values (e.g. \"eth\").",
      +                    "minLength": 1,
      +                    "type": "string"
      +                  },
      +                  "is_passthrough_coupler": {
      +                    "description": "True if generated ports are passive front-to-rear couplers.",
      +                    "type": "boolean"
      +                  },
      +                  "label_prefix": {
      +                    "description": "Prefix for generated human-readable labels.",
      +                    "type": "string"
      +                  },
      +                  "orientation": {
      +                    "default": "upright",
      +                    "description": "Physical orientation of the connector latch/keyway.",
      +                    "enum": [
      +                      "upright",
      +                      "inverted",
      +                      "left",
      +                      "right"
      +                    ],
      +                    "type": "string"
      +                  },
      +                  "start_index": {
      +                    "default": 1,
      +                    "description": "Starting numeric suffix for generated port IDs (default: 1).",
      +                    "maximum": 9007199254740991,
      +                    "minimum": 0,
      +                    "type": "integer"
      +                  }
      +                },
      +                "required": [
      +                  "id_prefix",
      +                  "start_index",
      +                  "count",
      +                  "face",
      +                  "connector_type",
      +                  "direction",
      +                  "capabilities",
      +                  "orientation",
      +                  "grid"
      +                ],
      +                "type": "object"
      +              },
      +              "type": "array"
      +            },
      +            "ports": {
      +              "default": [],
      +              "description": "Explicit physical ports with local face millimeter coordinates.",
      +              "items": {
      +                "additionalProperties": false,
      +                "description": "Explicit physical port definition with local millimeter coordinates.",
      +                "properties": {
      +                  "capabilities": {
      +                    "default": [],
      +                    "description": "Electrical, optical, or PoE capabilities supported by this port.",
      +                    "items": {
      +                      "description": "Supported electrical, optical, or PoE protocol capability.",
      +                      "enum": [
      +                        "100base-tx",
      +                        "1000base-t",
      +                        "2500base-t",
      +                        "5gbase-t",
      +                        "10gbase-t",
      +                        "10gbase-sr",
      +                        "10gbase-lr",
      +                        "10gbase-dac",
      +                        "25gbase-dac",
      +                        "poe-out",
      +                        "poe+",
      +                        "poe-out-af",
      +                        "poe-out-at",
      +                        "poe-out-bt-type3",
      +                        "poe-out-bt-type4",
      +                        "poe-in-af",
      +                        "poe-in-at",
      +                        "poe-in-bt-type3",
      +                        "poe-in-bt-type4",
      +                        "ac-mains",
      +                        "dc-power",
      +                        "usb-pd",
      +                        "usb-3.0",
      +                        "usb-3.1",
      +                        "audio-analog",
      +                        "serial-rs232",
      +                        "passthrough-coupler"
      +                      ],
      +                      "type": "string"
      +                    },
      +                    "type": "array"
      +                  },
      +                  "connector_type": {
      +                    "description": "Physical connector interface type.",
      +                    "enum": [
      +                      "rj45",
      +                      "rj45-serial-console",
      +                      "sfp-plus",
      +                      "iec-c13",
      +                      "iec-c14",
      +                      "schuko-cee7",
      +                      "dc-5525",
      +                      "usb-c",
      +                      "usb-a",
      +                      "audio-35mm"
      +                    ],
      +                    "type": "string"
      +                  },
      +                  "coordinates": {
      +                    "additionalProperties": false,
      +                    "description": "Local 2D coordinates on the device face in millimeters.",
      +                    "properties": {
      +                      "orientation": {
      +                        "default": "upright",
      +                        "description": "Physical orientation of the connector latch/keyway.",
      +                        "enum": [
      +                          "upright",
      +                          "inverted",
      +                          "left",
      +                          "right"
      +                        ],
      +                        "type": "string"
      +                      },
      +                      "x_mm": {
      +                        "description": "Horizontal offset in mm from the bottom-left corner of the face.",
      +                        "type": "number"
      +                      },
      +                      "y_mm": {
      +                        "description": "Vertical offset in mm from the bottom-left corner of the face.",
      +                        "type": "number"
      +                      }
      +                    },
      +                    "required": [
      +                      "x_mm",
      +                      "y_mm",
      +                      "orientation"
      +                    ],
      +                    "type": "object"
      +                  },
      +                  "direction": {
      +                    "description": "Signal or electrical power flow direction.",
      +                    "enum": [
      +                      "input",
      +                      "output",
      +                      "bidirectional"
      +                    ],
      +                    "type": "string"
      +                  },
      +                  "face": {
      +                    "description": "Mounting or port face relative to the rack or chassis.",
      +                    "enum": [
      +                      "front",
      +                      "rear"
      +                    ],
      +                    "type": "string"
      +                  },
      +                  "is_passthrough_coupler": {
      +                    "description": "True if this port is a passive front-to-rear feedthrough coupler.",
      +                    "type": "boolean"
      +                  },
      +                  "label": {
      +                    "description": "Human-readable silk-screened port label.",
      +                    "minLength": 1,
      +                    "type": "string"
      +                  },
      +                  "port_id": {
      +                    "description": "Unique identifier of the port within the device.",
      +                    "minLength": 1,
      +                    "type": "string"
      +                  }
      +                },
      +                "required": [
      +                  "port_id",
      +                  "label",
      +                  "face",
      +                  "connector_type",
      +                  "direction",
      +                  "capabilities",
      +                  "coordinates"
      +                ],
      +                "type": "object"
      +              },
      +              "type": "array"
      +            },
      +            "power_and_thermal": {
      +              "additionalProperties": false,
      +              "description": "Electrical power consumption, PoE budget, thermal airflow, and acoustic dB(A) characteristics.",
      +              "properties": {
      +                "airflow": {
      +                  "default": "passive-convection",
      +                  "description": "Primary thermal airflow path through the device chassis.",
      +                  "enum": [
      +                    "front-to-rear",
      +                    "rear-to-front",
      +                    "side-to-side",
      +                    "passive-convection",
      +                    "none"
      +                  ],
      +                  "type": "string"
      +                },
      +                "electrical_role": {
      +                  "description": "Role in the electrical and PoE Directed Acyclic Graph (DAG).",
      +                  "enum": [
      +                    "consumer",
      +                    "pse-switch",
      +                    "pdu",
      +                    "ups",
      +                    "passive"
      +                  ],
      +                  "type": "string"
      +                },
      +                "idle_watts": {
      +                  "default": 0,
      +                  "description": "Idle power draw in watts.",
      +                  "minimum": 0,
      +                  "type": "number"
      +                },
      +                "max_system_watts": {
      +                  "default": 0,
      +                  "description": "Peak own system power consumption in watts (excluding PoE output).",
      +                  "minimum": 0,
      +                  "type": "number"
      +                },
      +                "noise_db_a": {
      +                  "description": "Acoustic noise emission in dB(A) at 1 meter distance.",
      +                  "minimum": 0,
      +                  "type": "number"
      +                },
      +                "pdu_capacity_watts": {
      +                  "description": "Maximum output load capacity in watts for PDU units.",
      +                  "exclusiveMinimum": 0,
      +                  "type": "number"
      +                },
      +                "poe_budget_watts": {
      +                  "description": "Maximum total PoE output power budget in watts for PSE switches.",
      +                  "minimum": 0,
      +                  "type": "number"
      +                },
      +                "ups_capacity_watts": {
      +                  "description": "Maximum output load capacity in watts for UPS units.",
      +                  "exclusiveMinimum": 0,
      +                  "type": "number"
      +                }
      +              },
      +              "required": [
      +                "electrical_role",
      +                "idle_watts",
      +                "max_system_watts",
      +                "airflow"
      +              ],
      +              "type": "object"
      +            },
      +            "printable_metadata": {
      +              "anyOf": [
      +                {
      +                  "additionalProperties": false,
      +                  "properties": {
      +                    "fasteners": {
      +                      "description": "Optional specification of required mounting screws and cage nuts.",
      +                      "type": "string"
      +                    },
      +                    "filament_grams": {
      +                      "description": "Estimated filament mass in grams.",
      +                      "minimum": 0,
      +                      "type": "number"
      +                    },
      +                    "heat_set_inserts": {
      +                      "description": "Optional specification of required brass heat-set inserts.",
      +                      "type": "string"
      +                    },
      +                    "material_recommendation": {
      +                      "default": "PETG",
      +                      "description": "Recommended 3D printing filament material (e.g. \"PETG\", \"ABS\", \"ASA\").",
      +                      "type": "string"
      +                    },
      +                    "printables_url": {
      +                      "description": "Optional reference URL to an upstream 3D model repository.",
      +                      "format": "uri",
      +                      "type": "string"
      +                    }
      +                  },
      +                  "required": [
      +                    "filament_grams",
      +                    "material_recommendation"
      +                  ],
      +                  "type": "object"
      +                },
      +                {
      +                  "type": "null"
      +                }
      +              ],
      +              "default": null,
      +              "description": "3D printing fabrication metadata for printable modular carriers."
      +            },
      +            "slot_compatibility": {
      +              "description": "Slot compatibility token when mount_type is \"sub-module\".",
      +              "type": "string"
      +            },
      +            "slots": {
      +              "default": [],
      +              "description": "Sub-module carrier bays when mount_type is \"modular-carrier\".",
      +              "items": {
      +                "additionalProperties": false,
      +                "description": "Sub-U carrier bay specification for modular child devices.",
      +                "properties": {
      +                  "accepted_slot_type": {
      +                    "description": "Required child slot_compatibility token (e.g. \"mini-pc-1liter\").",
      +                    "minLength": 1,
      +                    "type": "string"
      +                  },
      +                  "max_dimensions_mm": {
      +                    "additionalProperties": false,
      +                    "description": "Maximum internal bounding dimensions of a carrier slot in mm.",
      +                    "properties": {
      +                      "depth": {
      +                        "description": "Maximum allowed child depth in mm.",
      +                        "exclusiveMinimum": 0,
      +                        "type": "number"
      +                      },
      +                      "height": {
      +                        "description": "Maximum allowed child height in mm.",
      +                        "exclusiveMinimum": 0,
      +                        "type": "number"
      +                      },
      +                      "width": {
      +                        "description": "Maximum allowed child width in mm.",
      +                        "exclusiveMinimum": 0,
      +                        "type": "number"
      +                      }
      +                    },
      +                    "required": [
      +                      "width",
      +                      "height",
      +                      "depth"
      +                    ],
      +                    "type": "object"
      +                  },
      +                  "offset_mm": {
      +                    "additionalProperties": false,
      +                    "description": "Local 3D offset of a sub-module slot relative to its parent carrier.",
      +                    "properties": {
      +                      "x": {
      +                        "description": "Local X offset from carrier origin in mm.",
      +                        "type": "number"
      +                      },
      +                      "y": {
      +                        "description": "Local Y offset from carrier origin in mm.",
      +                        "type": "number"
      +                      },
      +                      "z": {
      +                        "default": 0,
      +                        "description": "Local Z offset from carrier origin in mm.",
      +                        "type": "number"
      +                      }
      +                    },
      +                    "required": [
      +                      "x",
      +                      "y",
      +                      "z"
      +                    ],
      +                    "type": "object"
      +                  },
      +                  "slot_id": {
      +                    "description": "Unique slot identifier within the carrier.",
      +                    "minLength": 1,
      +                    "type": "string"
      +                  }
      +                },
      +                "required": [
      +                  "slot_id",
      +                  "accepted_slot_type",
      +                  "offset_mm",
      +                  "max_dimensions_mm"
      +                ],
      +                "type": "object"
      +              },
      +              "type": "array"
      +            },
      +            "slug": {
      +              "description": "Unique lowercase kebab-case hardware identifier (vendor-model-variant).",
      +              "minLength": 1,
      +              "pattern": "^[a-z0-9-]+$",
      +              "type": "string"
      +            },
      +            "visuals": {
      +              "additionalProperties": false,
      +              "default": {
      +                "chassis_color_hex": "#E5E7EB",
      +                "has_oled_display": false,
      +                "material_preset": "matte-black-steel",
      +                "stl_mesh_path": null
      +              },
      +              "description": "Visual rendering metadata for 2D SVG and 3D WebGL pipelines.",
      +              "properties": {
      +                "chassis_color_hex": {
      +                  "default": "#E5E7EB",
      +                  "description": "Primary chassis hex color code.",
      +                  "pattern": "^#[0-9A-Fa-f]{6}$",
      +                  "type": "string"
      +                },
      +                "has_oled_display": {
      +                  "default": false,
      +                  "description": "True if the front panel includes a status OLED screen.",
      +                  "type": "boolean"
      +                },
      +                "material_preset": {
      +                  "default": "matte-black-steel",
      +                  "description": "Surface material shader preset for 3D procedural rendering.",
      +                  "enum": [
      +                    "matte-black-steel",
      +                    "coated-aluminum",
      +                    "3d-printed-petg",
      +                    "3d-printed-abs",
      +                    "polycarbonate"
      +                  ],
      +                  "type": "string"
      +                },
      +                "stl_mesh_path": {
      +                  "default": null,
      +                  "description": "Optional relative path to custom 3D mesh (.stl/.glb).",
      +                  "type": [
      +                    "string",
      +                    "null"
      +                  ]
      +                }
      +              },
      +              "required": [
      +                "chassis_color_hex",
      +                "material_preset",
      +                "has_oled_display",
      +                "stl_mesh_path"
      +              ],
      +              "type": "object"
      +            }
      +          },
      +          "required": [
      +            "slug",
      +            "manufacturer",
      +            "model",
      +            "category",
      +            "mount_type",
      +            "geometry",
      +            "power_and_thermal",
      +            "port_groups",
      +            "ports",
      +            "slots",
      +            "visuals",
      +            "printable_metadata"
      +          ],
      +          "type": "object"
      +        },
      +        "requested_slug": {
      +          "description": "Requested slug echoed when lookup fails with BLUEPRINT_NOT_FOUND.",
      +          "type": "string"
      +        }
      +      },
      +      "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"
      +}
  4. Changed1 schema field changedv0.4.9
    • removedInput schema / additionalProperties
      Removed value: -false
  5. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the readOnly/idempotent/closed-world annotations, it discloses matching semantics (case-sensitive, no partial substrings), response shape (unpaginated, port_groups pre-expanded into up to 256 flat ports[]), and error behavior (returns status 'INVALID' with a BLUEPRINT_NOT_FOUND issue and candidate slugs rather than throwing). These are non-obvious behavioral traits an agent could not infer from annotations.

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?

It is front-loaded with the core action and closes with the routing rule, and nearly every clause carries operational detail. The middle sentence is dense and runs long, which costs a little scannability, but no sentence is padding.

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 single-parameter read tool with an output schema and full annotation coverage, this description supplies everything needed: matching rules, payload shape, and failure mode. Nothing required to invoke it correctly or interpret an error is missing.

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% and the schema already describes the slug format, so baseline is 3. The description adds practical meaning beyond that: uppercase or substring input will not match, and failures surface candidate slugs for recovery, which materially changes how the agent should construct and retry the call.

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 opens with a specific verb and resource ("Retrieve the complete hardware specification... for a single catalog blueprint") and enumerates the payload contents (port coordinates, PoE ratings, slot geometry). It is clearly distinguishable from search_catalog, mount_equipment, and connect_cables, which are named explicitly.

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 states the exact precondition ("Use when you already know the target slug and need exact port_id or slot_id values") and names the alternative for the opposite case ("use search_catalog instead to discover unknown slugs by criteria"). No inference is left about when this tool is the right choice.

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