The tools
All tools act on the project open in Syncretic; most need one (“No project is open in Syncretic. Call list_projects, then open_project or create_project.”).
Projects
| Tool | Arguments | Returns |
|---|---|---|
list_projects | — | each project’s id, name, whether it’s open, its node types; for the open one, node and relationship counts |
open_project | project (name or id) | opens it in Syncretic; errors when the name is ambiguous (“Open it by id”) |
create_project | name | a new empty project, opened; “Add node types… with design_shape” |
get_shape | — | the shape in the names a person sees, then the database names for Cypher, the dialect notes, and how many nodes and relationships there are |
Reading
| Tool | Arguments | Returns |
|---|---|---|
search | text, by = words (default) or meaning, limit ≤ 200 (25) | by words: exact titles, then titles, then text, loosely matched, as node/relationship JSON; by meaning: vector search on embedded text with a score and the matched passage, plus how many passages are still being embedded. Errors if nothing is embedded or the model isn’t downloaded |
run_cypher | query, limit ≤ 1000 (100) | columns, rows (nodes and relationships as JSON with their properties by shape name; long text cut at 4,000 characters), total rows, truncated. A write is refused: “run_cypher only reads the graph… To add, edit or remove, use propose_changes” |
get_node | id | the node, every property, and up to 300 relationships, each with its direction and the node at its other end |
show_nodes | ids | brings them onto Syncretic’s canvas and frames them (selects one) |
Changing
| Tool | Arguments | Returns |
|---|---|---|
propose_changes | nodes (ref, type, properties), relationships (type, from, to, properties), changes (action remove/update, description, query, properties), request (the person’s words), summary | the draft’s id, status: waiting for review, counts, how many were already in the graph, possible duplicates, what didn’t fit the shape, and a message to tell the person to review it in Syncretic |
check_proposal | id | waiting for review, added (with what was added, matched, removed, edited), discarded, replaced (a later draft took its place), or failed |
design_shape | types (name, title, properties with kind text/number/link/boolean), relationships (name, from, to, properties), request, summary | what was added; applies at once, undoable in Syncretic; “Nothing new” when the shape already has it |
Property values in a proposal are strings; numbers, booleans and objects sent as JSON values are converted. An object of name → value is accepted in place of a list.
Example exchange
AI: get_shape
App: Project: Reading … Node types: Book (name, year), Idea (name, summary) … Relationship types: PRESENTS: Book → Idea …
AI: search { text: "Hofstadter" }
App: { results: [ { id: "…", type: "Book", title: "Gödel, Escher, Bach", properties: { year: 1979 } } ] }
AI: propose_changes { nodes: [ { ref: "n1", type: "Idea", properties: { name: "Strange loop", summary: "…" } } ],
relationships: [ { type: "PRESENTS", from: "<book id>", to: "n1" } ], summary: "One idea from the book." }
App: { id: "…", status: "waiting for review", nodes: 1, relationships: 1, message: "The draft is open in Syncretic's Build panel…" }
AI: check_proposal { id }
App: { status: "added", nodes_added: 1, relationships_added: 1, matched_to_existing: 0 }