improve: enhance tool descriptions for better LLM agent tool selection

[spidershield-contrib]

What

Rewrote all 9 MCP tool descriptions using an action-verb-first format designed for LLM agent planning.

Why

MCP tool descriptions serve as planning hints — LLMs use them to select which tool to call and in what order. The current single-sentence descriptions (e.g., "List all schemas in the database") don't provide enough context for LLMs to distinguish between similar tools, leading to tool selection errors in multi-step database workflows.

Format applied

Each description now includes:

• Action verb lead — what the tool does
• Use when — concrete scenarios for this tool
• Do not use when — disambiguation with sibling tools (e.g., "use analyze_query_indexes instead")
• Accepts — key parameters with examples
• Raises an error if — failure conditions

Example: list_objects (before → after)

Before:

List objects in a schema

After:

List objects of a given type within a specific schema.

Use when the user wants to discover tables, views, sequences, or extensions in a known schema.
Do not use when you need column-level details or indexes for a specific object (use get_object_details instead).
Accepts 'schema_name' (required) and 'object_type' (optional, default 'table'). e.g., schema_name='public', object_type='view'.
Raises an error if the schema does not exist or the object_type is unsupported.

Scope

• 1 file changed (src/postgres_mcp/server.py)
• 9 tool descriptions rewritten
• Pure string replacement — no logic, schema, or API changes
• Python syntax verified (py_compile)

🤖 Descriptions improved with spidershield — open-source MCP security & quality scanner.

[jssmith]

Review — concise

Verdict: Approve with comments. Good intent — richer tool descriptions help LLM agents select the right tool. But the descriptions are overly verbose.

Strengths

• Each tool description now includes: what it does, when to use it, when NOT to use it (with alternative tool suggestions), accepted parameters, and error conditions.
• Cross-references between tools (e.g., "use list_objects instead", "use execute_sql instead") help LLM agents navigate the toolset.
• analyze_db_health description preserves the full list of available check types while adding context.

Issues to address

1. Descriptions are very long (non-blocking, but worth considering)
The new descriptions are 4-6 lines each. Some MCP clients may truncate long descriptions in the tool list, potentially losing the most important parts. Consider leading with a concise one-line summary, then the details. E.g.:

"List all schemas in the database (name, owner, type). Use to discover schemas before querying tables."

vs. the current multi-paragraph format. The essential information (what + when) fits in one line.

2. analyze_db_health description lost the bullet list format (non-blocking)
The original used a clear bullet list for health check types. The new version inlines them into a comma-separated string. The bullet format was more scannable. Consider keeping bullets for the check types.

3. No tests needed — description-only changes, no logic modified.

This review was created by an AI agent (OpenHands) on behalf of @jssmith.