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.