Skip to main content
Glama

pg-aiguide

by io.github.timescale
OverviewDiscussionsAdmin

Server Details

Comprehensive PostgreSQL documentation and best practices, including ecosystem tools

If you are the author of this connector, you can claim ownership by verifying the domain or GitHub account it belongs to. Claimed connector authors can inspect health checks, view analytics, and manage their listing.
Status
Healthy
Uptime
99.9% over 46 days
Last Tested
Transport
Streamable HTTP · MCP 2025-11-25
URL
Repository
timescale/pg-aiguide
GitHub Stars
1,852
Server Listing
pg-aiguide

TDQS

A3.7/5.0

Scored across 2 tools

Disambiguation5/5

The two tools serve clearly distinct purposes: search_docs performs hybrid semantic/keyword search across documentation, while view_skill retrieves a specific skill by name. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern (search_docs, view_skill), making the API predictable and easy to understand.

Tool Count3/5

With only 2 tools, the surface feels thin for a documentation/guide server. While the scope is narrow, it might benefit from additional operations like listing available skills or browsing categories.

Completeness2/5

The tool set lacks a way to discover what skills are available; view_skill assumes knowledge of skill names, and search_docs only searches documentation, not skills. This creates a significant gap for agents trying to navigate the guide content.

Available Tools

2 tools
search_docsSearch DocumentationA
Read-onlyIdempotent
Inspect

Search documentation with hybrid semantic (vector) and keyword (BM25) search. Use semanticWeight to choose keyword-only (0), semantic-only (1), or a blend; mid values fuse rankings with RRF. Supports Tiger Cloud (TimescaleDB), PostgreSQL, and PostGIS.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitYesThe maximum number of matches to return. Defaults to 20.
queryYesThe search query. Used for BM25 when keyword or hybrid search applies, and for the embedding when semantic or hybrid search applies.
sourceYesThe documentation source to search. "tiger" for Tiger Cloud and TimescaleDB, "postgres" for PostgreSQL, "postgis" for PostGIS spatial extension. Specific versions provided with _X.X suffixes.
semanticWeightYesControls the balance between semantic and keyword search. 0 = keyword only, 0.5 = equal mix, 1 = semantic only. Default is 0.7 (favor semantic search).

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultsYes

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations (readOnly, idempotent), the description discloses the hybrid search mechanism, BM25, semantic vectors, RRF fusion for mid values, and supported database platforms. This adds substantial behavioral context without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose, and every piece of information earns its place. No fluff or redundancy.

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?

Given the presence of an output schema and detailed annotations, the description sufficiently covers the tool's functionality, parameter tuning, and supported sources. It does not need to detail return values since the output schema exists.

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?

The schema already covers all parameters, but the description adds meaning by explaining the semanticWeight scale and that query is used for both BM25 and embedding where relevant. This goes beyond simple parameter names.

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 clearly states the tool searches documentation using hybrid semantic and keyword search, which is a specific verb+resource combination. It also distinguishes from the sibling tool view_skill by focusing on search rather than viewing.

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 description provides explicit guidance on using semanticWeight values (0, 1, blend) and lists supported sources. However, it does not explicitly contrast with view_skill or state when not to use this tool, so it lacks full alternative guidance.

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

view_skillView SkillB
Read-onlyIdempotent
Inspect

Retrieve detailed skills for TimescaleDB operations and best practices.

Available Skills

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesA relative path to a file or directory within the skill to view. If empty, will view the `SKILL.md` file by default. Use `.` to list the root directory of the skill.
skill_nameYesThe name of the skill to browse, or `.` to list all available skills.

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYesThe content of the file or directory listing.

TDQS

B3.3/5.0
Behavior3/5

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

Annotations already provide readOnlyHint=true and idempotentHint=true, so the read-only safety profile is covered. The description adds some context by naming the content domain (TimescaleDB operations) and listing available skills, but it does not disclose behavior beyond annotations, such as how path resolution works or what the returned structure looks like. It does not contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely long, dominated by a large catalog of skills with verbose trigger conditions and keywords. While this content is useful, it is not concise and pushes the actual tool-purpose statement into a tiny fraction of the whole. A shorter pointer to available skills would be more appropriate for a tool definition.

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

