# Phase 2 — Core Tools

> Query execution, graph CRUD, and traversal operations.

## Status: In Progress

## Research-Informed Changes

- Single query tool: `execute_gql` with auto-normalization of Cypher syntax
- Added `get_neighbors` — dedicated traversal tool (most impactful research finding)
- All tools have disambiguation lines ("Use this when..." / "Do NOT use for...")
- All list-returning tools have `limit` params and truncation messages
- Error messages suggest recovery actions (e.g. "Try graph_info to check labels")

## Tools (7 total)

### Query tool

| Tool          | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| `execute_gql` | Run GQL queries (Cypher syntax auto-normalized to GQL)            |

### Graph CRUD + traversal tools

| Tool                    | Description                                        |
| ----------------------- | -------------------------------------------------- |
| `create_node`           | Create a node with labels and properties           |
| `create_edge`           | Create a directed edge between two nodes           |
| `get_node`              | Retrieve a node by ID                              |
| `get_neighbors`         | Explore a node's neighborhood (primary traversal)  |
| `search_nodes_by_label` | Find nodes by label (with `limit` + pagination)    |
| `graph_info`            | Schema, stats, labels, edge types, indexes         |

## Tasks

- [x] Implement `execute_gql` with truncation, error recovery, and Cypher auto-normalization
- [x] Implement graph CRUD tools against real GrafeoDB API
- [x] Implement `get_neighbors` with direction/edge_type filtering
- [x] Implement `graph_info` with enriched schema output
- [x] Add disambiguation lines to all tool docstrings
- [x] Add token truncation to all list-returning tools
- [x] Write `tests/test_tools_query.py` (10 tests)
- [x] Write `tests/test_tools_graph.py` (18 tests)
- [ ] Test with a real MCP client (Claude Desktop or `mcp dev`)

## Design Decisions

### GQL only with Cypher auto-normalization

Single query tool using GrafeoDB's `execute()` method (GQL, ISO standard).
Lightweight regex-based normalization translates common Cypher keywords
(e.g. `CREATE` → `INSERT`) so AI agents trained on Cypher work seamlessly.

### Error handling: error strings (not exceptions)

Tools return descriptive error strings on failure with recovery suggestions.
Agents see errors as normal tool results and can decide how to handle them.

### Flat parameters

All tool parameters are primitives or simple `list`/`dict` — no nested models.
Maximizes compatibility across MCP clients and keeps tool schemas readable.
