Tools

Introduced 0.5.0

A tool performs a set of specific tasks. The following table lists all tools that Lucenia supports.

Specify a tool by providing its type, parameters, and, optionally, a description. For example, you can specify an AgentTool as follows:

{
  "type": "AgentTool",
  "description": "A general agent to answer any question",
  "parameters": {
    "agent_id": "9X7xWI0Bpc3sThaJdY9i"
  }
}

Each tool takes a list of parameters specific to that tool. In the preceding example, the AgentTool takes an agent_id of the agent it will run. For a list of parameters, see each tool's documentation.

To list the tools registered on a running cluster — the authoritative inventory for the version you are on — use the List Tools API:

GET /_plugins/_agent/tools

The response contains the name, type, description, and version of every registered tool type.

Register and run

Register agents and list tools under /_plugins/_agent. Execute an agent with:

POST /_plugins/_ml/agents/<agent_id>/_execute

That execute path is unchanged from earlier releases. See Execute an agent.

Each tool has a type you put in the agent spec (GeoLayerTool) and a default prompt name the model reads (FindFeatures). If you set "name" on the tool, that is the string the model sees. Pin stable arguments (index, time_field, search_pipeline) in the register body. A conversational agent fills per-question arguments (query, uri, baseline, id, from, to, like) from the model. A flow agent has no model: pass those keys on _execute. The runner copies execute parameters onto the tool by name.

Where a tool's parameter table lists query or filter as a phrase, the value is a query_string expression. RAGTool's filter and SearchIndexTool's query are Query DSL objects.

A flow agent runs tools in a fixed order. For an analyst that must choose among map, similarity, change, and release tools, register a conversational agent and list several tools. Pin indexes at register time; raise llm.parameters.max_iteration so the model can call more than the default three steps. See Agents and tools tutorial.

Date fields used by FindChanges and WhenWasThisImaged must exist on the region documents. The vectorize processor can stamp captured_at when you set that parameter.

Tool	Description
AgentTool	Runs another agent by its agent ID.
CatIndexTool	Retrieves detailed index information for the Lucenia cluster (health, status, document counts, and store sizes).
ChangeDetectionTool	Compares two time windows over indexed regions and reports what appeared, disappeared, grew, and shrank. Presented to an agent as FindChanges.
CheckAnalysisTool	Checks analysis code an agent authored against an allowlist before anything runs it, and states how much of it was actually examined. Executes nothing. Presented to an agent as CheckAnalysis.
ComplianceTool	Reports kinds, counts, and offsets of sensitive matches in text, and what a named profile applies. Presented to an agent as CheckCompliance.
ConceptSearchTool	Finds every document about a subject by expanding a concept through the vocabulary, and states its linked coverage. Presented to an agent as FindByMeaning.
ConnectorTool	Invokes an external service through a configured connector.
ContourTool	Finds where documents are concentrated, returning nested regions of density rather than a single bounding box. Presented to an agent as FindConcentrations.
DisseminationTool	Checks whether a scene may go to a named recipient, based on licence, marking, embargo, and origin. Presented to an agent as CheckDissemination.
GeoLayerTool	Finds where matching features are: count, extent, a GeoJSON sample, and a vector tile URL. Presented to an agent as FindFeatures.
GeoLineTool	Traces the path each moving thing travelled, stating for every path whether it is complete or was shortened. Presented to an agent as FindTracks.
ImageRegionsTool	Reads a raster and returns labelled polygons as the tool answer. Presented to an agent as FindImageRegions.
IndexMappingTool	Retrieves mapping and setting information for one or more indexes.
ListIndexTool	Lists the indexes in the cluster, along with their health, status, and document counts.
McpSseTool	Invokes a tool hosted on a remote Model Context Protocol (MCP) server. Registered by the cluster when an MCP connector discovers the remote tool rather than declared directly. See Using MCP tools.
MLModelTool	Runs any deployed machine learning model by its model ID.
QueryPlanningTool	Turns a natural-language question into a Lucenia query (query DSL) using an LLM.
RAGTool	Retrieves with a k-NN search, then asks a generation model to answer using the retrieved context.
ReadFromScratchPadTool	Reads back the notes an agent saved to its per-conversation scratchpad.
ReportTool	Assembles findings already gathered into a printable report, with every section attributed to its source. Presented to an agent as WriteReport.
ReprojectImageryTool	Fetches imagery a search pipeline has already reprojected into target_crs. Presented to an agent as FindReprojectedImagery.
RouteTool	Finds a path between two nodes on an indexed network. Presented to an agent as FindRoute.
SearchIndexTool	Searches an index using a query written in query domain-specific language (DSL).
SimilarImageryTool	Finds imagery that looks like a given image, from a stored document or a URL. Presented to an agent as FindSimilarImagery.
TemporalCoverageTool	Reports when a place was imaged and where the gaps in coverage are. Presented to an agent as WhenWasThisImaged.
VectorDBTool	Embeds your query text and runs a k-NN search, returning the matching documents as context.
VisualizationTool	Finds saved visualizations by matching a search term against their titles.
WriteToScratchPadTool	Saves a short note to an agent's per-conversation scratchpad for later recall.

note

Two names in the shipped modules/agent JAR differ from the type you write in a request:

• The class VisualizationsTool registers the type VisualizationTool (no s). Always use the type.
• McpSseTool is a registered type, but it only functions once bound to an MCP client, so it does not appear in the MCP built-in tool registry while unbound.

For the tool surface alongside the ingest and search processor surfaces, see the Tools and processors reference.

Developer information

The agents and tools framework is flexible and extensible. The built-in tools ship with the agent module (modules/agent/src/main/java/io/lucenia/agent/tools). For a different use case, you can build your own tool by implementing the Tool interface (libs/ml/src/main/java/io/skylite/ml/common/engine/tools/Tool.java).