cnc-mcp

List Inventory Jobs

cnc_list_inventory_jobs

Read-onlyIdempotent

List read-only inventory job history from Cisco Crosswork to review recent device, credential, provider, and tag writes. Find a lost job_id, then inspect or wait on it.

Instructions

List inventory jobs — the audit trail of every device, credential, provider and tag write on Crosswork (each write returns one job).

Read-only. Use it to review recent changes or to find the job_id of a write whose result was lost, then inspect one with cnc_get_inventory_job or wait for it with cnc_wait_for_inventory_job. Paged with the inventory filterData.PageSize/PageNum grammar (assumed for this endpoint; 'total' is null when the platform reports no result_count, and 'has_more' then means the page came back full).

Args: page_size / page: page size and 0-based page number.

Returns: str: Markdown listing, or JSON: {"total": int|null, "count": int, "page": int, "page_size": int, "items": [{"job_id": str, "state": str, "type": str, "creation_time": str, "completion_time": str, "created_by": str, "impacted": [str, ...], "error": str}, ...], "has_more": bool, "next_page": int|null, "collection_total": int|null} States: JOB_COMPLETED and JOB_COMPLETED_WITH_WARNING (a success with an advisory in "error", e.g. a no-op or partially applied write), JOB_FAILED / JOB_CANCELLED / JOB_ABORTED (unsuccessful), JOB_RUNNING and other in-progress states. On failure: "Error: ".

Input Schema

TableJSON Schema

Name	Required	Description	Default
`page`	No	0-based page number (e.g. 0).
`page_size`	No	Jobs per page (e.g. 20).
`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.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint/idempotentHint and no destruction, but the description adds real behavioral context: pagination grammar, the fact that 'total' is null when the platform reports no result_count, and that 'has_more' then means the page came back full. It also interprets job states (e.g. COMPLETED_WITH_WARNING is a success with an advisory in 'error') and failure format. The bulk of the return-value detail, however, overlaps the output schema.

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, scope, and routing in the first two paragraphs, and the hedging on the pagination grammar ('assumed for this endpoint') is honest. It is somewhat over-long, however: the full Returns JSON shape duplicates information already present in the 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 paged, read-only list endpoint, the definition covers purpose, routing alternatives, pagination caveats, item fields, state interpretation, and failure output. An output schema exists, so the return-shape narration is bonus rather than a gap, and 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.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents page, page_size and response_format. The description's Args line ('page_size / page: page size and 0-based page number') merely restates the schema, adding no new syntax or constraints — baseline 3.

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 a specific verb and resource plus its exact scope: 'the audit trail of every device, credential, provider and tag write on Crosswork (each write returns one job).' This clearly separates it from the singular cnc_get_inventory_job and the blocking cnc_wait_for_inventory_job.

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 names two use cases ('review recent changes' and 'find the job_id of a write whose result was lost') and routes the agent to the correct follow-up tools (cnc_get_inventory_job, cnc_wait_for_inventory_job) with the condition for each.

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