Skip to main content
Glama
darrenjrobinson

graph-atlas-mcp

by darrenjrobinson
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

expand_schema_node

Expand one schema graph node to return a mergeable nodes/edges delta for canvas visualization, revealing entity neighborhoods, touching permissions, and granting roles.

Instructions

Expand one node of the schema graph and return a {nodes, edges, message} delta to merge into the canvas — the interactive companion to visualize_schema_graph. kind="EntityType" with view="entity" returns the schema neighborhood (navigation targets, base type, referrers); with view="permission" the permissions that touch the entity; with view="role" those permissions plus the roles granting them (heuristic role map). kind="Permission" returns touched entities plus the roles granting it. kind="Role" returns granted permissions and their entities.

Input Schema

NameRequiredDescriptionDefault
kindYes
viewNoSteers EntityType expansion: schema neighborhood vs permission usageentity
sinceNoChange-activity window — ISO date or day count (e.g. "30")
node_idYesNode id — a lowercase entity type, or a permission or role name (casing ignored)
endpointNoOnly applies to EntityType schema neighborhoodsv1.0

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2026.10.23
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  2. Changed1 schema field changedv0.1.3
    • changedInput schema / properties / node_id / description
      Previous value: -"Node id — lowercase entity type, permission name, or role name"New value: +"Node id — a lowercase entity type, or a permission or role name (casing ignored)"
  3. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations, the description carries the burden and does reasonably well: it discloses the delta-merge return contract, warns that the role map is a 'heuristic', and scopes `endpoint` to EntityType neighborhoods only. It does not state that expansion is a read-only/no-side-effect operation or discuss failure modes, which leaves a gap.

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 and return shape, then a compact per-kind enumeration. It is dense but every clause conveys distinct behavior; only slight tightening (e.g., the parenthetical heuristic caveat) would be possible.

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?

No output schema exists, so the description must carry return semantics — it does so via the {nodes, edges, message} contract and per-kind results. What the 'message' field contains and how the delta reconciles with existing canvas state remain unspecified, a minor residual gap for a 5-parameter tool.

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 80% (baseline 3), and the description goes beyond the schema by explaining the kind×view interaction — e.g. view='permission' yields 'permissions that touch the entity' and view='role' adds granting roles. This is genuine semantic value the enum descriptions alone don't convey.

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 ('expand one node of the schema graph'), names the return payload ({nodes, edges, message} delta), and explicitly positions itself as the interactive companion to visualize_schema_graph. The per-kind breakdown lets an agent distinguish exact behavior without opening the schema.

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?

The 'interactive companion to visualize_schema_graph' framing tells the agent this is the incremental-expansion path versus full-graph visualization, and each kind/view combination is mapped to a described outcome. It stops short of explicit when-not guidance (e.g., when to prefer get_permission_context for permission questions).

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