Tools

Create retrieval tools your agent can use to query the warehouse

Overview

Tools let you define curated retrieval behaviors that your AI agent can call. A tool encapsulates three things:

• Name and description visible to the agent
• A retrieval method (chunks, objects, or a Cypher template)
• A search scope (documents and tags)

Use this guide to create a new tool in three steps.

1) General

On the General tab, provide:

• Name: a short action‑oriented label (e.g., “Search policies by tag”)
• Description: optional guidance for the agent describing when to use the tool and what it returns

Keep names specific so the agent can pick the right tool during routing.

2) Retrieval Method

Choose how the tool finds information. The selector offers three types:

• Search on chunks: search within chunk text
• Search on objects: search within the textual representation of extracted objects
• Templated search on objects: execute a parameterized Cypher query against the object graph

For Search on chunks and Search on objects, configure:

• Mode: Semantic (default), Full‑text, or Hybrid
• Query reformulation: enable HyDE‑style expansion to improve recall on vague queries
• Optimal reranking: re‑rank candidates for higher precision
• Number of objects: maximum items to return; optionally force the exact count
• Enrich with chunks (objects search): include the source chunk content alongside objects

For Templated search on objects, provide a Cypher query template. Parameters are supplied by the agent at runtime using $param syntax. Example:

MATCH (n:Person) WHERE n.name = $name RETURN n

When the agent calls this tool, it will set $name based on the user request and return the matching objects.

3) Search Scope

Limit where the tool searches:

• Documents: include all documents or select specific ones
• Include/Exclude tags: filter chunks and objects by tags. You can either:
  • Include all tags
  • Let Clarifeye decide the suitable selection
  • Select explicit tags to include/exclude

Tag filters apply to both chunks and objects (objects inherit the tags of their source chunk).

Usage tips

• Create multiple focused tools instead of a single broad one (e.g., a chunk search tool for policy sections, and an object search tool for a specific schema)
• Turn on reranking for long or multi‑intent queries
• Use query reformulation when users commonly ask underspecified questions
• Prefer a Cypher template when you need precise graph constraints or field‑level matching