cnc-mcp

Get Topology Graph

cnc_get_topology

Read-onlyIdempotent

Retrieve a paginated, read-only logical topology graph with nodes and links to inspect node-to-node adjacency, such as finding what a device connects to.

Instructions

Get the topology graph: one page of nodes plus one page of links (edges).

Read-only. Crosswork returns the whole graph (up to maxLogicalNodes, 5000 on the lab instance) in one response with no server-side paging, so this tool re-downloads the graph on every call and pages BOTH lists client-side: page/page_size window the links, node_page/ node_page_size window the nodes. Each link carries both endpoints resolved (node UUID, node name, interface), so a links page is self-contained — you do not need the nodes page to read adjacency. Use it for node-to-node adjacency (e.g. "what is PE1 connected to?"); for tabular attributes (IPs, reachability, link status/utilisation) prefer cnc_list_topology_nodes / cnc_list_topology_links. Keep page sizes modest: the response is capped at the configured size limit.

Args: map_type: 'logical' only ('geo' is rejected with an explanation). page_size: links per page (1-500). page: 0-based page of links. node_page_size: nodes per page (1-1000). node_page: 0-based page of nodes. response_format: markdown (default) or json.

Returns: str: Markdown listing nodes then "A:ifA <-> B:ifB" per link, or JSON: {"map_type": "LOGICAL", "attributes": {"totalNodes": int, ...}, "nodes": {"total": int, "count": int, "page": int, "page_size": int, "items": [{"uuid": str, "name": str}], "has_more": bool, "next_page": int|null, ...}, "links": {"total": int, "count": int, "page": int, "page_size": int, "items": [{"uuid": str, "name": "-", "source": {"node_uuid": str, "node_name": str, "interface": str}, "target": {"node_uuid": str, "node_name": str, "interface": str}}], "has_more": bool, "next_page": int|null, ...}} Node icon/checksum attributes and edge decoration attributes (the only attributes the platform returns on /data) are dropped. On failure: "Error: ". An HTTP 500 "Internal Server Error" from /v1/topology-service/... means the service rejected the request body (mapType/viewId/params) — deterministic, do NOT retry. (It is not the inventory's "NATS request failed" signal.)

Input Schema

TableJSON Schema

Name	Required	Description	Default
`page`	No	0-based page of links.
`map_type`	No	Map to read. Only 'logical' (default; wire value 'LOGICAL') is supported — 'geo' is rejected because the platform answers HTTP 500 for it.	logical
`node_page`	No	0-based page of nodes.
`page_size`	No	Links per page (client-side paging).
`node_page_size`	No	Nodes per page (client-side paging).
`response_format`	No	'markdown' for human-readable output, 'json' for complete data.	markdown

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?

Far beyond the annotations: it discloses that Crosswork returns the whole graph with no server-side paging, so every call re-downloads and pages client-side, that link endpoints are pre-resolved so a links page is self-contained, that icon/checksum and edge-decoration attributes are dropped, and that an HTTP 500 is deterministic and must not be retried.

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

Conciseness4/5

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

Front-loaded with the core fact and cleanly sectioned into Args/Returns/error handling. The verbose JSON return-shape listing is somewhat redundant against the existing output schema, which costs it a point, but little of the prose is filler.

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 6-parameter read tool with annotations and an output schema, the description still supplies the non-obvious operational context: client-side paging rationale, endpoint resolution, dropped attributes, page-size limits, and the deterministic-500 error contract.

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 already 100%, so the baseline is 3, but the description adds the cross-parameter model — that page/page_size window links while node_page/node_page_size window nodes, and that map_type accepts only 'logical'. This explains the interaction between parameters rather than just restating them.

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 opening line gives a precise verb and resource plus the exact shape of the payload ('one page of nodes plus one page of links'). It explicitly distinguishes itself from the sibling tools cnc_list_topology_nodes / cnc_list_topology_links by naming them and the attribute category each covers.

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 use case with a concrete example ('what is PE1 connected to?') and gives an explicit when-not with the alternative tools for tabular attributes. It also adds a sizing caveat ('keep page sizes modest') that shapes invocation.

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