To build an effective agent, you need a clear design.
An agent with poorly scoped tools, vague descriptions, or missing relationship context will give inconsistent results even with good data.
In this lesson, you will learn how to define role and scope, map question types to Cypher Template or Text2Cypher, write tool descriptions so the LLM selects the correct tool, and edit, delete, and manage tools and agents.
Design best practices
-
Scope — Prefer one focused agent per task. Create a clear scope for the agent to help the LLM select the correct tools.
-
One tool per pattern — Give each distinct job its own tool when the query or purpose differs. A single template should not try to cover unrelated asks; narrow tools get clearer descriptions and fewer wrong picks.
-
Templates first — If you can write the full Cypher now with only
$parameterslots for values, use a Cypher Template. Reserve Text2Cypher for questions whose structure changes with the ask. -
Descriptions — The LLM picks tools from descriptions only. For each tool, state what it returns and when to use it instead of the others. Skip vague phrases like "get customer data."
-
Text2Cypher fallback — Say when to use it and when not (for example, only when no template fits). Add domain context such as entities and attributes that matter for filters and aggregation. The tool already receives the schema.
-
Save changes — After you add, edit, or delete tools, click Update agent so the running configuration matches what you see in the form.
Role and scope
Define what the agent does and, equally important, what it does not do.
One focused agent per task works better than a general-purpose agent. A narrow scope makes tool selection easier for the LLM and makes the agent’s behavior more predictable.
For example, a Northwind Analyst agent answers questions about customers, orders, products, categories, and suppliers. It does not answer questions about pricing strategy, HR, or anything outside the graph.
Encoding that boundary in the instructions keeps the agent on task. For example, instruct it to politely decline off-topic requests.
Question types
Apply the test from the Using Text2Cypher lesson: can you write the complete Cypher query right now, with only $parameter slots for variable values?
| Test result | Best tool | Example |
|---|---|---|
Yes: the |
Cypher Template |
"Top 10 customers by order count" → fixed |
No: the query structure itself changes depending on what the user asks |
Text2Cypher |
"Which customers ordered products from more than 2 different suppliers?" → the filter count, the multi-hop path, and the aggregation all depend on the question. The structure cannot be pre-written. |
Tool descriptions
The LLM selects tools based solely on their descriptions. It never inspects the Cypher query or the parameter names. A description like "get customer data" is too vague to be useful: if three tools all retrieve data, the LLM has no basis for choosing between them.
Write descriptions that answer two questions:
-
What does this tool return?
-
When should the LLM use it instead of the other tools?
Compare these two descriptions for the same tool:
| Description | Problem |
|---|---|
|
Too vague: could match any question mentioning a customer |
|
Specific: names the parameter type, gives an example value, scopes what it returns |
For your Text2Cypher fallback, the description must state when to use it (and when not). The tool automatically receives the database schema. Add domain-specific context: relevant entities, categorical property patterns, and which attributes are suitable for aggregation. That helps the LLM generate more accurate Cypher.
Use this tool ONLY when no other tool covers the question.
The graph contains: Customer, Order, Product, Category, Supplier nodes.
Relationships: PLACED (Customer→Order), CONTAINS (Order→Product), IN_CATEGORY (Product→Category), SUPPLIES (Supplier→Product).The "ONLY when no other tool covers" constraint prevents the LLM from defaulting to Text2Cypher for questions your templates handle.
The Northwind Analyst agent design
Applying these principles to the Northwind graph produces this design:
| Element | Value |
|---|---|
Role |
Northwind retail analyst |
Scope |
Questions about customers, orders, products, categories, and suppliers. Decline off-topic or harmful requests. |
Cypher Template tools |
Get Customer, Top Customers by Order Count, Products by Category, Get Product |
Text2Cypher tool |
Fallback for ad-hoc questions not covered by the templates above |
When you implement this design, you add tools from the agent configuration with Add Tool → Cypher Template or Text2Cypher.
Once you have built an agent, you can refine it by editing tools, adding new ones, or removing what you no longer need. A Project Admin role is required to change agent configuration. The following sections describe how to edit and delete tools and how to delete an agent.
Review your Northwind agent or the one you created with AI in Module 1 against the design above: check that role and scope are clear, question types map to Cypher Template or Text2Cypher, and tool descriptions are specific enough for the LLM to select the correct tool.
Edit tools
Open any tool in the agent configuration and click the pencil icon to edit it. You can change the name, description, parameters, and Cypher query.
For Cypher Template tools, the edit dialog shows the same fields as when you created the tool: Name, Description, Parameters, and the Cypher query. To edit a parameter, click the pencil icon next to it in the Parameters list and update the name, data type, or description.
You can also rename a tool by editing its Name field. A clearer name helps the LLM when it compares tool descriptions to the user’s question.
After any change to tools—add, edit, or delete—click Update agent to save. The agent keeps using the previous configuration until you do.
Delete tools
To remove a tool, click the trash icon next to it in the tool list.
The tool is removed as soon as you delete it. Click Update agent to persist the change.
Delete an agent
To delete an agent, open the … menu next to the agent in the Agents list and select Delete agent.
A confirmation dialog will appear. Deletion is permanent and removes all associated configuration.
Click Delete agent to confirm.
Deletion is permanent
Deleting an agent cannot be undone. All tools, instructions, and configuration are permanently removed.
Check your understanding
Narrow Scoping
Why is defining a clear role and scope important when designing an agent?
Select the correct answer.
-
❏ It allows the agent to answer as many questions possible question
-
✓ It helps the LLM choose tools more easily and makes the agent’s behavior more predictable
-
❏ It ensures the agent always uses Text2Cypher when thinking is mode is on
-
❏ It prevents the agent from using Cypher queries
Hint
The lesson says one focused agent per task works better than a general-purpose agent, and a narrow scope makes tool selection easier for the LLM.
Solution
It helps the LLM choose tools more easily and makes the agent’s behavior more predictable.
A narrow scope reduces ambiguity: fewer irrelevant tools compete for the same questions, and instructions can state what the agent does and does not do. That does not block Cypher. It does not force Text2Cypher. It does not mean the agent can answer everything.
Summary
A well-designed agent has a narrow scope, uses Cypher Templates for predictable questions, and has specific tool descriptions that give the LLM enough context to make the correct tool selection.
In the next challenge, you will build an agent from scratch with Cypher Template and Text2Cypher tools.