Postgram MCP server provides 9 well-named tools with complete input schemas and descriptions. All tools follow verb_noun naming convention (create_, list_, search_, get_, update_, delete_). Descriptions are present and actionable (average 80-120 chars). Input schemas include proper type definitions and parameter descriptions. However, there are significant gaps: (1) No output schemas documented for any tool, LLMs cannot predict return structure or plan follow-up calls; (2) No error handling guidance, tools lack recovery instructions or error categorization; (3) No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels (WRITE, DESTRUCTIVE); (4) Parameter descriptions lack constraints, 'limit', 'offset', 'type' parameters have no stated ranges or valid values; (5) Pagination support is implicit but not documented in tool descriptions. Per-tool analysis: naming is excellent across all 9 tools (verb-first, action-clear). Descriptions are present but brief and lack context on when/why to use each tool. Schemas are complete with types and descriptions, meeting the minimum bar. Output structure is not documented.

• Document output schemas for all 9 tools. For create_entity, return {id: string (UUID), created_at: ISO8601, entity: {...}}. For list_entities, return {items: [...], total_count: number, has_more: boolean}. This enables agents to chain results to downstream calls.
• Add tool annotations to tool definitions: readOnlyHint=true for list_/search_/get_ tools; destructiveHint=true for delete_ tools; idempotentHint=true for operations that are safe to retry. This informs client safety policies.
• Upgrade parameter descriptions with constraints. Change 'Entity type (memory, person, project, task, interaction, document)' to an enum constraint in schema. Change 'Maximum number of entities to return' to 'limit: 1 - 100 (default: 20)'.
• Enhance tool descriptions to include WHEN guidance: 'search_entities: Use when you have a natural language query about entities. If you know the exact ID, use get_entity instead. Performs semantic search with embeddings, slower but finds related entities across the knowledge base.'
• Add pagination documentation to list_entities and list_edges descriptions: 'Returns paginated results with total_count. Set limit (1 - 100) and offset (default 0) to navigate. Results sorted by creation date descending.'
• Implement dry-run parameter for delete_entity and delete_edge: 'dry_run?: boolean, if true, returns what would be deleted without committing. Recommended before destructive operations.'
• Consider adding a confirmation/validation tool: confirm_deletion(entity_ids: string[], reason?: string) that returns a confirmation_token, then pass it to delete_entity to complete the deletion. This prevents accidental cascade deletes.