[
  {
    "name": "add_cm_task",
    "description": "Add an automated-config task (a device operation) to a DRAFT change management. Give the cm_id, device_id, an `operation` from list_cm_task_catalog, and its variables. Requires cm:update + device:read. The task does NOT execute — a human runs the CM later.",
    "inputSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "cm_id": {
          "description": "The DRAFT change management to add the task to.",
          "format": "uuid",
          "type": "string"
        },
        "device_id": {
          "description": "The device the operation runs on.",
          "format": "uuid",
          "type": "string"
        },
        "operation": {
          "description": "The operation to run — an `operation_name` from `list_cm_task_catalog` for this device.",
          "type": "string"
        },
        "title": {
          "description": "Optional step title (defaults to the operation's title).",
          "type": [
            "string",
            "null"
          ]
        },
        "variables": {
          "description": "Operation variables as an object of `{ name: value }` (see the operation's `variables`)."
        }
      },
      "required": [
        "cm_id",
        "device_id",
        "operation"
      ],
      "type": "object"
    },
    "outputSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "cm_id": {
          "format": "uuid",
          "type": "string"
        },
        "operation": {
          "type": "string"
        },
        "plan_id": {
          "format": "uuid",
          "type": "string"
        },
        "position": {
          "format": "int32",
          "type": "integer"
        },
        "task_id": {
          "format": "uuid",
          "type": "string"
        }
      },
      "required": [
        "cm_id",
        "plan_id",
        "task_id",
        "operation",
        "position"
      ],
      "type": "object"
    }
  },
  {
    "name": "check_connectivity",
    "description": "Answer \"why can't A reach B?\" — trace the observed network path between two points and evaluate per-hop link, VLAN, STP and routing checks against collected state (passive: nothing is probed). Returns a one-sentence verdict with caveats, forward and return hop lists with pass/fail/unknown/not_checked checks, and stated limits (firewall rules are not yet evaluated; host-level causes are invisible). src and dst each take an endpoint id, a device id, or an IP literal; an ambiguous IP returns candidates to pick from rather than auto-resolving. Requires device:read.",
    "inputSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "dst": {
          "description": "Destination: an endpoint id, a device id, or an IP literal.",
          "type": "string"
        },
        "port": {
          "format": "uint16",
          "maximum": 65535,
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "proto": {
          "description": "\"tcp\" | \"udp\" | \"icmp\". Display-only until the filter leg lands.",
          "type": [
            "string",
            "null"
          ]
        },
        "src": {
          "description": "Source: an endpoint id, a device id, or an IP literal.",
          "type": "string"
        }
      },
      "required": [
        "src",
        "dst"
      ],
      "type": "object"
    },
    "outputSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "status": {
          "description": "`\"blocked\"` | `\"clear\"` | `\"unknown\"`. `unknown` means the collected state was not\nenough to decide — it is not a quiet \"fine\". Read `verdict` and the trace's stated\nlimits before drawing a conclusion from it.",
          "type": "string"
        },
        "trace": {
          "description": "The full trace document: resolution (with picker candidates on\nambiguity), forward/reverse hop lists with per-hop checks, passport,\nand the stated limits. Same shape as `GET /api/path-check`."
        },
        "verdict": {
          "description": "The verdict sentence — the one-line answer (caveats inside `trace`).",
          "type": "string"
        }
      },
      "required": [
        "verdict",
        "status",
        "trace"
      ],
      "type": "object"
    }
  },
  {
    "name": "create_change_management",
    "description": "Create a DRAFT change management in your context. Requires the cm:create permission. The draft does NOT execute — a human (or an execute-capable principal) submits and starts it later.",
    "inputSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "description": {
          "description": "Optional longer description of what the change does and why.",
          "type": [
            "string",
            "null"
          ]
        },
        "title": {
          "description": "Short human-readable title for the change.",
          "type": "string"
        }
      },
      "required": [
        "title"
      ],
      "type": "object"
    },
    "outputSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "cm_id": {
          "format": "uuid",
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "title": {
          "type": "string"
        }
      },
      "required": [
        "cm_id",
        "state",
        "title"
      ],
      "type": "object"
    }
  },
  {
    "name": "describe",
    "description": "Describe a resource type (devices, gateways, incidents, change_managements) or device_state: its fields, filters, and — for device_state — every aspect get_device_state can return. Call this to learn a type before querying it.",
    "inputSchema": {
      "$defs": {
        "DescribeTarget": {
          "description": "What `describe` can document: a resource type, or `device_state` for the aspects\n`get_device_state` returns.",
          "enum": [
            "devices",
            "gateways",
            "incidents",
            "change_managements",
            "device_state"
          ],
          "type": "string"
        }
      },
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "type": {
          "$ref": "#/$defs/DescribeTarget",
          "description": "What to describe."
        }
      },
      "required": [
        "type"
      ],
      "type": "object"
    },
    "outputSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "info": {
          "description": "Field lists and available filters for the type."
        },
        "resource_type": {
          "type": "string"
        }
      },
      "required": [
        "resource_type",
        "info"
      ],
      "type": "object"
    }
  },
  {
    "name": "get_device_state",
    "description": "Read one slice of a device's observed state. Start with aspect=overview: one cheap call giving counts for every aspect and any failing collector, so you can tell what is worth reading. Then read in full with aspect = config (running config text), config_history, interfaces, vlans, mac_table (endpoints seen on each port), routes, stp, neighbors (LLDP), wireless, or monitoring (which collectors run, whether they are succeeding, and how much each produced — this is the state of collection FROM the device, not the device's own health). An empty aspect reports the status of the collector behind it. Requires device:read. Call describe with type=device_state for each aspect's fields and paging options.",
    "inputSchema": {
      "$defs": {
        "DeviceStateAspect": {
          "description": "Which slice of a device's observed state to return.",
          "enum": [
            "overview",
            "config",
            "config_history",
            "interfaces",
            "vlans",
            "mac_table",
            "routes",
            "stp",
            "neighbors",
            "wireless",
            "monitoring"
          ],
          "type": "string"
        }
      },
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "aspect": {
          "$ref": "#/$defs/DeviceStateAspect",
          "description": "Which slice of state to return."
        },
        "device_id": {
          "description": "The device's UUID (from `list_resources` with type=devices).",
          "format": "uuid",
          "type": "string"
        },
        "limit": {
          "description": "Row cap for the row-shaped aspects (default 50, max 200).",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "max_bytes": {
          "description": "`config` only: how much config text to return (default 16384, max 65536).",
          "format": "uint",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "offset": {
          "description": "Row offset for the row-shaped aspects. Pass the previous response's `next_offset` to\nread the rows a cap cut off; without it a truncated aspect's tail is unreachable.\nApplies to the collection `limit` caps — the membership matrix for vlans, the ports\nfor stp, the clients for wireless.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "offset_bytes": {
          "description": "`config` only: byte offset into the config text, for paging a long config.",
          "format": "uint",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "snapshot_id": {
          "description": "`config` only: a specific snapshot id from `config_history`; defaults to the latest.",
          "format": "uuid",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "device_id",
        "aspect"
      ],
      "type": "object"
    },
    "outputSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "aspect": {
          "type": "string"
        },
        "device_id": {
          "format": "uuid",
          "type": "string"
        },
        "device_last_seen_at": {
          "description": "When the platform last heard from the device at all. State is collected on a poll\ncycle, so treat every aspect below as \"last observed\", not \"live\".",
          "type": "string"
        },
        "device_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "server_time": {
          "description": "The platform's clock, for ageing any timestamp in this response.",
          "type": "string"
        },
        "state": {
          "description": "The aspect payload; its shape depends on `aspect` (see `describe` with\ntype=device_state)."
        }
      },
      "required": [
        "device_id",
        "aspect",
        "device_last_seen_at",
        "server_time",
        "state"
      ],
      "type": "object"
    }
  },
  {
    "name": "get_resource",
    "description": "Get full detail for one resource by `type` and `id` (the interesting-looking summary you got from list_resources). Enforces read permission on that specific resource.",
    "inputSchema": {
      "$defs": {
        "ResourceType": {
          "description": "The resource types the read facade understands.",
          "enum": [
            "devices",
            "gateways",
            "incidents",
            "change_managements"
          ],
          "type": "string"
        }
      },
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "id": {
          "description": "The resource's UUID.",
          "format": "uuid",
          "type": "string"
        },
        "type": {
          "$ref": "#/$defs/ResourceType",
          "description": "The resource type."
        }
      },
      "required": [
        "type",
        "id"
      ],
      "type": "object"
    },
    "outputSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "resource": {
          "description": "The full resource detail (shape depends on the type; see `describe`)."
        },
        "resource_type": {
          "type": "string"
        },
        "server_time": {
          "description": "The platform's clock, for ageing the timestamps below.",
          "type": "string"
        }
      },
      "required": [
        "resource_type",
        "server_time",
        "resource"
      ],
      "type": "object"
    }
  },
  {
    "name": "list_cm_task_catalog",
    "description": "List the configuration operations available for a device (its vendor-profile task catalog). Each operation is a candidate for add_cm_task. Requires device:read.",
    "inputSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "device_id": {
          "description": "The device whose available configuration operations you want.",
          "format": "uuid",
          "type": "string"
        }
      },
      "required": [
        "device_id"
      ],
      "type": "object"
    },
    "outputSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "device_id": {
          "format": "uuid",
          "type": "string"
        },
        "operations": {
          "description": "Each operation: `{ operation_name, title, description, variables[] }`. Pass an\n`operation_name` (and its variables) to `add_cm_task`.",
          "items": true,
          "type": "array"
        },
        "profile": {
          "type": [
            "string",
            "null"
          ]
        },
        "vendor": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "device_id",
        "operations"
      ],
      "type": "object"
    }
  },
  {
    "name": "list_resources",
    "description": "List resources in your context. `type` is one of: devices, gateways, incidents, change_managements. Returns compact summaries, capped by limit and filtered by status, name_contains, or — incidents only — device_id and severity. Use get_resource for full detail and describe for a type's fields and filters.",
    "inputSchema": {
      "$defs": {
        "ResourceType": {
          "description": "The resource types the read facade understands.",
          "enum": [
            "devices",
            "gateways",
            "incidents",
            "change_managements"
          ],
          "type": "string"
        }
      },
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "device_id": {
          "description": "Incidents only: incidents concerning this device — its own `device_id` or its\naffected-devices list.",
          "format": "uuid",
          "type": [
            "string",
            "null"
          ]
        },
        "limit": {
          "description": "Max rows to return (default 50, max 200).",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "name_contains": {
          "description": "Case-insensitive substring match on the resource's name, to turn a name into an id.",
          "type": [
            "string",
            "null"
          ]
        },
        "severity": {
          "description": "Incidents only: exact severity — critical, high, medium, low, or info.",
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "description": "Optional status/state filter. Meaning depends on the type (devices/gateways/incidents\nfilter on `status`, change_managements on `state`). Call `describe` for allowed values.",
          "type": [
            "string",
            "null"
          ]
        },
        "type": {
          "$ref": "#/$defs/ResourceType",
          "description": "Which resource type to list."
        }
      },
      "required": [
        "type"
      ],
      "type": "object"
    },
    "outputSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "count": {
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "filter_matched_nothing": {
          "description": "Present only when a filter was supplied and nothing matched: every filter that was\napplied, the value asked for, and — where the field has one — its real vocabulary.\nDistinguishes \"there are none of those\" from \"there is no such value\", which an empty\nlist alone cannot."
        },
        "items": {
          "items": true,
          "type": "array"
        },
        "resource_type": {
          "type": "string"
        },
        "server_time": {
          "description": "The platform's clock, for ageing the timestamps below.",
          "type": "string"
        }
      },
      "required": [
        "resource_type",
        "server_time",
        "count",
        "items"
      ],
      "type": "object"
    }
  },
  {
    "name": "whoami",
    "description": "Report your identity as an MCP service principal and the effective permissions you hold in your context. Call this first to learn what you are allowed to do.",
    "inputSchema": {
      "properties": {},
      "type": "object"
    },
    "outputSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "properties": {
        "context_id": {
          "format": "uuid",
          "type": "string"
        },
        "permissions": {
          "description": "The effective permission names the principal holds in its context (already capped by\nthe delegation ceiling). Lets an agent see what it is allowed to do.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "principal_id": {
          "format": "uuid",
          "type": "string"
        },
        "server_time": {
          "description": "The platform's clock, for ageing any `*_at` you read without guessing what \"now\" is.",
          "type": "string"
        }
      },
      "required": [
        "principal_id",
        "context_id",
        "server_time",
        "permissions"
      ],
      "type": "object"
    }
  }
]