Skip to main content
Glama

Search Hardware Blueprint Catalog

search_catalog
Read-onlyIdempotent

Filter the local hardware catalog by form factor, depth, category, slot compatibility, or PoE budget to find compatible rackmount devices and modules before mounting.

Instructions

Search and filter the local hardware catalog to discover compatible rackmount devices, modular carriers, and sub-modules before mounting. All supplied filters combine with logical AND: 'form_factor' and its alias 'mount_type' accept width shorthands '10inch', '19inch', and '6inch' that match both direct rackmount gear and modular carriers, 'accepted_slot_type' matches both carrier bays and compatible sub-modules, and 'max_depth_mm' bounds chassis depth excluding plug clearance. Returns all matches from the bounded catalog in one unpaginated response sorted in deterministic registration order, with built-in blueprints followed by custom blueprints. Call with no arguments to list the full catalog; use get_device_blueprint to inspect expanded port coordinates for a known slug, or define_custom_blueprint to register unlisted hardware.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_catalog"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryNoOptional case-insensitive substring filter matching slug, manufacturer, or model name (omit to match all).
categoryNoFunctional hardware category filter (e.g., "switch", "router", "ups", "pdu", "patch-panel", "modular-carrier", "mini-pc", "sbc").
mount_typeNoOptional alias for form_factor to filter by physical mounting style ("rackmount-10", "rackmount-19", "rackmount-6", "sub-module", or "shelf-standing"); combined with logical AND if both are provided.
form_factorNoPrimary rack width or mounting form-factor filter (shorthands "10inch", "19inch", and "6inch" match both direct rackmount equipment and modular carriers of that width).
max_depth_mmNoMaximum allowed chassis depth in millimeters (inclusive upper bound).
accepted_slot_typeNoSub-module slot compatibility token matching either a sub-module slot_compatibility or a carrier slot accepted_slot_type (e.g., "mini-pc-1liter", "sbc-rpi5", "standard-keystone").
min_poe_budget_wattsNoMinimum required PSE PoE output power budget in watts (inclusive lower bound).

Output Schema

