Skip to main content
Glama
J-MaFf

s2-netbox-mcp

by J-MaFf
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

get_portals

Lists portals (doors) and their nested readers from NetBox. Supports pagination via STARTFROMKEY/NEXTKEY and resolves reader descriptions by default (RESOLVEDESCRIPTIONS).

Instructions

Lists portals (doors) configured on the NetBox system, each with its nested readers (wraps NBAPI GetPortals, paginated via STARTFROMKEY/NEXTKEY — there is no single-portal filter). RESOLVEDESCRIPTIONS defaults to true — an inverted, opt-out default (unlike most optional booleans in this codebase): GetPortals never populates a nested reader's own DESCRIPTION field (only READERKEY/NAME/PORTALORDER), so this fills it in directly on each nested reader via one GetReaders full-table fetch per call (not per portal/reader). Set RESOLVEDESCRIPTIONS: false to return readers exactly as GetPortals provides them, with no DESCRIPTION field and no GetReaders call.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
STARTFROMKEYNoOptional. Pagination cursor — the NEXTKEY from a previous call, to continue listing.
RESOLVEDESCRIPTIONSNoOptional (default true — on by default; the inverse of this codebase's usual optional-boolean default). Fills in each nested reader's own DESCRIPTION field (GetPortals leaves it unpopulated) via one GetReaders full-table fetch per call (not per portal/reader). Set to false to skip it and return readers exactly as GetPortals provides them.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.3.0
    • addedInput schema / properties / RESOLVEDESCRIPTIONS
      Added value: +{
+  "description": "Optional (default true — on by default; the inverse of this codebase's usual optional-boolean default). Fills in each nested reader's own DESCRIPTION field (GetPortals leaves it unpopulated) via one GetReaders full-table fetch per call (not per portal/reader). Set to false to skip it and return readers exactly as GetPortals provides them.",
+  "type": "boolean"
+}
  2. First observedv0.2.3

TDQS

A4.3/5.0
Behavior5/5

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

With no annotations, the description carries the full burden of behavioral disclosure, and it does so excellently. It exposes pagination via STARTFROMKEY/NEXTKEY, the surprising inverted default of RESOLVEDESCRIPTIONS, the fact that GetPortals leaves DESCRIPTION unpopulated, and the extra GetReaders full-table fetch cost per call.

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 description is dense but information-rich, front-loading the core purpose and pagination behavior. The second sentence packs several important caveats into one long clause; although everything earns its place, it could be structured slightly more cleanly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description covers the critical behaviors well: pagination, the single-portal limitation, the default behavior, and the extra fetch cost. It is slightly incomplete on the exact return shape for portal objects, though nested reader fields are partially described.

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% and the schema already documents both parameters, including the RESOLVEDESCRIPTIONS default and behavior. The tool description mostly restates this same information, so it adds little semantic value beyond what the schema provides.

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 states a specific verb and resource: 'Lists portals (doors) configured on the NetBox system, each with its nested readers.' It also distinguishes this list-style call from single-portal access by stating 'there is no single-portal filter,' which differentiates it from sibling tools like get_portal.

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

Usage Guidelines4/5

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

It gives clear context for when to use the tool: for listing all portals with nested readers, with no single-portal filter available. It also gives explicit guidance on when to set RESOLVEDESCRIPTIONS to false. However, it does not explicitly name alternatives or state when to prefer find_portals or get_portal.

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

Deploy Server

Other Tools