Skip to main content
Glama
ozgurcd

gograph

by ozgurcd
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

gograph_routes

Read-onlyIdempotent

List a bounded page of HTTP routes with methods, URL patterns, handlers, and source locations in Go code. Use it to inventory a service or find a route before tracing its call chain.

Instructions

List a deterministic bounded page of HTTP routes with methods, URL patterns, handler names, and source locations. Production routes are returned by default; include_tests=true adds *_test.go registrations. Optional term matches method/path, handler, or file. module selects an exact module path/directory, a unique nested-module directory basename, or the repository directory name for a root module. limit defaults to 100 and is restricted to 1-200; next_cursor continues the same filtered census. Each page is also bounded to 64 KiB so the result stays directly consumable instead of spilling to an out-of-band file. Constant nested Gin/Echo/Fiber Group prefixes and Chi Route closure prefixes are composed; Gin/Fiber use the final variadic argument as the terminal handler, while Echo uses the handler immediately after the path. Dynamically computed prefixes remain unresolved. The MCP server refreshes source analysis before this call. Read-only; no side effects. WHEN TO USE: To inventory one service/module or find a route before gograph_endpoint. NOT TO USE: For a handler's downstream call chain (use gograph_endpoint). RETURNS: gograph.routes.v1 JSON with total, returned, truncated, routes[], and next_cursor when more matches exist.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
termNoOptional case-insensitive substring matched against method/path, handler, or file
limitNoMaximum rows in this page, 1-200 (default: 100); the 64 KiB byte budget may return fewer
cursorNoOpaque next_cursor from the previous gograph_routes result; reuse the same filters
moduleNoOptional exact module path/directory, unique nested-module directory basename, or repository directory name for a root module (for example identuum-idp)
include_testsNoInclude routes registered in *_test.go files; false by default

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv1.7.5
    • addedInput schema / properties / cursor
      Added value: +{
+  "description": "Opaque next_cursor from the previous gograph_routes result; reuse the same filters",
+  "type": "string"
+}
    • addedInput schema / properties / include_tests
      Added value: +{
+  "description": "Include routes registered in *_test.go files; false by default",
+  "type": "boolean"
+}
    • addedInput schema / properties / limit
      Added value: +{
+  "description": "Maximum rows in this page, 1-200 (default: 100); the 64 KiB byte budget may return fewer",
+  "type": "integer"
+}
    • addedInput schema / properties / module
      Added value: +{
+  "description": "Optional exact module path/directory, unique nested-module directory basename, or repository directory name for a root module (for example identuum-idp)",
+  "type": "string"
+}
    • addedInput schema / properties / term
      Added value: +{
+  "description": "Optional case-insensitive substring matched against method/path, handler, or file",
+  "type": "string"
+}
  2. Addedv1.5.3
  3. Removedv1.5.3
  4. First observedv1.0.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already cover readOnly/idempotent/no-destructive, so the bar is lower, yet the description adds substantial non-annotation behavior: the server refreshes source analysis before the call, pages are capped at 64 KiB to avoid spilling to an out-of-band file, Gin/Fiber vs Echo handler-resolution rules differ, constant Group/Route prefixes are composed, and dynamic prefixes stay unresolved. These are real operational traits an agent cannot infer from the schema or hints.

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, then caveats, then WHEN TO USE/NOT TO USE and RETURNS. Dense but every sentence carries information; the framework-specific handler-resolution detail is the only passage bordering on over-explanation for a listing tool.

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?

No output schema exists, so the description compensates by naming the gograph.routes.v1 payload shape (total, returned, truncated, routes[], next_cursor). Combined with pagination limits, test inclusion, and module resolution semantics, an agent has everything needed to call it correctly.

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 baseline is 3; the description goes slightly beyond by framing cursor reuse as continuing the 'same filtered census' and explaining that limit interacts with the 64 KiB byte budget (the page may return fewer than limit rows). Most param text overlaps the schema, so it is not a full 5.

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?

Specific verb (List) + resource (HTTP routes) + explicit scope (deterministic bounded page) with the returned fields enumerated. The WHEN TO USE / NOT TO USE block names gograph_endpoint as the sibling for downstream call chains, so an agent can distinguish it from the surrounding gograph_* tools without opening any schema.

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?

Contains an explicit WHEN TO USE (inventory one service/module, find a route before gograph_endpoint) and NOT TO USE (handler downstream call chain → use gograph_endpoint). The condition selecting the alternative is stated, not implied.

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