Neo4j MCP server has significant definition quality gaps. Tool definitions are inferred from test files and code rather than explicitly visible in schema registration. Only 4 tools total, with minimal parameter documentation and no visible input/output schemas. Descriptions are present but generic (10-60 chars), well below the 194-char baseline for A+ tools. No parameter type definitions, enums, or constraints visible. Error handling descriptions missing. Schema files not provided in source code sample, forcing inference from test expectations. The server uses STDIO transport (hard cap 50), making remote deployment impossible.
Tools (4)
get-schemaread onlysource verified32/100
Infers the schema of the Neo4j database using APOC's meta.schema procedure
list-gds-proceduresread onlysource verified28/100
Lists available Graph Data Science (GDS) procedures when GDS is installed
read-cypherread onlysource verified35/100
Executes read-only Cypher queries against the Neo4j database
write-cypherwritesource verified32/100
Executes write Cypher queries against the Neo4j database for state mutation
No input/output schemas visible in source code. Tool definitions appear to be inferred from test expectations rather than explicit schema registration. Cannot verify parameter types, descriptions, constraints, or output structure.
Parameter descriptions missing or not visible. No documentation of what parameters control, expected formats, valid ranges, or constraints. LLM cannot infer parameter semantics from names alone (e.g., 'query' parameter for Cypher tools lacks format guidance).
Tool descriptions are 10-60 characters, well below the 194-char baseline for production tools. Descriptions lack context on WHEN to use each tool (distinction between read-cypher and write-cypher unclear), prerequisites, or expected return types. No guidance on tool selection or composition.
Create explicit JSON Schema files for each tool's input and output. Include type definitions, enums (e.g., GDS algorithm categories), min/max constraints (query timeout: 30-300s), and required fields. Example: `read-cypher` input should define { query: string (max 10000 chars), timeout: integer (1-300), database?: string, parameters?: object }
Expand all tool descriptions to 150-250 characters. Include WHAT, WHEN, and RETURN type. Example: 'read-cypher: Execute read-only Cypher queries against Neo4j. Use for data retrieval, graph analysis, and pattern discovery. Returns result rows as structured objects with field names matching Cypher RETURN clauses. Max 10,000 characters per query; queries timing out after 30s return partial results.'
Document every parameter with a description explaining format, range, and allowed values. Example: `query: Cypher read query (10-10000 chars, no WRITE/DELETE/CREATE allowed); timeout: Query timeout in seconds (1-300, default 30); database: Database name (default: 'neo4j'); parameters: Query parameters as JSON object (e.g. {"id": 123, "status": "active"})`
Add error handling guidance to tool descriptions. Example for write-cypher: 'On constraint violations, returns error with constraint details. On syntax errors, returns clause and position. On permission errors, contact database admin. Retry-safe only if the mutation is idempotent (use MERGE, not CREATE).'
Implement dry-run or confirmation for write-cypher. Add optional parameter `preview: boolean (default false)`. When true, return query plan and estimated mutations without applying changes. Pair with a confirmation pattern: 'Review the dry-run output, then call write-cypher again with preview=false to commit.'
Error handling not documented. No guidance for LLMs on recovery steps when queries fail, syntax errors occur, or GDS is unavailable. Responses likely return raw error messages rather than actionable recovery hints ('Try calling list-gds-procedures first' or 'Cypher syntax error: ...'; invalid clause: ...').
write-cypher tool lacks confirmation/dry-run pattern. Agents can mutate the graph without preview or confirmation, risking data corruption. No mention of idempotence or retry-safety for write operations.
Output pagination/limits not documented. 'list-gds-procedures' does not indicate if results are paginated, capped, or unbounded. Large result sets could exhaust context window. 'get-schema' likely returns entire schema, no mention of limits or structure.
Tool names lack clear distinction. 'read-cypher' and 'write-cypher' differ only in intent, not naming pattern (both start with action verbs but could be 'query-cypher-readonly' vs 'execute-cypher-write' for clarity). Agents may conflate them.
read-cypherwrite-cypher
Add pagination to list-gds-procedures and get-schema. Include limit, offset/cursor parameters and return { results: [...], total: number, next_cursor?: string } to handle large result sets without context explosion.
Specify query timeouts and resource limits in descriptions. Example: 'Queries are terminated after 30 seconds. For long-running analyses, use GDS algorithms directly. Queries consuming >1GB RAM are cancelled.'
Document idempotence expectations for write-cypher. State: 'Idempotent if the Cypher uses MERGE or conditional logic. Non-idempotent UPSERTs (multiple CREATE statements) risk duplicates on retry. Test with test_write_cypher tool (if available) before production use.'
Return structured output with clear field names and types. Example: read-cypher should return { rows: [{ field1: any, field2: any, ... }], columns: ["field1", "field2"], stats: { rows_returned: number, execution_time_ms: number } }
Add a discovery tool or enhance get-schema to return schema in a more navigable form: { nodes: [{ label: string, properties: { name: string, type: string }[] }], relationships: [{ type: string, source_label: string, target_label: string }] } to guide agent query construction.