Completeness3/5

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

The description plus schema provides enough to invoke the tool correctly: required parameters are covered, available skill values are listed, and annotations plus output schema reduce ambiguity. However, it lacks any statement of how view_skill relates to search_docs, and it never explicitly says it browses skill files/directories. This leaves a gap for an agent deciding between the two tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

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

Although the input schema describes both parameters with 100% coverage, the description adds substantial value by enumerating all available skill_name values with detailed descriptions. This is effectively a dynamic enum for skill_name, which the schema does not provide. The path parameter is not discussed in the description, but the schema already documents its default and '.' behavior thoroughly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific action and resource: 'Retrieve detailed skills for TimescaleDB operations and best practices.' It is clear this tool returns skill content, and the large available-skills list gives concrete examples. However, it does not explicitly differentiate this tool from the sibling search_docs, and 'detailed skills' is slightly ambiguous about browsing files versus returning a catalog.

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

Usage Guidelines2/5

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

There is no guidance on when to use view_skill versus search_docs or any other alternative. The available_skills list explains when to use each skill, but that is content-specific guidance, not guidance about invoking this tool. No exclusions, prerequisites, or routing rules are stated.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool update
    • Changedsearch_docs6 fields changed
      • changedInput schema / properties / limit / description
        Previous value: -"The maximum number of matches to return. If not provided, default is 10."New value: +"The maximum number of matches to return. Defaults to 20."
      • changedInput schema / properties / query / description
        Previous value: -"The search query. For semantic search, use natural language. For keyword search, provide keywords."New value: +"The search query. Used for BM25 when keyword or hybrid search applies, and for the embedding when semantic or hybrid search applies."
      • removedInput schema / properties / search_type
        Removed value: -{
-  "description": "The type of search to perform. \"semantic\" uses natural language vector similarity, \"keyword\" uses BM25 keyword matching.",
-  "enum": [
-    "semantic",
-    "keyword"
-  ],
-  "type": "string"
-}
      • addedInput schema / properties / semanticWeight
        Added value: +{
+  "anyOf": [
+    {
+      "maximum": 1,
+      "minimum": 0,
+      "multipleOf": 0.1,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Controls the balance between semantic and keyword search. 0 = keyword only, 0.5 = equal mix, 1 = semantic only. Default is 0.7 (favor semantic search)."
+}
      • changedInput schema / required
        Previous value: -[
-  "source",
-  "search_type",
-  "query",
-  "limit"
-]New value: +[
+  "source",
+  "query",
+  "limit",
+  "semanticWeight"
+]
      • changedOutput schema / properties / results / items / anyOf
        Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "content": {
-        "description": "The content of the documentation entry.",
-        "type": "string"
-      },
-      "distance": {
-        "description": "The distance score indicating the relevance of the entry to the query. Lower values indicate higher relevance.",
-        "type": "number"
-      },
-      "id": {
-        "description": "The unique identifier of the documentation entry.",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "metadata": {
-        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "id",
-      "content",
-      "metadata",
-      "distance"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "content": {
-        "description": "The content of the documentation entry.",
-        "type": "string"
-      },
-      "id": {
-        "description": "The unique identifier of the documentation entry.",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "metadata": {
-        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
-        "type": "string"
-      },
-      "score": {
-        "description": "The score indicating the relevance of the entry to the keywords. Higher values indicate higher relevance.",
-        "type": "number"
-      }
-    },
-    "required": [
-      "id",
-      "content",
-      "metadata",
-      "score"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "content": {
+        "description": "The content of the documentation entry.",
+        "type": "string"
+      },
+      "distance": {
+        "description": "The distance score indicating the relevance of the entry to the query. Lower values indicate higher relevance.",
+        "type": "number"
+      },
+      "id": {
+        "description": "The unique identifier of the documentation entry.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "metadata": {
+        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "content",
+      "metadata",
+      "distance"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "content": {
+        "description": "The content of the documentation entry.",
+        "type": "string"
+      },
+      "id": {
+        "description": "The unique identifier of the documentation entry.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "metadata": {
+        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
+        "type": "string"
+      },
+      "score": {
+        "description": "The score indicating the relevance of the entry to the keywords. Higher values indicate higher relevance.",
+        "type": "number"
+      }
+    },
+    "required": [
+      "id",
+      "content",
+      "metadata",
+      "score"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "content": {
+        "description": "The content of the documentation entry.",
+        "type": "string"
+      },
+      "id": {
+        "description": "The unique identifier of the documentation entry.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "metadata": {
+        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
+        "type": "string"
+      },
+      "rrf_score": {
+        "description": "Hybrid search: fused RRF score from combining semantic and keyword result rankings.",
+        "type": "number"
+      }
+    },
+    "required": [
+      "id",
+      "content",
+      "metadata",
+      "rrf_score"
+    ],
+    "type": "object"
+  }
+]
  2. 1 tool update
    • Changedsearch_docs9 fields changed
      • addedInput schema / properties / limit / anyOf
        Added value: +[
+  {
+    "maximum": 9007199254740991,
+    "minimum": -9007199254740991,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]
      • changedInput schema / properties / limit / description
        Previous value: -"The maximum number of matches to return. Default is 10."New value: +"The maximum number of matches to return. If not provided, default is 10."
      • removedInput schema / properties / limit / maximum
        Removed value: -9007199254740991
      • removedInput schema / properties / limit / minimum
        Removed value: --9007199254740991
      • removedInput schema / properties / limit / type
        Removed value: -"integer"
      • changedInput schema / properties / source / description
        Previous value: -"The documentation source to search. \"tiger\" for Tiger Cloud and TimescaleDB, \"postgres\" for PostgreSQL, \"postgis\" for PostGIS spatial extension."New value: +"The documentation source to search. \"tiger\" for Tiger Cloud and TimescaleDB, \"postgres\" for PostgreSQL, \"postgis\" for PostGIS spatial extension. Specific versions provided with _X.X suffixes."
      • changedInput schema / properties / source / enum
        Previous value: -[
-  "tiger",
-  "postgres",
-  "postgis"
-]New value: +[
+  "tiger",
+  "postgres_14",
+  "postgres_15",
+  "postgres_16",
+  "postgres_17",
+  "postgres_18",
+  "postgis_3.3",
+  "postgis_3.4",
+  "postgis_3.5",
+  "postgis_3.6"
+]
      • removedInput schema / properties / version
        Removed value: -{
-  "anyOf": [
-    {
-      "enum": [
-        "14",
-        "15",
-        "16",
-        "17",
-        "18",
-        "latest"
-      ],
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "The PostgreSQL major version (ignored when searching \"tiger\"). Recommended to assume the latest version if unknown. Only applicable when source is Postgres. Defaults to latest version."
-}
      • changedInput schema / required
        Previous value: -[
-  "source",
-  "search_type",
-  "query",
-  "version",
-  "limit"
-]New value: +[
+  "source",
+  "search_type",
+  "query",
+  "limit"
+]
  3. 2 tool updates
    • Changedsearch_docs4 fields changed
      • removedInput schema / additionalProperties
        Removed value: -false
      • addedInput schema / properties / limit / maximum
        Added value: +9007199254740991
      • addedInput schema / properties / limit / minimum
        Added value: +-9007199254740991
      • changedOutput schema / properties / results / items / anyOf
        Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "content": {
-        "description": "The content of the documentation entry.",
-        "type": "string"
-      },
-      "distance": {
-        "description": "The distance score indicating the relevance of the entry to the query. Lower values indicate higher relevance.",
-        "type": "number"
-      },
-      "id": {
-        "description": "The unique identifier of the documentation entry.",
-        "type": "integer"
-      },
-      "metadata": {
-        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "id",
-      "content",
-      "metadata",
-      "distance"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "content": {
-        "$ref": "#/properties/results/items/anyOf/0/properties/content"
-      },
-      "id": {
-        "$ref": "#/properties/results/items/anyOf/0/properties/id"
-      },
-      "metadata": {
-        "$ref": "#/properties/results/items/anyOf/0/properties/metadata"
-      },
-      "score": {
-        "description": "The score indicating the relevance of the entry to the keywords. Higher values indicate higher relevance.",
-        "type": "number"
-      }
-    },
-    "required": [
-      "id",
-      "content",
-      "metadata",
-      "score"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "content": {
+        "description": "The content of the documentation entry.",
+        "type": "string"
+      },
+      "distance": {
+        "description": "The distance score indicating the relevance of the entry to the query. Lower values indicate higher relevance.",
+        "type": "number"
+      },
+      "id": {
+        "description": "The unique identifier of the documentation entry.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "metadata": {
+        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "content",
+      "metadata",
+      "distance"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "content": {
+        "description": "The content of the documentation entry.",
+        "type": "string"
+      },
+      "id": {
+        "description": "The unique identifier of the documentation entry.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "metadata": {
+        "description": "Additional metadata about the documentation entry, as a JSON encoded string.",
+        "type": "string"
+      },
+      "score": {
+        "description": "The score indicating the relevance of the entry to the keywords. Higher values indicate higher relevance.",
+        "type": "number"
+      }
+    },
+    "required": [
+      "id",
+      "content",
+      "metadata",
+      "score"
+    ],
+    "type": "object"
+  }
+]
    • Changedview_skill1 field changed
      • removedInput schema / additionalProperties
        Removed value: -false
  4. 1 tool update
    • Changedsearch_docs4 fields changed
      • addedInput schema / properties / version / anyOf
        Added value: +[
+  {
+    "enum": [
+      "14",
+      "15",
+      "16",
+      "17",
+      "18",
+      "latest"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
      • changedInput schema / properties / version / description
        Previous value: -"The PostgreSQL major version (ignored when searching \"tiger\"). Recommended to assume the latest version if unknown."New value: +"The PostgreSQL major version (ignored when searching \"tiger\"). Recommended to assume the latest version if unknown. Only applicable when source is Postgres. Defaults to latest version."
      • removedInput schema / properties / version / enum
        Removed value: -[
-  "14",
-  "15",
-  "16",
-  "17",
-  "18",
-  "latest"
-]
      • removedInput schema / properties / version / type
        Removed value: -"string"
  5. 1 tool update
    • Changedsearch_docs2 fields changed
      • changedInput schema / properties / source / description
        Previous value: -"The documentation source to search. \"tiger\" for Tiger Cloud and TimescaleDB, \"postgres\" for PostgreSQL."New value: +"The documentation source to search. \"tiger\" for Tiger Cloud and TimescaleDB, \"postgres\" for PostgreSQL, \"postgis\" for PostGIS spatial extension."
      • changedInput schema / properties / source / enum
        Previous value: -[
-  "tiger",
-  "postgres"
-]New value: +[
+  "tiger",
+  "postgres",
+  "postgis"
+]
  6. 2 tool updates
    • First observedsearch_docs
    • First observedview_skill

Related MCP Connectors

Related MCP Servers

  • postgres-mcp-server

    mukul975
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables AI assistants to manage, monitor, and optimize PostgreSQL databases with over 200 specialized tools for operations, security, performance tuning, and diagnostics.
    23 npm
    9
    MIT

  • Postgres MCP Pro

    BACH-AI-Tools
    A
    license
    B
    quality
    D
    maintenance
    Enables comprehensive PostgreSQL database management including index tuning, query plan analysis, health monitoring, schema-aware SQL generation, and safe SQL execution with configurable access control for both development and production environments.
    9
    MIT

  • MCP PostgreSQL Operations

    call518
    A
    license
    A
    quality
    B
    maintenance
    Enables comprehensive PostgreSQL database monitoring, analysis, and management through natural language queries. Provides performance insights, bloat analysis, vacuum monitoring, and intelligent maintenance recommendations across PostgreSQL versions 12-17.
    34
    160
    MIT

  • PostgreSQL MCP Server

    jamesjohnsdev
    A
    license
    B
    quality
    F
    maintenance
    Facilitates management and optimization of PostgreSQL databases, offering analysis, setup guidance, and debugging, while ensuring secure and efficient database operations.
    3
    8 npm
    23
    AGPL 3.0
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources