> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/configuration/tools/search-tool.md).

# Search AI Tool

Let agents find customers or legal entities by name or number with the Search AI Tool.

The Search AI Tool lets an agent look up customers or legal entities of your tenant by name, number, or other details. The tool runs a text search on a search index that Emporix manages for each entity type, so it needs no embeddings or LLM provider. Use it when the agent must find specific records. To find records by meaning rather than by matching terms, use a [RAG Emporix tool](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/configuration/tools/rag/rag-emporix.md) instead.

## Configuring Search tool

To configure a Search tool, follow these steps:

{% stepper %}
{% step %}

#### Add the tool

In **Agentic AI** -> **AI Tools**, choose **Add new tool**. On the **General** tab, set the following fields:

* **Tool Type** – *Search*
* **Tool ID** – Unique identifier of the tool, which you cannot change after saving
* **Tool Name** – Name displayed in the UI
* **Prompt** – Optional instructions that tell the agent when to search

The prompt is added to the tool's built-in description, for example "Use this tool when the user asks about a customer account." If you leave it empty, the agent decides when to search based on the built-in description and its own **User Prompt**.

<figure><img src="https://1530167654-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8GgoeZEZYjZrpjOU6w52%2Fuploads%2Fgit-blob-01b4e15bb613ace0052c7db7c3ce16746f6fa05e%2Fagentic_search_tool.png?alt=media" alt="Search tool General tab"><figcaption><p>Search tool General tab</p></figcaption></figure>
{% endstep %}

{% step %}

#### Choose what the tool searches

On the **Settings** tab, set the following fields:

* **Entity Type** – Type of records the tool searches, either *Customer* or *Legal Entity*
* **Max Results** – Number of records the tool returns for one search, from 1 to 10, with a default of 5

Fewer results keep the agent's context small.
{% endstep %}

{% step %}

#### Save the tool

Choose **Save**. Saving prepares the search index for the selected entity type.
{% endstep %}

{% step %}

#### Load existing records

New and changed customers or legal entities are added to the search index automatically. Records that existed before the index was prepared are not. To add them, choose **Reindex** on the tool in the **AI Tools** list. All Search tools of the same entity type share one index, so you need to do this only once per entity type, not once per tool.

If you are not sure whether a reindex already ran, for example because another Search tool of that entity type exists, you can run it again. A reindex rebuilds the whole index for that entity type, so it can take a long time when there are many records. While the reindex runs, **Reindex** is unavailable for tools of that entity type.
{% endstep %}

{% step %}

#### Attach the tool to an agent

In the agent's **Tools** tab, add the tool under **Native Tools**. For details, see [AI Agents](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/agents.md#attach-tools).
{% endstep %}
{% endstepper %}

## Searched fields

The tool searches the `ai-customer` or `ai-legal-entity` index, depending on the entity type. The index defines which fields the agent can search. Text matching is tolerant of small differences. For example, a search for `Muller` can also find `Müller`, a name can match a similar-sounding spelling, and `Maier` can find `Maier GmbH`. Fields matched exactly let the agent narrow the results, for example by country or type.

| Index             | Matched by text                                                                                                                                                                                                                                                                       | Matched exactly                                                                                                                                                                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ai-customer`     | `firstName`, `middleName`, `lastName`, `title`, `company`, `contactEmail`, `contactPhone`, `customerNumber`, `b2b.companyRegistrationId`, `addresses.street`, `addresses.city`, `addresses.zipCode`, `addresses.companyName`, `b2b.legalEntities.name`                                | `customerNumber`, `b2b.companyRegistrationId`, `addresses.country`, `type`, `businessModel`, `preferredLanguage`, `preferredSite`, `metadata.createdAt`, `b2b.legalEntities._id`                                                                           |
| `ai-legal-entity` | `name`, `legalInfo.legalName`, `legalInfo.taxRegistrationNumber`, `legalInfo.registrationId`, `contacts.name`, `contacts.surname`, `contacts.email`, `contacts.phone`, `entitiesAddresses.name`, `entitiesAddresses.contactDetails.city`, `entitiesAddresses.contactDetails.postcode` | `legalInfo.countryOfRegistration`, `type`, `parentId`, `metadata.createdAt`, `contacts._id`, `contacts.customerId`, `contacts.type`, `contacts.primary`, `entitiesAddresses._id`, `entitiesAddresses.type`, `entitiesAddresses.contactDetails.countryCode` |

## Access to results

The agent finds only the customers or legal entities that the invoking user or integration is allowed to read. If their read access is restricted, the agent finds only the records within those restrictions. If they can read only their own data, the agent finds only their own customer record or the legal entities they are assigned to. To control who can trigger the agent, set its [Required scopes](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/agents.md#define-activation-rules). The same rules apply to [RAG Emporix tools for customers and legal entities](https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/configuration/tools/rag/rag-emporix.md#scoped-retrieval-for-customers-and-legal-entities).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.emporix.io/agentic-commerce-intelligence/agentic-intelligence/configuration/tools/search-tool.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