NameRequiredDescriptionDefault
dataYesCatalog search 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. Changed7 schema fields changedv0.7.8
    • addedInput schema / properties / accepted_slot_type / maxLength
      Added value: +100
    • addedInput schema / properties / max_depth_mm / maximum
      Added value: +2000
    • addedInput schema / properties / min_poe_budget_watts / maximum
      Added value: +100000
    • addedInput schema / properties / query / maxLength
      Added value: +200
    • addedOutput schema / properties / data / properties / blueprints / items / properties / slots / items / properties / max_dimensions_mm / properties / depth / maximum
      Added value: +2000
    • addedOutput schema / properties / data / properties / blueprints / items / properties / slots / items / properties / max_dimensions_mm / properties / height / maximum
      Added value: +3000
    • addedOutput schema / properties / data / properties / blueprints / items / properties / slots / items / properties / max_dimensions_mm / properties / width / maximum
      Added value: +2000
  2. Changed8 schema fields changedv0.4.10
    • changedInput schema / properties / accepted_slot_type / description
      Previous value: -"Sub-module slot compatibility token (e.g., \"mini-pc-1liter\", \"standard-keystone\")."New value: +"Sub-module slot compatibility token matching either a sub-module slot_compatibility or a carrier slot accepted_slot_type (e.g., \"mini-pc-1liter\", \"sbc-rpi5\", \"standard-keystone\")."
    • changedInput schema / properties / category / description
      Previous value: -"Primary functional category of the hardware unit."New value: +"Functional hardware category filter (e.g., \"switch\", \"router\", \"ups\", \"pdu\", \"patch-panel\", \"modular-carrier\", \"mini-pc\", \"sbc\")."
    • changedInput schema / properties / form_factor / description
      Previous value: -"Hardware form factor or mounting mechanism filter."New value: +"Primary rack width or mounting form-factor filter (shorthands \"10inch\", \"19inch\", and \"6inch\" match both direct rackmount equipment and modular carriers of that width)."
    • changedInput schema / properties / max_depth_mm / description
      Previous value: -"Maximum allowed chassis depth in millimeters."New value: +"Maximum allowed chassis depth in millimeters (inclusive upper bound)."
    • changedInput schema / properties / min_poe_budget_watts / description
      Previous value: -"Minimum required PoE power budget in watts."New value: +"Minimum required PSE PoE output power budget in watts (inclusive lower bound)."
    • changedInput schema / properties / mount_type / description
      Previous value: -"Hardware form factor or mounting mechanism filter."New value: +"Optional alias for form_factor to filter by physical mounting style (\"rackmount-10\", \"rackmount-19\", \"rackmount-6\", \"sub-module\", or \"shelf-standing\"); combined with logical AND if both are provided."
    • changedInput schema / properties / query / description
      Previous value: -"Free-text search filter matching manufacturer, model, or slug."New value: +"Optional case-insensitive substring filter matching slug, manufacturer, or model name (omit to match all)."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "data": {
      +      "additionalProperties": {},
      +      "description": "Catalog search result payload.",
      +      "properties": {
      +        "blueprints": {
      +          "description": "Matching hardware blueprint summary records.",
      +          "items": {
      +            "additionalProperties": {},
      +            "description": "Compact hardware blueprint summary returned by search_catalog.",
      +            "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"
      +              },
      +              "depth_mm": {
      +                "description": "Chassis depth in millimeters.",
      +                "type": "number"
      +              },
      +              "electrical_role": {
      +                "description": "Role in the electrical and PoE Directed Acyclic Graph (DAG).",
      +                "enum": [
      +                  "consumer",
      +                  "pse-switch",
      +                  "pdu",
      +                  "ups",
      +                  "passive"
      +                ],
      +                "type": "string"
      +              },
      +              "height_mm": {
      +                "description": "Chassis height in millimeters.",
      +                "type": "number"
      +              },
      +              "manufacturer": {
      +                "description": "Hardware manufacturer name.",
      +                "type": "string"
      +              },
      +              "max_system_watts": {
      +                "description": "Peak system power consumption in watts.",
      +                "type": "number"
      +              },
      +              "model": {
      +                "description": "Hardware model name.",
      +                "type": "string"
      +              },
      +              "mount_type": {
      +                "description": "Physical form factor and mounting mechanism.",
      +                "enum": [
      +                  "rackmount-19",
      +                  "rackmount-10",
      +                  "rackmount-6",
      +                  "sub-module",
      +                  "shelf-standing"
      +                ],
      +                "type": "string"
      +              },
      +              "poe_budget_watts": {
      +                "description": "Available PSE PoE output budget in watts (0 if non-PSE).",
      +                "type": "number"
      +              },
      +              "port_count": {
      +                "description": "Total number of expanded physical ports.",
      +                "maximum": 9007199254740991,
      +                "minimum": 0,
      +                "type": "integer"
      +              },
      +              "slot_compatibility": {
      +                "description": "Sub-module slot compatibility token, or null for rackmount equipment.",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              },
      +              "slots": {
      +                "description": "Available carrier bays when mount_type is \"modular-carrier\".",
      +                "items": {
      +                  "additionalProperties": false,
      +                  "properties": {
      +                    "accepted_slot_type": {
      +                      "description": "Accepted child sub-module compatibility token.",
      +                      "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"
      +                    },
      +                    "slot_id": {
      +                      "description": "Carrier bay slot identifier.",
      +                      "type": "string"
      +                    }
      +                  },
      +                  "required": [
      +                    "slot_id",
      +                    "accepted_slot_type",
      +                    "max_dimensions_mm"
      +                  ],
      +                  "type": "object"
      +                },
      +                "type": "array"
      +              },
      +              "slug": {
      +                "description": "Unique lowercase kebab-case hardware blueprint slug.",
      +                "type": "string"
      +              },
      +              "u_height": {
      +                "description": "Nominal height in Rack Units (U).",
      +                "type": "number"
      +              },
      +              "weight_grams": {
      +                "description": "Device mass in grams.",
      +                "type": "number"
      +              },
      +              "width_mm": {
      +                "description": "Chassis width in millimeters.",
      +                "type": "number"
      +              }
      +            },
      +            "required": [
      +              "slug",
      +              "manufacturer",
      +              "model",
      +              "category",
      +              "mount_type",
      +              "u_height",
      +              "width_mm",
      +              "height_mm",
      +              "depth_mm",
      +              "weight_grams",
      +              "electrical_role",
      +              "max_system_watts",
      +              "poe_budget_watts",
      +              "slot_compatibility",
      +              "slots",
      +              "port_count"
      +            ],
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        "count": {
      +          "description": "Total number of catalog blueprints matching all supplied filter criteria.",
      +          "maximum": 9007199254740991,
      +          "minimum": 0,
      +          "type": "integer"
      +        }
      +      },
      +      "required": [
      +        "count",
      +        "blueprints"
      +      ],
      +      "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. Changed4 schema fields changedv0.4.9
    • removedInput schema / additionalProperties
      Removed value: -false
    • removedInput schema / properties / mount_type / $ref
      Removed value: -"#/properties/form_factor"
    • addedInput schema / properties / mount_type / enum
      Added value: +[
      +  "rackmount-19",
      +  "rackmount-10",
      +  "rackmount-6",
      +  "sub-module",
      +  "shelf-standing",
      +  "10inch",
      +  "19inch",
      +  "6inch"
      +]
    • addedInput schema / properties / mount_type / type
      Added value: +"string"
  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?

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered; the description adds genuine behavior on top: all filters combine with logical AND, mount_type is an alias rather than a distinct dimension, max_depth_mm excludes plug clearance, and results come back unpaginated in deterministic registration order (built-ins before custom). It stops short of describing error behavior or catalog size limits, keeping it below a 5.

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?

The verb and scope are front-loaded, and each clause carries information (AND semantics, alias behavior, depth exclusion, ordering, alternatives). The single dense paragraph is efficient but would scan better as short structured clauses, which is the only reason it is not a 5.

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?

Seven optional parameters are all schema-documented, an output schema handles return shape, and the description still covers the pieces an agent needs that structured fields cannot express: zero-argument behavior, AND filtering, alias equivalence, ordering, and sibling routing. Nothing material for a correct invocation 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?

With 100% schema coverage the baseline is 3, but the description earns more by clarifying enum semantics the schema states only partially: '10inch'/'19inch'/'6inch' match both direct rackmount gear and modular carriers, and accepted_slot_type matches both carrier bays and sub-module slot compatibility. It also resolves the mount_type/form_factor alias relationship and the AND combination, which the schema leaves implicit.

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: "Search and filter the local hardware catalog," and names the concrete object types returned (rackmount devices, modular carriers, sub-modules). It distinguishes itself from get_device_blueprint and define_custom_blueprint by name, so an agent can route without opening any schema.

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

Usage Guidelines5/5

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

It gives an explicit default mode ("Call with no arguments to list the full catalog") and two named alternatives with their selecting conditions: get_device_blueprint for expanded port coordinates on a known slug, define_custom_blueprint for registering unlisted hardware. Both when-to-use and when-to-use-something-else are covered.

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