Bulk-create nodes and edges from JSON arrays in a single call.

Use this tool when: you need to import many nodes and edges at once, e.g. loading a dataset, building a graph from structured data, or ingesting extracted entities in bulk. Do NOT use for: creating a single node or edge (use create_node / create_edge), or updating existing data (use update_node / update_edge).

Nodes are created first, then edges. Edges can reference nodes created in this batch using "@index" notation (e.g. "@0" refers to the first node in the nodes array).

Note: this operation is not atomic. If an error occurs partway through, already-created nodes/edges remain in the graph.

Args: nodes: List of node objects, each with: - labels: list of strings (required) - properties: dict of key-value pairs (optional) edges: List of edge objects, each with: - source_ref: int (existing node ID) or str ("@0", "@1", ...) referencing a node by its index in the nodes array - target_ref: int (existing node ID) or str ("@0", "@1", ...) - edge_type: str (required) - properties: dict of key-value pairs (optional)

Returns: JSON with created_nodes count, created_edges count, and a node_id_map from batch index to actual node ID.

Examples: batch_import( nodes=[ {"labels": ["Person"], "properties": {"name": "Alice"}}, {"labels": ["Person"], "properties": {"name": "Bob"}}, ], edges=[ {"source_ref": "@0", "target_ref": "@1", "edge_type": "KNOWS"}, ], )

