Provides comprehensive PostgreSQL database management tools including schema inspection, SQL execution, query explanation with EXPLAIN plans, index tuning recommendations, workload analysis, and database health checks with support for pg_stat_statements and hypopg extensions.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pgsql-mcp show me the top 5 slowest queries from the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pgsql-mcp gives MCP clients safe PostgreSQL inspection, bounded SQL, reviewed changes, and operational diagnostics.
The server starts in restricted mode. Write tools require an explicit unrestricted configuration.
Control | Behavior | Evidence |
Safe default | Restricted mode permits bounded read operations | Database read-only transactions and SQL validation |
Reviewed change | Migration and maintenance plans require a review hash | Durable ledgers and commit guards |
Bounded output | Public tools apply row, time, and result limits | Server-side cursors and hard ceilings |
Broad catalog | Core catalogs expose relations, types, extensions, and providers | OID-backed identities and deterministic results |
Release quality | Main commits run the complete quality system | Tests, coverage, mutation, stress, and compatibility jobs |
Related MCP server: PostgreSQL MCP Server
Use a dedicated PostgreSQL role with the minimum required privileges.
Use stdio for local clients when possible. Put remote transports behind authentication and transport encryption.
Read the security model before production use.
Set a read-only database URI.
DATABASE_URI='postgresql://readonly_user:password@localhost:5432/app' \
uvx pgsql-mcpUse unrestricted mode only for a controlled environment.
DATABASE_URI='postgresql://developer:password@localhost:5432/app_dev' \
uvx pgsql-mcp --access-mode=unrestrictedDo not use a production owner or superuser role.
{
"mcpServers": {
"postgres": {
"command": "uvx",
"args": ["pgsql-mcp"],
"env": {
"DATABASE_URI": "postgresql://readonly_user:password@localhost:5432/app"
}
}
}
}docker run -i --rm \
-e DATABASE_URI='postgresql://readonly_user:password@host.docker.internal:5432/app' \
pgsql-mcpCommand | Scope | Pool | Write access |
| Full catalog, SQL, diagnostics, and reviewed changes | Configured pool | Explicit unrestricted mode |
| Six focused read-only tools | Two connections | No |
| Replication and failover inspection | Focused pool | No |
Inspect schemas, relations, routines, types, privileges, policies, and partitions.
Search trusted PostgreSQL catalogs.
Report installed and available extension profiles.
Inventory objects that belong to an installed extension.
Report PostGIS columns and spatial indexes.
Report pgvector columns and indexes.
Report provider capabilities without reading secrets.
Inspect replication topology and failover readiness.
Execute one bounded read-only SQL statement.
Bind values with native PostgreSQL parameters.
Select typed pages with stable keyset pagination.
Insert, upsert, update, and delete rows with commit guards.
Execute guarded atomic transactions in unrestricted mode.
Create and hash transactional migration plans.
Apply and roll back reviewed migrations.
Create and hash nontransactional maintenance plans.
Apply maintenance and reconcile an unknown outcome.
Explain validated queries.
Read bounded workload statistics.
Analyze query and workload index opportunities.
Run database health checks.
Publish privacy-preserving runtime metrics.
Surface | Limit |
Full server rows | 5,000 |
Lite server rows | 500 |
Typed data rows | 500 |
Extension objects | 500 |
PostGIS columns and indexes | 500 combined |
pgvector columns and indexes | 500 combined |
Protected operations also apply query, lock, and idle-transaction timeouts.
The current release scope is ready for trusted internal and operator workflows when all checklist items are true.
Use a dedicated database role.
Keep restricted mode unless a reviewed write workflow is required.
Keep remote transports behind authentication and TLS.
Set explicit row and timeout limits.
Monitor the main branch quality jobs.
Test each upgrade against a disposable PostgreSQL database.
Review production readiness before deployment.
Future roadmap items are not release guarantees. Read the project plan for planned work.
Topic | Guide |
Security and deployment | |
Production review | |
Architecture | |
Compatibility | |
Catalog model | |
Typed data | |
Reviewed changes | |
Extensions | |
High availability | |
Quality system | |
Writing profile |
uv sync --all-extras
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest -v
python scripts/check_ste_docs.py .Run the complete gates locally before merge. GitHub Actions run only after a commit reaches main.
Read CONTRIBUTING.md before you change the project.
Main branch jobs build and validate the package and container. They do not publish artifacts.
Read PUBLISHING.md for the manual release procedure.
MIT
Analyze database health. Valid values: index, connection, vacuum, sequence, replication, buffer, constraint, all; comma-separated values are accepted.
| Name | Required | Description | Default |
|---|---|---|---|
| health_type | No | all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does not mention whether the analysis is read-only, requires special permissions, or has any side effects. The description only states valid input values, omitting important behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences, no redundant information, and directly conveys the tool's purpose and valid inputs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no output schema, the description covers the valid inputs but lacks explanation of the output format or return behavior. It does not indicate whether the tool is safe to run without side effects, which is important for a health analysis tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description adds significant value by listing all valid values for the health_type parameter and noting that comma-separated values are accepted. This clarifies usage beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Analyze database health' and lists valid health types. However, it does not explicitly differentiate from sibling tools like get_runtime_metrics or analyze_workload_indexes, which also analyze database aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It only lists valid values for the health_type parameter without explaining typical use cases or when other tools might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze up to ten SQL queries and recommend indexes
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | dta | |
| queries | Yes | ||
| max_index_size_mb | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does not mention whether the tool is read-only, destructive, requires permissions, or has performance implications. The minimal description leaves the agent without essential safety context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence), but it lacks structure and omits important details. It is front-loaded with the action but incomplete, which reduces its utility for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should specify the return value (e.g., index recommendations). It also fails to cover the three parameters adequately. The tool is one of many, and the description lacks the completeness needed for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain the method enum, the queries array format, or the max_index_size_mb parameter. The phrase 'up to ten SQL queries' hints at the queries parameter but omits critical semantic details needed for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (analyze and recommend), the resource (SQL queries), the output (indexes), and a limit (up to ten). It distinguishes this tool from siblings like explain_query and analyze_workload_indexes by focusing on specific user-supplied queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like analyze_workload_indexes, or any prerequisites or contraindications. The intended context is only implied by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze frequently executed queries and recommend indexes
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | dta | |
| max_index_size_mb | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavior. It only states the action ('analyze' and 'recommend') but omits whether this is read-only, requires permissions, or has side effects. The nature of recommendations (output format, how to apply them) is unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, which is good for front-loading. However, it is too brief for a tool with two parameters and no annotations, sacrificing necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the two unannotated parameters and missing output schema, the description fails to provide sufficient context. It doesn't explain how to interpret recommendations or behave for different method choices, leaving critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of the two parameters ('method' and 'max_index_size_mb'). The agent receives no help understanding what the enum values mean or how to set the size limit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool analyzes frequently executed queries and recommends indexes, using a specific verb and resource. It distinguishes from sibling analyze_query_indexes by implying workload-level analysis rather than per-query, but could be more explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like analyze_query_indexes or get_top_queries. There is no mention of prerequisites, typical use cases, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply an exact reviewed nontransactional maintenance plan
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Stable maintenance operation name | |
| parallel | No | VACUUM parallel workers | |
| operation | Yes | Structured maintenance operation | |
| review_hash | Yes | Exact review hash returned by create_maintenance_plan | |
| schema_name | Yes | Exact target schema | |
| skip_locked | No | Skip relations that cannot be locked immediately | |
| target_name | Yes | Exact relation or index name | |
| index_cleanup | No | VACUUM index cleanup policy | auto |
| timeout_seconds | No | ||
| lock_timeout_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It notes 'nontransactional,' implying individual statements are not wrapped in a transaction, but fails to disclose other behavioral traits such as potential downtime, locking behavior (though hinted by 'skip_locked' and 'lock_timeout_seconds' parameters), required permissions, or whether it is destructive. The description is insufficient for an agent to understand the tool's full impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, well front-loaded with the key action. It avoids fluff, but could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no output schema, and no annotations, the one-sentence description is insufficient. It does not explain what 'nontransactional' implies in practice, the need for a review_hash from create_maintenance_plan, the possible effects of the operation, or how to interpret results. The tool is complex (maintenance operations) and requires more contextual detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80% (8 of 10 parameters have descriptions), so the baseline is 3. The description does not add any additional parameter information beyond the schema. It does not explain how parameters interact or provide usage tips.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Apply an exact reviewed nontransactional maintenance plan,' which clearly indicates it executes a pre-reviewed plan. The verb 'apply' and noun 'maintenance plan' are specific, and it distinguishes from sibling tools like 'create_maintenance_plan' (creation) and 'get_maintenance_status' (status check). However, it does not specify the exact maintenance operations (vacuum, analyze, etc.) that the plan encompasses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., a plan must exist), nor provide when-not-to-use or explicit comparisons to siblings like 'reconcile_maintenance_operation.' The description leaves the agent to infer usage context from the parameter names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a reviewed fully transactional migration and its ledger row atomically
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Stable migration name | |
| steps | Yes | The exact reviewed ordered statement pairs | |
| review_hash | Yes | Exact 64-character review hash from create_migration_plan | |
| timeout_seconds | No | ||
| lock_timeout_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially discloses behavior by stating 'fully transactional' and 'atomically', implying atomic commit/rollback. However, it does not specify whether locks are acquired, what happens on failure, or the effect on the ledger row beyond atomicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the core purpose without extraneous words. It is front-loaded and immediately actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and no annotations, the description is too brief. It fails to explain the review_hash requirement, timeout meaning, or what the tool returns on success/failure, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no detail about parameters (name, steps, review_hash, timeouts) beyond what the schema provides. Schema coverage is 60%, but the description does not compensate for the missing descriptions of timeout_seconds and lock_timeout_seconds.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('apply') and resource ('migration plan'), and adds the qualifiers 'reviewed', 'fully transactional', and 'ledger row atomically', which clearly distinguishes it from siblings like create_migration_plan and rollback_migration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., create_migration_plan, rollback_migration). The description does not mention prerequisites or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a reviewed nontransactional PostgreSQL maintenance plan
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Stable maintenance operation name | |
| parallel | No | VACUUM parallel workers | |
| operation | Yes | Structured maintenance operation | |
| schema_name | Yes | Exact target schema | |
| skip_locked | No | Skip relations that cannot be locked immediately | |
| target_name | Yes | Exact relation or index name | |
| index_cleanup | No | VACUUM index cleanup policy | auto |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions 'nontransactional', hinting at execution context, but fails to explain what 'reviewed' means, whether the plan is saved or returned, or any side effects. The description is too brief to substitute for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, highly concise. While it could include more useful information without becoming verbose, it avoids redundancy and front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no output schema, no annotations) and the presence of many sibling tools, the description is inadequate. It does not explain what a maintenance plan is, how the created plan is used, or what the return value indicates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for each parameter. It does not reference parameters or provide context for their use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and the specific resource 'reviewed nontransactional PostgreSQL maintenance plan', distinguishing it from sibling tools like apply_maintenance_plan which executes plans. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives (e.g., apply_maintenance_plan, get_maintenance_status). While the purpose is clear, the agent is not informed about preconditions or context for choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a deterministic reviewed PostgreSQL migration plan without touching the database
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Stable migration name | |
| steps | Yes | Ordered forward and rollback statement pairs |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explicitly states 'without touching the database', which indicates a safe, non-destructive operation. However, it does not mention potential edge cases or input validation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. Every part of the description contributes to understanding the tool's purpose and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose and side-effect-free nature. However, there is no output schema, and the description does not hint at what the tool returns, leaving some ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and parameters are well-documented in the schema. The description adds no extra meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create', the resource 'migration plan', and key characteristics ('deterministic', 'reviewed', 'without touching the database'). This distinguishes it from siblings like apply_migration_plan which modifies the database.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for planning migrations before applying, and the sibling context includes apply_migration_plan and execute_sql, but it lacks explicit when-not-to-use or alternative suggestions for 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete rows with mandatory filters, optimistic predicates, and commit guards
| Name | Required | Description | Default |
|---|---|---|---|
| where | Yes | Mandatory structured target filter | |
| returning | No | Columns returned after commit validation | |
| concurrency | No | Optional optimistic concurrency predicates | |
| schema_name | Yes | Exact schema name | |
| expected_rows | No | Optional exact affected row count | |
| relation_name | Yes | Exact table name | |
| max_affected_rows | No | Hard mutation ceiling |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral disclosure burden. It mentions mandatory filters, optimistic predicates, and commit guards, but fails to disclose that this is a destructive operation, whether changes are immediately committed, failure behavior, or rollback support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that front-loads the action and key concepts, with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, 3 required, no output schema), the description is too brief. It lacks explanation of success/failure behavior, return values, or safety warnings for this destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing baseline 3. The description adds meaning by mapping 'mandatory filters' to the 'where' parameter, 'optimistic predicates' to 'concurrency', and 'commit guards' to 'expected_rows' and 'max_affected_rows', which enriches the technical schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'Delete' and resource 'rows', and highlights key features (mandatory filters, optimistic predicates, commit guards). It distinguishes from sibling tools like 'select_rows' or 'insert_rows', though it could be more explicit about the meaning of 'commit guards'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention when not to use it or any prerequisites. It lacks explicit differentiation from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute exactly one read-only, parameterized SQL statement with bounded results
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | Exactly one SQL statement | |
| params | No | Native values for psycopg %s placeholders | |
| max_rows | No | Maximum rows returned |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only, parameterized, and bounded results; no annotations provided. Lacks details on error handling or query limits but sufficient for core behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence conveying all key constraints with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with well-described params; description summarizes constraints adequately for an AI agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions; description adds high-level context but does not meaningfully extend schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'execute' with clear resource 'SQL statement' and constraints 'read-only, parameterized, bounded results'. Distinguishes from sibling write tools like insert_rows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies read-only nature and bounded results, implying use for queries; no explicit when-not or alternatives, but context from siblings fills gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain a SQL query and optionally simulate hypothetical indexes
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SQL query to explain | |
| analyze | No | Execute the statement to collect actual statistics | |
| hypothetical_indexes | No | Hypothetical index definitions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions the key behavior of explaining a query and optionally simulating indexes, but it does not disclose that when 'analyze' is true, the query is actually executed (side effect). No permissions or other behavioral traits are covered. Since no annotations are provided, the description carries the full burden but misses important details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that front-loads the main purpose. However, it could be slightly expanded to cover key behavioral notes without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool supports advanced features like hypothetical indexes and analyze, but the description does not explain output, interpretation, or caveats. No output schema exists, and no annotations are provided, so the description should do more to set expectations for a complex EXPLAIN tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all three parameters with descriptions. The tool description adds no further meaning beyond restating the core action. Baseline 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'explain' and the resource 'SQL query', and it adds the optional feature of simulating hypothetical indexes. This effectively distinguishes it from sibling tools like 'execute_sql' and various analysis tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied (explain SQL queries) but there is no explicit guidance on when to use this tool versus alternatives like 'execute_sql' or 'analyze_query_indexes'. No when-not-to-use or context for choosing among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report conservative PostgreSQL deployment-provider capabilities without secrets
| Name | Required | Description | Default |
|---|---|---|---|
| provider_hint | No | auto, upstream, generic_managed, aws_rds, aws_aurora, google_cloud_sql, google_alloydb, azure_flexible_server, neon, or supabase_hosted | auto |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions 'without secrets', implying no sensitive data exposure, but does not specify read-only behavior, caching, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys core purpose without extraneous words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what the tool returns. It does not describe output format, fields, or the meaning of 'capabilities'. The term 'conservative' is undefined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the single parameter fully (100% coverage). The description adds 'conservative' and 'without secrets' but does not enhance understanding of the provider_hint parameter beyond the schema's default and enum-like listing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports PostgreSQL deployment-provider capabilities and mentions it is conservative and without secrets. However, it does not explicitly distinguish from siblings like get_server_capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description provides no context for when this tool is preferred over other tools like get_server_capabilities or get_extension_profiles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inventory PostgreSQL objects owned by one installed extension through core catalogs
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum extension-owned objects | |
| extension_name | Yes | Exact installed extension name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must bear full burden. It mentions 'through core catalogs' implying read-only but does not disclose permissions, side effects, or other behavioral traits like safety or restrictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, efficiently states purpose. However, could be slightly expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With two params and no output schema, the description is adequate but lacks information on return values or usage guidance. Enough to infer basic operation but not comprehensively complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema's parameter definitions; it merely reiterates 'Exact installed extension name' and 'Maximum extension-owned objects'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inventories PostgreSQL objects owned by an extension, using a specific verb and resource. It distinguishes from sibling tools like list_objects or get_object_details by focusing on extension-owned objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description only states what it does without comparative or conditional advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List installed or available PostgreSQL extension capability profiles
| Name | Required | Description | Default |
|---|---|---|---|
| include_available | No | Include extensions available to install but not currently installed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it lists profiles, but with no annotations, it fails to disclose behavioral traits such as read-only nature, performance impact, or required permissions. It meets minimal disclosure but relies on the user to infer it is a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is front-loaded and conveys the essential information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description should explain what 'capability profiles' contain (e.g., name, version, status). It does not, so completeness is adequate but not exceptional. The tool is simple with one parameter, so minimal completeness is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single boolean parameter that has a clear description in the schema. The tool description does not add any additional meaning beyond what the parameter schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('List') and the resource ('installed or available PostgreSQL extension capability profiles'). It distinguishes from sibling tools like get_extension_objects which lists objects within a specific extension.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., get_extension_objects, list_schemas). The description lacks when-to-use or when-not-to-use context, and does not mention any prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List redacted reviewed maintenance status records
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum status rows |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. It does not state whether the operation is read-only, idempotent, or requires special permissions. The name 'get' implies reading, but the description fails to explicitly confirm safety or side effects. The transparency is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one short phrase) but lacks clarity due to the ambiguous 'redacted' qualifier. It is not verbose, but the brevity sacrifices usefulness. An average score reflects that it is neither overly long nor optimally clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema, no annotations), the description should provide more context about what 'reviewed' means and how the output is structured. The current text is too minimal to fully understand the tool's role in the maintenance workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the only parameter ('limit') with a description, achieving 100% coverage. The description adds no additional meaning beyond the schema's own description. Baseline score of 3 is appropriate since no further value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List redacted reviewed maintenance status records', which indicates a read operation on a specific resource. However, the term 'redacted' is confusing and likely a placeholder, and the description does not differentiate from sibling tools like get_migration_status. The purpose is moderately clear but lacks precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as create_maintenance_plan or apply_maintenance_plan. There is no mention of prerequisites, context, or exclusion criteria. The description simply states the action without any usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List redacted reviewed migration ledger metadata
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum migration rows |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the action (list) but does not confirm it is read-only, mention side effects, or authentication needs. This is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Efficient but could include more valuable content without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output format, usage context, and relationship to sibling migration tools. Despite simple schema, the description does not provide enough context for an agent to confidently use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning for the 'limit' parameter beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists migration ledger metadata with 'redacted reviewed' qualifiers, which distinguishes it from sibling tools like create_migration_plan or rollback_migration. However, it doesn't explicitly contrast with similar list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_server_info or list_relations. The description lacks any contextual cues about prerequisites or suitability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show columns, constraints, indexes, and comments for a database object
| Name | Required | Description | Default |
|---|---|---|---|
| object_name | Yes | Object name | |
| object_type | No | table, view, sequence, or extension | table |
| schema_name | Yes | Schema name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the burden of disclosing behavioral traits. The term 'Show' clearly indicates a read-only operation, implying no destructive side effects. However, it does not detail any specific behavioral aspects like permission requirements, limits on object types (though the schema includes an 'object_type' parameter with allowed values), or whether the output is always returned or might be empty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the essential information. Every word is necessary and contributes to understanding the tool's purpose without redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has three parameters and no output schema, the description is moderately complete. It explains what the tool shows but does not describe the format of the output (e.g., whether it returns a list, a table, or text), nor does it provide examples or context about typical usage. It is adequate but leaves gaps for an agent unfamiliar with the system.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all three parameters. The description does not add semantic meaning beyond what is in the schema; it only lists the information returned (columns, constraints, etc.). Thus, it meets the baseline but provides no extra clarification for parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Show columns, constraints, indexes, and comments for a database object'. It specifies the verb ('Show') and the resource ('database object'), making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like 'get_relation_details', though the specific list of shown elements provides some distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'list_objects', 'get_relation_details', or 'search_catalog'. The description lacks context for selecting this tool over others, and there are no prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report bounded pgvector columns and indexes through PostgreSQL core catalogs
| Name | Required | Description | Default |
|---|---|---|---|
| max_columns | No | Maximum pgvector columns | |
| max_indexes | No | Maximum pgvector indexes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose important behavioral traits: it does not explain what 'bounded' means, whether the tool is read-only, required permissions, or behavior if pgvector is not installed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no filler, directly conveying the tool's action and scope. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description omits what the output contains and lacks context about 'bounded'. Without an output schema, more detail would help the agent understand the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters have descriptions). The tool description adds no additional meaning beyond the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reports bounded pgvector columns and indexes using a specific verb ('report') and resource ('pgvector columns and indexes'). It distinguishes itself from sibling tools like get_postgis_diagnostics by focusing on pgvector.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is specific to pgvector diagnostics, making its usage clear among database tools. However, it does not explicitly state when to use versus alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report bounded PostGIS columns and indexes through PostgreSQL core catalogs
| Name | Required | Description | Default |
|---|---|---|---|
| max_columns | No | Maximum PostGIS columns | |
| max_indexes | No | Maximum PostGIS indexes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not indicate whether the tool is read-only, destructive, or requires specific permissions. The term 'bounded' is ambiguous and unexplained, leaving behavioral traits unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the tool's purpose. There is no redundant or unnecessary information; every word contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two parameters with schema descriptions and no output schema, the description provides minimal context. It does not explain what 'bounded' means, what the output contains, or any usage considerations. For a diagnostic tool, more context is needed for effective decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 does not add additional meaning beyond the schema, which already describes max_columns and max_indexes with defaults and constraints. The phrase 'bounded' loosely relates but adds no specific param insight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Report') and resource ('bounded PostGIS columns and indexes'), and specifies the method ('through PostgreSQL core catalogs'). It effectively differentiates from sibling tools like get_pgvector_diagnostics by focusing on PostGIS.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like get_pgvector_diagnostics, get_runtime_metrics, or other diagnostic tools. No context on prerequisites or intended scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect any PostgreSQL type, including enum, domain, composite, range, multirange, array, and extension types
| Name | Required | Description | Default |
|---|---|---|---|
| type_oid | No | Exact PostgreSQL type OID | |
| type_name | No | Type name when OID is omitted | |
| schema_name | No | Type schema when OID is omitted |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description indicates an 'inspect' operation (read-only) and lists supported types, but does not explicitly state that it is non-destructive or detail any permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, efficient sentence front-loads the verb 'Inspect' and concisely lists supported type categories without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fails to mention what the tool returns (e.g., type details, structure), leaving important information missing. Given no output schema, this is a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all three parameters with 100% coverage. The description does not add any additional meaning beyond what the schema provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inspects PostgreSQL types with a specific verb 'Inspect' and lists supported type categories (enum, domain, etc.), distinguishing it from siblings like list_postgres_types which lists types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for inspecting any PostgreSQL type, but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect a relation's columns, constraints, indexes, triggers, policies, partitions, and privileges
| Name | Required | Description | Default |
|---|---|---|---|
| schema_name | Yes | Exact schema name | |
| relation_name | Yes | Exact relation name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. The description implies a read-only operation by naming 'Inspect', but does not explicitly state safety, idempotency, or side effects. Moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with 11 words, front-loaded with the action and resource, and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a retrieval tool with no output schema, the description covers the main aspects returned (columns, constraints, etc.). It is mostly complete, though it could hint at output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The tool description adds context that the parameters identify a relation to inspect, but does not add significant detail beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Inspect' and the resource 'relation's columns, constraints, indexes, triggers, policies, partitions, and privileges', making the tool's purpose highly specific and distinguishable from sibling tools like get_object_details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., get_object_details, list_objects), nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return privacy-preserving aggregate runtime metrics for the current process
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that metrics are privacy-preserving and aggregate, which is a key behavioral trait. However, without annotations, it lacks details on side effects (presumably none), data access patterns, or cost. The privacy disclosure adds value but is alone insufficient for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with 8 words, front-loaded with verb and object. No superfluous content. Perfectly concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no output schema, the description covers the core purpose and key attribute (privacy). It is mostly complete, though it could mention that it is a safe read-only call. Given the low complexity, missing details are minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no parameters (0). Per guidelines, baseline for 0 parameters is 4. The description adds no parameter information because none are needed, and the schema has 100% coverage trivially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Return privacy-preserving aggregate runtime metrics' clearly states the verb (return) and resource (runtime metrics), and the phrase 'privacy-preserving aggregate' distinguishes it from sibling diagnostic tools like get_top_queries or get_server_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, suitable contexts, or when to avoid using it. Sibling tools like get_server_info are not explicitly differentiated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the active profile, access policy, and hard execution limits
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only says 'Report', which implies read-only, but does not explicitly state safety, side effects, or what happens if capabilities are unavailable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence conveying the exact purpose with no extra words. Perfectly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description is adequate but could be more complete by mentioning the return format or additional context like 'returns JSON'. Still, it covers the key items reported.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Baseline for 0 parameters is 4. Description adds no parameter info, which is acceptable as there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool reports active profile, access policy, and hard execution limits. The verb 'report' matches the read-only nature, and the resource is distinctly different from sibling tools like get_server_info or get_runtime_metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternative sibling tools. The description only says what it does, without suggesting context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report PostgreSQL version, database, role, recovery, locale, and installed extensions
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'Report...', which implies read-only but does not disclose any further behavioral traits such as authentication needs, rate limits, or side effects. The description carries the full burden and is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should explain the return structure or format. It only lists items but not how they are organized (e.g., key-value pairs, nested fields). The description is incomplete for an agent to understand the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters, so schema coverage is 100%. The description adds context by listing what is reported, which is useful despite no parameters existing. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Report PostgreSQL version, database, role, recovery, locale, and installed extensions', which is a specific verb ('report') and lists the exact resources. It distinguishes itself from sibling tools like 'get_runtime_metrics' which focus on different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus siblings such as 'get_server_capabilities' or 'get_runtime_metrics'. There is no mention of when not to use it or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report slow or resource-intensive queries using pg_stat_statements
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| sort_by | No | resources |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not mention whether the tool is read-only, safe, or has any side effects. It also fails to mention any prerequisites like requiring pg_stat_statements extension to be enabled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks necessary detail. It could be expanded to cover key behavioral aspects and parameter meanings without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and two parameters, the description is insufficient. It does not describe the return format (e.g., a list of query texts with metrics), nor does it mention the source (pg_stat_statements) in a way that signals usage context. For a tool with multiple siblings, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no information about the parameters (limit, sort_by). The agent does not learn what 'sort_by' values are allowed or how 'limit' affects results, leaving it to guess based on default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports slow or resource-intensive queries using pg_stat_statements. The verb 'report' and resource 'slow/resource-intensive queries' are specific, and it distinguishes from sibling tools like 'explain_query' or 'get_runtime_metrics' which focus on different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not explain when to prefer it over 'explain_query' for query performance analysis or 'analyze_workload_indexes' for indexing insights.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert bounded typed rows with exact affected-row commit guards
| Name | Required | Description | Default |
|---|---|---|---|
| rows | Yes | Rows sharing one column set | |
| returning | No | Columns returned after commit validation | |
| schema_name | Yes | Exact schema name | |
| expected_rows | No | Optional exact affected row count | |
| relation_name | Yes | Exact table name | |
| max_affected_rows | No | Hard mutation ceiling |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears the full burden. It mentions 'exact affected-row commit guards,' hinting at validation behavior, but it does not disclose other important traits like whether the operation is destructive, requires permissions, or what happens on failure. Minimal disclosure beyond the basic mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single short phrase—and front-loads the action. However, it sacrifices clarity for brevity, making it somewhat cryptic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 6 parameters, the description is insufficient. It does not explain return values, prerequisites, or edge cases. For a mutation tool with complex guards, more behavioral context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing adequate parameter descriptions. The description adds the phrases 'bounded typed rows' and 'exact affected-row commit guards,' which loosely reference parameters like rows, expected_rows, and max_affected_rows, but it does not add significant meaning beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Insert bounded typed rows' which clarifies the operation and adds nuance about the rows being bounded and typed, but the term 'typed rows' is vague and not clearly defined. It does not effectively distinguish from sibling tools like upsert_rows or update_rows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as upsert_rows or delete_rows. The description lacks any context about appropriate use cases or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tables, views, sequences, or extensions
| Name | Required | Description | Default |
|---|---|---|---|
| object_type | No | table, view, sequence, or extension | table |
| schema_name | Yes | Schema name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states what is listed but does not disclose any behavioral aspects such as pagination, filtering behavior, or side effects. For a read-only listing tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at 5 words, which is efficient. However, it omits important context that could be included without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema and no description of return values, the tool is incomplete for context. Important details like output format, columns returned, or whether all objects of a type are listed are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, meaning both parameters are documented in the input schema. The tool description adds no extra meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'list' and the specific resource types ('tables, views, sequences, or extensions'), making the purpose unambiguous. It distinguishes from sibling tools like 'list_schemas' and 'list_relations' by specifying the exact object categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool over alternatives. Sibling tools such as 'list_relations', 'search_catalog', and 'get_object_details' could overlap, but no explanation of when to prefer this tool is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List built-in, user-defined, and extension-owned PostgreSQL types by OID
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum types | |
| offset | No | Result offset | |
| type_kind | No | Optional kind: array, base, composite, domain, enum, multirange, pseudo, or range | |
| schema_name | No | Optional exact schema filter | |
| include_system | No | Include system types |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It mentions listing by OID but does not detail pagination, ordering, or whether the list includes all types by default (only with include_system). There is no contradiction with annotations since none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous words. It is concise but could include more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided. The description covers what is listed but not the format or fields of the returned data. For a listing tool with five parameters and no output schema, additional detail about the result structure would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all five parameters. The description adds the context of listing by OID but does not enhance understanding of how parameters like limit or offset affect results beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'PostgreSQL types', specifying 'by OID' and covering three categories (built-in, user-defined, extension-owned). It distinguishes from the sibling 'get_postgres_type' which retrieves a single type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'get_postgres_type' or other catalog tools. The description lacks context about filters or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tables, partitions, views, sequences, foreign tables, indexes, and other relations
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum relations | |
| offset | No | Result offset | |
| schema_name | No | Optional exact schema filter | |
| relation_kind | No | Optional kind: table, partitioned_table, view, materialized_view, sequence, foreign_table, index, partitioned_index, composite, or toast | |
| include_system | No | Include system schemas |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the listing action. It does not disclose whether the operation is read-only, performance characteristics, or what 'relations' excludes (e.g., functions, operators). Minimal behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence covering the core function. It is concise but could benefit from front-loading the primary use case (listing relations in the database) before enumerating types.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no annotations, the description lacks context on pagination, filtering, default behavior (e.g., does it exclude system schemas?), and what the returned data looks like (no output schema). The agent may not understand how to effectively use the parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3 is appropriate. The description adds no extra meaning beyond the parameter descriptions in the schema—e.g., it does not clarify the pagination behavior via limit/offset or the effect of include_system.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'tables, partitions, views, sequences, foreign tables, indexes, and other relations,' specifying the resource and action. It is distinct from siblings like list_schemas or get_relation_details, though not explicitly differentiating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as list_schemas, get_relation_details, or search_catalog. An agent lacks context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all schemas in the database
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. As a simple read-only listing, the description is adequate but does not explicitly state it is non-destructive or clarify return behavior (e.g., returns schema names only).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, clearly front-loaded with verb and resource, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only listing tool without output schema, the description is complete. It sufficiently informs the agent of its function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has 0 parameters and schema description coverage is 100% (empty). No parameter information needed; baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List all schemas in the database' with a specific verb (List) and resource (schemas). It inherently distinguishes from sibling tools that list other entities like relations or objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as list_relations or list_objects. The description does not provide context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reconcile a reviewed maintenance operation after external outcome verification
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Stable maintenance operation name | |
| resolution | Yes | Externally verified outcome | |
| review_hash | Yes | Exact stored review hash |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the action ('reconcile') without disclosing behavioral traits such as whether the operation is destructive, requires special permissions, is reversible, or what side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no superfluous words. It front-loads the purpose with the verb and resource, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description does not convey what the tool returns or confirms after reconciliation. It is adequate for the basic purpose but lacks details on outcome or side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the description adds limited extra meaning. It does not elaborate on how the parameters like 'review_hash' or 'resolution' fit into the reconciliation process beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('reconcile') and resource ('maintenance operation'), and adds context with 'after external outcome verification'. This clearly distinguishes it from sibling tools like create, apply, or get maintenance operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the usage context: 'after external outcome verification'. This helps the agent know when to invoke it. However, it does not provide explicit exclusions or mention alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Atomically roll back the latest reviewed migration using its stored verified plan
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Applied migration name | |
| review_hash | Yes | Exact review hash of the stored plan | |
| timeout_seconds | No | ||
| lock_timeout_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses atomicity and use of stored plan but lacks critical info on destructive nature, permission requirements, and side effects, especially given no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single efficient sentence with no wasted words, front-loaded with key verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides basic context of atomic rollback but omits failure behavior, idempotency, prerequisites, and relationship to sibling migration tools, leaving gaps for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 50% of parameters with descriptions; description adds no extra parameter semantics beyond what schema provides, meeting baseline adequacy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'roll back' and resource 'latest reviewed migration', distinguishing it from sibling migration tools like apply_migration_plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for rolling back a reviewed migration but provides no explicit when-to-use or when-not-to-use guidance, nor mentions alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search relations, routines, types, collations, and extensions
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Case-insensitive name or comment fragment | |
| limit | No | Maximum matches | |
| offset | No | Result offset | |
| object_kind | No | Optional exact object-kind filter | |
| schema_name | No | Optional exact schema filter | |
| include_system | No | Include pg_catalog and other system schemas |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states the action and objects without disclosing behavior like case-insensitivity, pagination, default filters, or result format. Critical behavioral traits are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose. Very concise but possibly too brief, omitting key information that could fit in 2-3 sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks explanation of return values, result structure, or typical usage context. Without output schema or detailed description, an agent has insufficient context to trust the tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% so baseline is 3. The description adds no extra meaning beyond the schema; it does not explain parameter context or usage nuances.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'search' and specific resource types (relations, routines, types, collations, extensions), distinguishing it from sibling tools like list_schemas or get_object_details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like execute_sql or list_objects. The description implies it's for broad catalog search but lacks when-not-to-use or alternative comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Select bounded rows using catalog-validated identifiers, typed filters, and keyset pagination
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum visible rows | |
| where | No | Structured value-bound filter | |
| cursor | No | Opaque keyset cursor from a prior page | |
| columns | No | Projected columns; omit to select every column | |
| order_by | No | Stable order including a primary or unique key | |
| schema_name | Yes | Exact schema name | |
| relation_name | Yes | Exact table or readable relation name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It mentions validation of identifiers and pagination but does not disclose return format, error behavior, auth requirements, or whether it mutates data. Incomplete but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with key attributes, no fluff, and every word adds value. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of row selection with pagination and filters, the description covers main features but omits return format details (e.g., structure of rows, cursor for next page). Slightly incomplete but still helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context about bounded rows and typed filters but does not provide additional meaning per parameter beyond what the schema already explains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it selects rows with specific features: bounded, catalog-validated identifiers, typed filters, and keyset pagination. This clearly distinguishes it from sibling tools like execute_sql or mutation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for filtered, paginated row selection but does not explicitly state when to use this tool versus alternatives like execute_sql for arbitrary SQL or list_relations for metadata. No when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update typed values with mandatory filters, optimistic predicates, and commit guards
| Name | Required | Description | Default |
|---|---|---|---|
| where | Yes | Mandatory structured target filter | |
| values | Yes | Columns and bound replacement values | |
| returning | No | Columns returned after commit validation | |
| concurrency | No | Optional optimistic concurrency predicates | |
| schema_name | Yes | Exact schema name | |
| expected_rows | No | Optional exact affected row count | |
| relation_name | Yes | Exact table name | |
| max_affected_rows | No | Hard mutation ceiling |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only vaguely mentions 'mandatory filters, optimistic predicates, and commit guards' without detailing behavioral traits like mutation limits or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise and to the point, but lacks structural elements like bullet points or separate sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complex tool with 8 parameters, nested objects, and no output schema; the description fails to explain return values, failure behavior, or pagination, leaving gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds little beyond labeling parameters as 'mandatory' and 'optimistic'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update typed values' with key constraints, distinguishing it from sibling tools like insert_rows and delete_rows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives; the description implies use for updates with filters but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upsert typed rows through a verified primary or unique conflict key
| Name | Required | Description | Default |
|---|---|---|---|
| rows | Yes | Rows sharing one column set | |
| returning | No | Columns returned after commit validation | |
| schema_name | Yes | Exact schema name | |
| expected_rows | No | Optional exact affected row count | |
| relation_name | Yes | Exact table name | |
| update_columns | No | Inserted columns updated on conflict | |
| conflict_columns | Yes | Complete primary or non-partial unique key | |
| max_affected_rows | No | Hard mutation ceiling |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It only states 'upsert through a verified conflict key' without explaining core behaviors like atomicity, row resolution details, or whether returned rows include inserted or updated results. The schema adds limited behavioral context via 'update_columns' and 'conflict_columns' but the description does not synthesize this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded and to the point. It could benefit from more structure, but it efficiently communicates the core function with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no output schema, and no annotations, the description provides minimal context. It omits information about return values, error handling, row-matching logic, and the effect of 'update_columns'. A more complete description would guide the agent on expected outcomes and limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes each parameter. The description adds no additional semantic meaning beyond the verb 'upsert', which is already implied. With high schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool upserts typed rows using a verified primary or unique conflict key. It effectively distinguishes itself from sibling tools like insert_rows and update_rows by specifying the combined insert-or-update behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for upsert scenarios but lacks explicit guidance on when to prefer this over insert_rows or update_rows, or any exclusions. The name and description together make the context clear, but no alternatives or when-not-to-use are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0analyze_db_healthanalyze_query_indexesanalyze_workload_indexesapply_maintenance_planapply_migration_plancreate_maintenance_plancreate_migration_plandelete_rowsexecute_sqlexplain_queryget_deployment_profileget_extension_objectsget_extension_profilesget_maintenance_statusget_migration_statusget_object_detailsget_pgvector_diagnosticsget_postgis_diagnosticsget_postgres_typeget_relation_detailsget_runtime_metricsget_server_capabilitiesget_server_infoget_top_queriesinsert_rowslist_objectslist_postgres_typeslist_relationslist_schemasreconcile_maintenance_operationrollback_migrationsearch_catalogselect_rowsupdate_rowsupsert_rowsEach tool targets a distinct operation or resource (e.g., schema listing vs. object details, migration planning vs. maintenance), with clear descriptions that prevent ambiguity. Even similar tools like 'list_objects' and 'list_relations' differentiate by scope.
All tool names follow a consistent 'verb_noun' pattern in snake_case (e.g., 'get_runtime_metrics', 'create_migration_plan'). No mixed conventions (camelCase, different verb styles) are present.
35 tools is slightly high for typical MCP servers (most have 3-15), but each tool serves a well-defined PostgreSQL operation. The count is justified by the broad domain coverage, though some tools like the three 'analyze_*' variants could potentially be consolidated.
The tool set covers CRUD, migration lifecycle, maintenance, diagnostics, and schema inspection comprehensively. Minor gaps exist (e.g., no explicit tools for role/permission management, transaction control beyond migrations), but overall it's sufficient for database interaction.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
Generate, fix, explain and run read-only SQL on PostgreSQL, MySQL and SQL Server
Comprehensive PostgreSQL documentation and best practices, including ecosystem tools
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/surajmandalcell/pgsql-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
