In the previous challenge, you created a Cypher Template tool that runs a fixed Cypher query with variable parameters. Cypher Templates work well when the query structure is known in advance, but not every question fits a predefined pattern.
In this lesson, you will learn how to:
-
Decide when to use Text2Cypher instead of a Cypher Template
-
Configure a Text2Cypher tool to produce more accurate queries
Deciding when to use Text2Cypher
A Text2Cypher tool converts a natural language question into a Cypher query at runtime and executes it against your graph.
With a Text2Cypher tool, your agent can adapt to questions that do not follow a fixed pattern.
Text2Cypher uses a fine-tuned LLM to generate Cypher at runtime, so the output is probabilistic. The same question can produce different Cypher on different calls, and generated queries may contain errors.
Text2Cypher in production
Text2Cypher relies on a language model and can produce queries with errors.
Test generated queries in the reasoning panel before relying on them for production use.
Configuring a Text2Cypher tool
A Text2Cypher tool has two configuration options, Name and Description.
Use the Name to uniquely identify the tool in the agent configuration.
Use the Description to tell the agent when and when not to use the tool. Include domain-specific aspects of your graph, relevant labels and relationship types, and which attributes are suitable for aggregation.
Invoking a Text2Cypher tool
When a Text2Cypher tool is invoked, the agent passes the user’s question, the database schema, and the Text2Cypher system prompt to the LLM. The resulting Cypher statement is executed against the graph, and the results are returned to the user.
You can view the generated Cypher statement and results in the reasoning panel.
Check your understanding
Tool Name
What does the Name of a Text2Cypher tool do?
Select the correct answer.
-
❏ It is used as the system prompt sent to the LLM
-
❏ It controls which database schema is supplied to the tool
-
✓ It uniquely identifies the tool in the agent configuration
-
❏ It determines which questions the tool will answer
Hint
The name appears in the agent configuration and in the reasoning panel output when the tool is invoked.
Solution
It uniquely identifies the tool in the agent configuration.
The name labels the tool in the configuration and appears in the reasoning panel when the agent invokes it. The description — not the name — is what the agent uses to decide when to call the tool.
Tool Description
What can you include in a Text2Cypher tool description? Select all that apply.
-
❏ The name of your instance
-
✓ When and when not to use the tool
-
✓ Domain-specific aspects of your graph
-
✓ Which attributes are suitable for aggregation or filtering
-
❏ The entire graph schema
Hint
The database schema is supplied automatically. The description adds context that the schema alone cannot express.
Solution
When and when not to use the tool, domain-specific aspects of your graph, and which attributes are suitable for aggregation or filtering are all useful to include.
The schema is passed to the LLM automatically, so you do not need to list labels, relationship types, or credentials. The description adds the context the schema cannot express — usage guidance and domain knowledge that steers the LLM toward more accurate Cypher.
Summary
In this lesson, you learned that Text2Cypher generates Cypher from natural language at runtime. Use it when the query structure changes between questions.
In the next challenge, you will practice with Text2Cypher: trigger it with ad-hoc questions and inspect the generated Cypher in the reasoning panel.