Compute betweenness centrality for all nodes (Brandes' algorithm).

Betweenness centrality measures how often a node lies on the shortest path between other node pairs. High-betweenness nodes are "bridges" that connect different parts of the graph.

Use this tool when: you want to find bridge or bottleneck nodes. Do NOT use this for: finding the most linked-to nodes (use pagerank) or finding communities (use louvain).

Args: normalized: If True, normalize scores by 2/((n-1)(n-2)) so they fall in [0, 1] (default True). top_k: Number of top-ranked nodes to return (default 20).

Returns: JSON array of {node_id, score, labels, properties} sorted by score descending.

Error recovery: If all scores are 0 the graph may be too small or disconnected.

Find connected components (treating the graph as undirected).

A connected component is a maximal set of nodes such that every pair is reachable from every other by following edges in either direction.

Use this tool when: you want to know how many disconnected subgraphs exist, or which nodes belong to the same component. Do NOT use this for: finding dense sub-communities (use louvain).

Returns: JSON object with {num_components, components} where components maps component_id -> list of node IDs.

Error recovery: If every node is its own component, the graph has no edges.

Create a directed edge (relationship) between two existing nodes.

Use this tool when: you need to connect two nodes with a typed relationship. Do NOT use this for: creating nodes (use create_node) or querying relationships (use execute_gql).

Args: source_id: The source node ID (integer). target_id: The target node ID (integer). edge_type: Relationship type string (e.g. "KNOWS", "WORKS_AT"). properties: Optional edge properties (e.g. {"since": 2020, "weight": 1.5}).

Returns: JSON with the created edge's id, source_id, target_id, edge_type, and properties.

Examples: create_edge(1, 2, "KNOWS") create_edge(1, 3, "WORKS_AT", {"since": 2020})

Create a new node in the graph with the given labels and properties.

Use this tool when: you need to add a single new entity to the graph. Do NOT use this for: bulk inserts (use execute_gql with INSERT/CREATE statements) or creating relationships (use create_edge).

Args: labels: One or more node labels (e.g. ["Person"] or ["Person", "Employee"]). properties: Optional key-value properties (e.g. {"name": "Alice", "age": 30}). Omit or pass null for a node with no properties.

Returns: JSON with the created node's id, labels, and properties.

Examples: create_node(["Person"], {"name": "Alice", "age": 30}) create_node(["Company"], {"name": "Acme", "founded": 2010}) create_node(["Tag"]) # no properties

Create a full-text search index on a string property.

Call this once before using search_text on the same label + property pair. Existing nodes with the given label and property are indexed immediately; future nodes are indexed on insertion.

Use this tool when: you want to enable keyword search on a text property. Do NOT use for: vector/embedding search (use create_vector_index).

Args: label: Node label to index (e.g. "Article"). property: String property to index (e.g. "title", "content").

Returns: Confirmation string on success, or an error message.

Examples: create_text_index("Article", "title") create_text_index("Document", "content")

Create an HNSW vector index for fast similarity search.

Call this once before using vector_search on a label + property pair. If nodes with the given label already have vector values in the property, they are indexed immediately; future nodes are indexed on insertion.

Args: label: Node label to index (e.g. "Document"). property: Property containing embedding vectors (e.g. "embedding"). dimensions: Vector dimensionality (e.g. 1536 for OpenAI, 384 for MiniLM). If None the engine infers it from existing data. metric: Distance metric — "cosine" (default), "euclidean", "dot_product", or "manhattan". m: HNSW links per node (default 16 inside the engine). Higher values give better recall but use more memory. ef_construction: HNSW construction beam width (default 128 inside the engine). Higher values build a higher-quality index but take longer.

Returns: Confirmation string on success, or an error message.

Example call: create_vector_index("Document", "embedding", 1536, "cosine", m=32, ef_construction=200)

Delete an edge from the graph.

Use this tool when: you need to remove a relationship between two nodes. Do NOT use for: deleting nodes (use delete_node) or updating edge properties (use update_edge).

Args: edge_id: The ID of the edge to delete.

Returns: Confirmation message on success, or an error message.

Examples: delete_edge(5)

Delete a node from the graph.

Use this tool when: you need to remove a node permanently. Do NOT use for: updating properties (use update_node) or deleting edges only (use delete_edge).

Args: node_id: The ID of the node to delete. detach: If True (default), also delete all edges connected to this node (like DETACH DELETE in Cypher). If False, fail if the node has any connected edges.

Returns: Confirmation message on success, or an error message.

Examples: delete_node(42) # detach delete (remove edges too) delete_node(42, detach=False) # fail if edges exist

Find the shortest weighted path between two nodes (Dijkstra's algorithm).

Returns the total distance and the sequence of nodes along the path.

Use this tool when: you need the shortest or cheapest path between two known nodes. Do NOT use this for: discovering important nodes (use pagerank) or finding similar content (use vector_search).

Args: source_id: Starting node ID. target_id: Destination node ID. weight_property: Edge property to use as weight (e.g. "distance", "cost"). If None every edge has weight 1.0.

Returns: JSON object with {distance, path: [{node_id, labels, properties}, ...]}. Returns an error message if the nodes are unreachable.

Error recovery: If the result is null/unreachable, check that both node IDs exist (use get_node) and that there is a connecting path in the graph.

Execute a GQL query against the graph database.

GQL (Graph Query Language) is the ISO/IEC standard query language. Use MATCH patterns to find nodes and relationships, INSERT to add data, and RETURN to project results.

Cypher syntax (e.g. CREATE) is automatically normalized to GQL (INSERT), so queries written in Cypher style will generally work as-is.

Use this tool when: you need to run a custom query — complex filters, multi-hop traversals, aggregations, or mutations beyond what the CRUD tools (create_node, create_edge) provide. Do NOT use this for: simple node lookups (use get_node), label browsing (use search_nodes_by_label), or one-hop exploration (use get_neighbors).

Args: query: A GQL query string (Cypher syntax is auto-normalized). limit: Maximum rows to return (default 100). Use to prevent overwhelming context windows. The query itself can also contain a LIMIT clause for server-side limiting.

Examples: MATCH (p:Person) RETURN p.name, p.age MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name INSERT (:Person {name: 'Alice', age: 30}) MATCH (p:Person) WHERE p.age > 25 RETURN p.name LIMIT 10

Get neighboring nodes connected to a given node.

This is the primary tool for graph traversal. Use it to explore the neighborhood of a known node. Returns connected nodes with the edges that link them.

Use this tool when: you have a node ID and want to see what it connects to. Do NOT use this for: finding nodes by property (use search_nodes_by_label) or running complex multi-hop queries (use execute_gql).

Args: node_id: The ID of the node to get neighbors for. direction: "outgoing" (node-->neighbor), "incoming" (neighbor-->node), or "both" (default). Controls which direction of edges to follow. edge_type: Filter by relationship type (e.g. "KNOWS"). None returns all edge types. limit: Maximum neighbors to return (default 50).

Returns: JSON with the center node, a list of neighbors (with connecting edge info), and counts.

Examples: get_neighbors(0) get_neighbors(42, direction="outgoing") get_neighbors(1, edge_type="KNOWS", limit=10) get_neighbors(5, direction="incoming", edge_type="WORKS_AT")

Get a single node by its ID.

Returns the node's labels and all properties, or a not-found message.

Use this tool when: you have a specific node ID and need its details. Do NOT use this for: searching nodes by label or property (use search_nodes_by_label or execute_gql).

Args: node_id: The numeric node ID (e.g. 0, 1, 42).

Returns: JSON with id, labels, and properties -- or an error/not-found message.

Examples: get_node(0) get_node(42)

Get an overview of the graph database: counts, labels, edge types, and schema.

Use this tool when: you need to understand what data is in the graph before writing queries, or to verify the database state after mutations. Do NOT use this for: retrieving specific node/edge data (use get_node, search_nodes_by_label, or execute_gql).

Returns: JSON with database info (mode, node_count, edge_count, persistence), schema (labels with counts, edge_types with counts, property_keys), and detailed statistics.

Detect communities using the Louvain modularity-optimization algorithm.

Groups densely-connected nodes into communities. Higher resolution values produce more (smaller) communities; lower values produce fewer (larger) communities.

Use this tool when: you want to discover clusters or groups in the graph. Do NOT use this for: finding paths (use dijkstra) or ranking nodes (use pagerank).

Args: resolution: Resolution parameter (default 1.0). Values > 1 favor smaller communities, values < 1 favor larger ones.

Returns: JSON object with {modularity, num_communities, communities} where communities maps community_id -> list of node summaries. Output is truncated if it exceeds the token budget.

Error recovery: If this returns 0 communities, the graph may have no edges. Check with graph_info.

Find diverse nearest neighbors using Maximal Marginal Relevance (MMR).

MMR balances relevance to the query with diversity among results, avoiding redundant near-duplicate results. This is ideal for RAG pipelines where you want broad coverage rather than 10 variations of the same paragraph.

Use this tool when: you need diverse vector search results for RAG or when vector_search returns too many near-duplicates. Use vector_search when: you want the absolute closest matches regardless of diversity.

Args: label: Node label to search within (e.g. "Document"). property: Property that holds the embedding vector (e.g. "embedding"). query_vector: The query embedding as a list of floats. k: Number of diverse results to return (default 10). fetch_k: Initial candidates from HNSW before MMR re-ranking (default: 4*k). Higher values give MMR more to choose from. lambda_mult: Balance between relevance and diversity. 0.0 = maximize diversity, 1.0 = maximize relevance. Default: 0.5 (balanced). For RAG, try 0.3-0.7. ef: HNSW search beam width. Leave as None for index default.

Returns: JSON array of {node_id, distance, labels, properties} ordered by MMR selection (not pure distance).

Example call: mmr_search("Document", "embedding", [0.12, -0.34, ...], k=5, lambda_mult=0.3)

Run PageRank and return the top-k most important nodes.

PageRank assigns every node a score proportional to how many (and how important) other nodes link to it. Higher scores mean more connected / influential nodes.

Use this tool when: you want to find the most important or central nodes in the graph based on link structure. Do NOT use this for: finding similar nodes by content (use vector_search) or for finding shortest paths (use dijkstra).

Args: damping: Probability of following a link vs. teleporting (default 0.85). max_iterations: Upper bound on convergence iterations (default 100). tolerance: Convergence threshold (default 1e-6). top_k: How many top-ranked nodes to return (default 20). The algorithm always scores every node, but only the top-k are returned to keep the output manageable.

Returns: JSON array of {node_id, score, labels, properties} sorted by score descending. Output is truncated if it exceeds the token budget.

Error recovery: If this returns an error, verify the graph is non-empty with graph_info. PageRank requires at least one edge.

Find nodes that have a specific label.

Returns node IDs and their properties, paginated by limit/offset.

Use this tool when: you want to list or browse nodes of a certain type (e.g. all Person nodes, all Company nodes). Do NOT use this for: getting a single node by ID (use get_node), or complex filtered queries (use execute_gql).

Args: label: The label to filter by (e.g. "Person", "Company"). limit: Maximum number of results to return (default 100). offset: Number of results to skip for pagination (default 0).

Returns: JSON with a list of {node_id, properties} objects, total count, and a truncation note if applicable.

Examples: search_nodes_by_label("Person") search_nodes_by_label("Company", limit=10) search_nodes_by_label("Person", limit=50, offset=50) # page 2

Full-text keyword search over string properties.

Finds nodes whose text property matches the search query. Requires a text index created via create_text_index on the same label + property.

Use this tool when: you want to search for nodes by keyword or phrase. Do NOT use for: semantic/vector similarity (use vector_search), exact property matching (use execute_gql with WHERE), or browsing by label (use search_nodes_by_label).

Args: label: Node label to search within (e.g. "Article"). property: String property to search (e.g. "title"). query: Search query string (keywords or phrase). limit: Maximum number of results to return (default 20).

Returns: JSON array of {node_id, score, labels, properties} sorted by relevance score descending.

Examples: search_text("Article", "title", "graph database") search_text("Document", "content", "machine learning", limit=10)

Update properties on an existing edge.

Use this tool when: you need to modify an edge's properties after creation. Do NOT use for: changing the edge type (delete and recreate), creating new edges (use create_edge), or deleting edges (use delete_edge).

Args: edge_id: The ID of the edge to update. properties: Key-value properties to set. merge: If True (default), merge with existing properties. If False, replace all properties.

Returns: JSON with the updated edge's id, source_id, target_id, edge_type, and properties.

Examples: update_edge(0, {"weight": 2.5}) update_edge(0, {"since": 2024}, merge=False)

Update properties on an existing node.

Use this tool when: you need to modify a node's properties after creation. Do NOT use for: changing labels (use execute_gql), creating new nodes (use create_node), or deleting nodes (use delete_node).

Args: node_id: The ID of the node to update. properties: Key-value properties to set. Values can be strings, numbers, booleans, or lists. merge: If True (default), merge with existing properties (new keys are added, existing keys are overwritten, unlisted keys are kept). If False, replace all properties (unlisted keys are removed).

Returns: JSON with the updated node's id, labels, and properties.

Examples: update_node(0, {"age": 31}) # merge: keep other props update_node(0, {"name": "Alice"}, merge=False) # replace all props

Hybrid search: find similar nodes by vector, then expand their graph neighborhood.

This is the most powerful search tool — it combines semantic similarity (vector search) with graph structure (neighbor expansion). Use it when you want to find relevant nodes AND understand their context.

Step 1: Vector search finds the top-k most similar nodes. Step 2: For each result, expands outward by expand_depth hops.

Use this tool when: you need both semantic relevance AND graph context. Use vector_search when: you only need the similar nodes themselves. Use get_neighbors when: you already have a node and want to explore around it.

Args: label: Node label to search (must have a vector index). property: Property holding the embedding vector. query_vector: The query embedding as a list of floats. k: Number of nearest seed nodes to return (default 5). expand_depth: How many hops to expand from each seed (default 1). Use 0 to skip expansion (equivalent to plain vector_search). expand_edge_type: Optional edge type filter. If provided, only edges of this type are followed during expansion.

Returns: JSON object with "seeds" (vector results) and "neighbors" (expanded context), truncated if the output is large.

Example call: vector_graph_search("Article", "embedding", [0.1, ...], k=3, expand_depth=2, expand_edge_type="CITES")

Find the k nearest nodes by vector similarity (HNSW index).

Use this tool when you have an embedding vector and want to find semantically similar nodes. Requires a vector index created via create_vector_index on the same label + property.

Do NOT use this for keyword or property search — use search_nodes_by_label or execute_gql for that.

Args: label: Node label to search within (e.g. "Document"). property: Property that holds the embedding vector (e.g. "embedding"). query_vector: The query embedding as a list of floats. k: Number of nearest neighbors to return (default 10). ef: HNSW search beam width. Higher values improve recall at the cost of speed. Leave as None to use the index default.

Returns: JSON array of {node_id, distance, labels, properties} sorted by distance ascending (most similar first).

Example call: vector_search("Document", "embedding", [0.12, -0.34, ...], k=5)