This server has critical definition gaps across all three tools. While tool names follow verb_noun convention (query_agent, list_agents, create_neon_management_agent), descriptions are present but vague, parameters lack type information and descriptions in the schema, and output schemas are completely undocumented. The code shows basic string returns with no structured output. Tools are functional but would confuse LLMs about when to call each one and what to do with results. The create_neon_management_agent tool accepts zero parameters yet has significant side effects (creates a new agent in a remote service), violating the principle that idempotent discovery tools should have no parameters while mutation tools should require explicit intent parameters.

• Convert all tool outputs from markdown/string to structured JSON. E.g., list_agents should return {"agents": [{"name": "...", "id": "..."}, ...], "total": N} so LLMs can reliably extract agent_id.
• Add input parameters to create_neon_management_agent: agent_name (string, required), agent_description (string), model_name (enum of supported models), max_tokens (integer 100-4000). This enables LLM control over creation and supports idempotency.
• Document output schema for every tool in the tool description. E.g., 'Returns {"agents": [...]}' for list_agents, '{"agent_id": "...", "status": "created"}' for create_neon_management_agent.
• Add pagination to list_agents: limit (integer 1-100, default 20), offset (integer >= 0). Return {"agents": [...], "total": N, "limit": 20, "offset": 0} to support incremental discovery.
• Enhance error messages with recovery guidance. E.g., 'Agent U1234 not found. Call list_agents() to see available agents.' or 'Query timeout (>30s). Try a simpler query or retry in 60 seconds.'
• Add parameter descriptions with formats and constraints: agent_id as 'UUID of an existing agent (from list_agents())', query as 'Natural language question or command (max 5000 chars)'.
• Add tool annotation hints (destructiveHint for create_*, readonly hints for list_/query). Helps LLMs understand which tools need confirmation.
• Support make-idempotent create_neon_management_agent by accepting an optional agent_name parameter and checking for existing agent before creating. Return existing agent if it already exists.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry