cnc-mcp

List Devices

cnc_list_devices

Read-onlyIdempotent

List network devices with optional filters and paging to discover UUIDs or host names before viewing, updating, or deleting them.

Instructions

List network devices (inventory nodes) with optional filters and paging.

Read-only. Use it to discover device uuids/host names before calling cnc_get_device, cnc_update_device or cnc_delete_device. Filters AND together. Unmanaged devices are hidden in the CNC UI's default table but are returned here.

Args: host_name, reachability, admin_state, credential_profile: exact-match filters (case-insensitive, '*' wildcard). Enum filters accept friendly or wire values. page_size, page: paging (page is 0-based). response_format: 'markdown' (default) or 'json'.

Returns: str: Markdown, one line per device: "host_name (uuid) ip=... reach=... oper=... admin=... profile=... dg=..." plus "More available: page=N." when another page exists. Or JSON: {"total": int|null, "count": int, "page": int, "page_size": int, "has_more": bool, "next_page": int|null, "collection_total": int|null, "items": []} 'total' is the number of matches for the filter (absent when zero matched); 'collection_total' is the size of the whole inventory. On failure: "Error: " (unknown enum value -> the accepted values are listed; 500 'NATS request failed' -> the platform could not parse the request).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`page`	No	0-based page number.
`host_name`	No	Filter by host name: exact match, case-insensitive, '' wildcard (e.g. 'PE1' or 'PE'). No substring match without '*'.
`page_size`	No	Devices per page (e.g. 20).
`admin_state`	No	Filter by admin state: 'up', 'down' or 'unmanaged' (or the wire value, e.g. 'ROBOT_ADMIN_STATE_UP').
`reachability`	No	Filter by reachability: 'reachable', 'unreachable', 'degraded' or 'unknown' (or the wire value, e.g. 'CONN_STATE_REACHABLE').
`response_format`	No	'markdown' for a one-line-per-device summary, 'json' for all fields.	markdown
`credential_profile`	No	Filter by credential profile name (e.g. 'cml-xrd'); '*' wildcard.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 12, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses that filters AND together, that unmanaged devices are included unlike the UI, and documents failure modes with actionable error semantics ('unknown enum value -> accepted values listed', 500 NATS failure meaning). This is unusually rich behavioral context.

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

Conciseness4/5

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

Front-loaded with purpose, usage, then Args/Returns. Well-organized, though the Returns block is long and partially redundant with the existing output schema.

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 7-param, filter-heavy read tool with an output schema, this covers discovery intent, filter combination, visibility caveats, paging, and error behavior comprehensively. Nothing an agent needs to call it correctly 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%, so the parameter descriptions already carry most semantics. The description adds the cross-parameter rule that filters are AND-ed together and repeats the case-insensitive/'*' wildcard and 0-based paging contract, which is useful but largely mirrored in the schema.

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

Purpose5/5

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

States the specific verb+resource ('List network devices (inventory nodes)') plus scope ('optional filters and paging'). It even clarifies that these devices are inventory nodes, distinguishing it from the topology-oriented siblings.

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

Usage Guidelines5/5

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

Explicitly routes the agent: use this to discover uuids/host names before calling cnc_get_device, cnc_update_device or cnc_delete_device. It also warns that unmanaged devices are hidden in the CNC UI default table but returned here, preventing a wrong inference about coverage.

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