gograph

Overview Schema Source Related Servers Discussions Admin

gograph_sql

Read-onlyIdempotent

Returns bounded pages of static PostgreSQL query literals with operation, read/write/DDL access, tables, enclosing function, and source location. Use it to audit database interactions and write paths.

Instructions

Return one bounded gograph.sql.v1 page of static PostgreSQL query literals with operation, read/write/DDL access, referenced tables, enclosing function, module ownership, and source location. Extraction covers direct literals plus statically resolvable local or same-file package const/var declarations, straight-line assignments, and bounded string concatenations. The MCP server checks freshness before this call and refreshes in the current requested analysis mode. Read-only; no side effects. Filters in different categories AND-compose; repeated values within tables, verbs, and accesses OR-compose. Tests remain included by default for backward compatibility; set no_tests=true for production-only results. CTEs resolve to their actual operation, data-modifying CTEs retain write access/table evidence, PostgreSQL UPSERT remains INSERT, and unsupported classification is explicit rather than guessed. WHEN TO USE: Audit database interactions, write paths, or queries touching a table. NOT TO USE: For ORM struct mappings (use gograph_schema) or runtime-generated SQL that is not a static literal. RETURNS: A deterministic page with total/returned/truncated/next_cursor and queries[].

Input Schema

Name	Required	Description
`root`	No	Absolute path of the checkout you are working in (your cwd or git worktree). Must be this server's repository or one of its git worktrees; the answer then comes from that checkout's own graph. A path elsewhere is refused. Alias: cwd. Omit only when the configured checkout is the one you mean.
`term`	No	Optional case-insensitive raw SQL substring filter
`limit`	No	Page size from 1 to 200; defaults to 100
`verbs`	No	Optional PostgreSQL operation filters; values OR-compose
`cursor`	No	Opaque next_cursor from the previous gograph_sql page; reuse the same filters
`module`	No	Optional exact module path/directory, unique nested basename, or repository basename for a root module
`tables`	No	Optional PostgreSQL table selectors; values OR-compose and may be table or schema.table
`accesses`	No	Optional statement access classes; values OR-compose
`function`	No	Optional case-insensitive enclosing-function substring
`no_tests`	No	Exclude SQL facts from *_test.go files; tests are included by default
`intention`	No	Technical rationale, required for analytical calls selecting an active session.
`session_id`	No	Caller selector returned by session_create. Omission means an independent caller; never inherits server environment or another caller's session.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.7.18Nov 5, 2026

addedInput schema / properties / intention

Added value: +{
+  "description": "Technical rationale, required for analytical calls selecting an active session.",
+  "type": "string"
+}

addedInput schema / properties / root

Added value: +{
+  "description": "Absolute path of the checkout you are working in (your cwd or git worktree). Must be this server's repository or one of its git worktrees; the answer then comes from that checkout's own graph. A path elsewhere is refused. Alias: cwd. Omit only when the configured checkout is the one you mean.",
+  "type": "string"
+}

addedInput schema / properties / session_id

Added value: +{
+  "description": "Caller selector returned by session_create. Omission means an independent caller; never inherits server environment or another caller's session.",
+  "type": "string"
+}

Changed10 schema fields changedv1.7.5Oct 3, 2026

addedInput schema / properties / accesses

Added value: +{
+  "description": "Optional statement access classes; values OR-compose",
+  "items": {
+    "enum": [
+      "read",
+      "write",
+      "ddl"
+    ],
+    "type": "string"
+  },
+  "maxItems": 32,
+  "type": "array"
+}

addedInput schema / properties / cursor

Added value: +{
+  "description": "Opaque next_cursor from the previous gograph_sql page; reuse the same filters",
+  "maxLength": 1024,
+  "type": "string"
+}

addedInput schema / properties / function

Added value: +{
+  "description": "Optional case-insensitive enclosing-function substring",
+  "maxLength": 1024,
+  "type": "string"
+}

addedInput schema / properties / limit

Added value: +{
+  "description": "Page size from 1 to 200; defaults to 100",
+  "maximum": 200,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / module

Added value: +{
+  "description": "Optional exact module path/directory, unique nested basename, or repository basename for a root module",
+  "maxLength": 1024,
+  "type": "string"
+}

addedInput schema / properties / no_tests

Added value: +{
+  "description": "Exclude SQL facts from *_test.go files; tests are included by default",
+  "type": "boolean"
+}

addedInput schema / properties / tables

Added value: +{
+  "description": "Optional PostgreSQL table selectors; values OR-compose and may be table or schema.table",
+  "items": {
+    "maxLength": 256,
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 32,
+  "type": "array"
+}

changedInput schema / properties / term / description

Previous value: -"Optional SQL keyword or table name to filter database queries (e.g., 'SELECT', 'users')"New value: +"Optional case-insensitive raw SQL substring filter"

addedInput schema / properties / term / maxLength
```
Added value: +4096
```

addedInput schema / properties / verbs

Added value: +{
+  "description": "Optional PostgreSQL operation filters; values OR-compose",
+  "items": {
+    "enum": [
+      "SELECT",
+      "INSERT",
+      "UPDATE",
+      "DELETE",
+      "MERGE",
+      "CREATE",
+      "ALTER",
+      "DROP",
+      "TRUNCATE"
+    ],
+    "type": "string"
+  },
+  "maxItems": 32,
+  "type": "array"
+}

Changed1 schema field changedv1.4.70May 25, 2026

changedInput schema / properties / term / description

Previous value: -"Optional string to filter the queries"New value: +"Optional SQL keyword or table name to filter database queries (e.g., 'SELECT', 'users')"

First observedv1.0.0May 25, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare read-only, non-destructive, idempotent, closed-world, and the description corroborates rather than contradicts them. Beyond that it discloses non-obvious behavior: server-side freshness checks and mode-specific refresh before the call, CTE resolution to the real operation, data-modifying CTEs retaining write evidence, UPSERT normalized to INSERT, and explicit rather than guessed classification for unsupported cases.

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?

Purpose is front-loaded and labeled sections (WHEN TO USE / NOT TO USE / RETURNS) make scanning easy; nearly every clause carries information. The extraction-coverage sentence is dense and run-on, bundling several distinct behaviors into one long clause, which slightly hurts legibility.

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 12-parameter tool with no output schema, the definition still describes the return envelope (total/returned/truncated/next_cursor plus queries[]) and the paging contract via cursor. Combined with the extraction-scope and filter-composition rules, an agent has everything needed to call it and interpret results.

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 schema already documents each parameter, but the description adds cross-parameter semantics the schema does not state: filters in different categories AND-compose while repeated values within tables/verbs/accesses OR-compose, and no_tests exists only for backward-compatible defaults. It also implies cursor reuse must preserve the same filters, though it does not restate the extraction-scope limits (straight-line assignments, bounded concatenation) per parameter.

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 ('Return one bounded gograph.sql.v1 page of static PostgreSQL query literals') and enumerates exactly what each result carries: operation, access class, tables, enclosing function, module, source location. It also explicitly distinguishes itself from gograph_schema, so an agent can route correctly without opening a 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?

Provides explicit 'WHEN TO USE' (auditing DB interactions, write paths, queries touching a table) and 'NOT TO USE' with named alternatives (gograph_schema for ORM struct mappings, and a stated exclusion for runtime-generated SQL). This is exactly the when/when-not/alternative structure the top score requires.

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

Deploy Server

gograph_sql

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools