tool_search

Tool Search adds tool plugins (via the Tool module) for working with Search API indexes. It ships two tools: search_index searches an index and returns the matching results, and index_words_exist checks — word by word — whether a list of words is present in an index.

The search_index tool is backend-agnostic: it works against database indexes (search_api_db) and AI/vector indexes (search_api_ai_search) alike. The index_words_exist tool is for keyword/database indexes, where checking whether an exact word is present is meaningful. Both are usable on their own (for example via the Tool Explorer) and are automatically exposed to AI agents when tool_ai_connector is installed (as tool:search_index and tool:index_words_exist).

Requirements

• Tool (tool)
• Search API (search_api)

Tool: Search index (search_index)

Searches a Search API index and returns the matching results, either as markdown or as rendered entity output.

Input Type Required Default Description index string yes — Search API index id to search. search_words string yes — The words or phrase to search for. conjunction string no OR How to combine multiple words: OR matches any word, AND requires all. amount integer no 10 Maximum number of results per page. page integer no 0 Zero-based page of results. Page 0 is the first set, page 1 the next, and so on. min_score float no 0.0 Minimum relevance score to include. check_access boolean no true Exclude results the current user may not view. See Access below. output_format string no markdown Either markdown or rendered. view_mode string no search_index View mode used when output_format is rendered. fields string[] no — In markdown output, only show these indexed fields (by machine name). Empty shows all.

In markdown mode each result is one block: a heading (the result label), the score, the URL, a bullet for every indexed field (label and value), and finally the excerpt or RAG snippet. In rendered mode each result entity is rendered through the given view mode (falling back to default) and the markup is returned in the structured results output. In both modes the structured results output also includes a fields map of every indexed field per result.

Multiple words are combined with OR by default (matching any word); set conjunction to AND to require every word. Results are paged: each call returns one page of amount results, and the message reports the total and whether a further page is available so the caller can request the next page.

Tool: Check words in index (index_words_exist)

Takes a list of space-separated words and checks each one individually against an index, reporting how many items match each word. It is intended for keyword/database indexes where exact-word presence is meaningful.

Input Type Required Default Description index string yes — Search API index id to check. search_words string yes — Words separated by spaces; each is checked on its own. check_access boolean no true Count only items the current user may view (checked up to 100 per word). See Access below.

The readable output is a compact CSV optimised for agents: a word,count header followed by one row per word, where a count of 0 means the word was not found.

word,count
santa,3
style,5
unicorn,0

The structured results output mirrors this as a list of {word, count} records, one per word, in input order.

Access

Search API does not enforce per-item view access on a query unless the index has an access-control processor (for example Content access for nodes, or Role access). Without one, a raw query — and therefore these tools — could otherwise reveal indexed content (or, for index_words_exist, confirm that a term exists and how many items contain it) to users who cannot view that content.

To prevent this, both tools take a check_access input that defaults to true. The search_index tool loads each match and excludes any result the current user cannot view. The index_words_exist tool counts only viewable matches, inspecting up to 100 matches per word, so a reported count is a lower bound when a word matches more than 100 items.

Set check_access to false only when the index carries its own access control or the content is non-sensitive; this trusts the backend's results, skips the per-item checks, is faster, and gives exact counts.

Note: hopefully this will be baked into the Search API module in the future, if Tool API becomes a standard. Note: access is checked against the entity behind each result. Results with no backing entity (for example raw vector chunks) cannot be checked in code and rely entirely on the index's own access configuration.