Skip to content

Add execute tool API doc #11214

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 13, 2025
Merged

Add execute tool API doc #11214

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d252659
Add execute tool API doc
nathaliellenaa Oct 10, 2025
8c83c17
Address comments
nathaliellenaa Oct 13, 2025
4aaf7ec
Apply suggestions from code review
natebower Oct 13, 2025
550db36
Doc review
kolchfa-aws Oct 13, 2025
5efa604
Update _ml-commons-plugin/agents-tools/tools/search-index-tool.md
natebower Oct 13, 2025
92776b0
Apply suggestions from code review
kolchfa-aws Oct 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion _ml-commons-plugin/agents-tools/tools/agent-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,4 +104,8 @@ The following table lists all tool parameters that are available when running th

Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`question` | String | Required | The natural language question to send to the LLM.
`question` | String | Required | The natural language question to send to the LLM.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
6 changes: 5 additions & 1 deletion _ml-commons-plugin/agents-tools/tools/connector-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,4 +165,8 @@ When running the agent, you can define any parameter needed for the API call in
"request_body": "{ \"number1\":\"${parameters.number1}\", \"number2\":\"${parameters.number2}\" }"
}
]
```
```

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
4 changes: 4 additions & 0 deletions _ml-commons-plugin/agents-tools/tools/create-anomaly-detector.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,3 +167,7 @@ The following table lists the available tool parameters for running the agent.
Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`index` | String | Required | The index name. Supports wildcards (for example, `weblogs-*`). If wildcards are used, then the tool fetches mappings from the first resolved index and sends them to the LLM.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
4 changes: 4 additions & 0 deletions _ml-commons-plugin/agents-tools/tools/data-distribution-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,6 +195,10 @@ The following table lists the available tool parameters for running the agent.
| `dsl` | String | Optional | A complete raw DSL query as a JSON string. If provided, takes precedence over the `filter` parameter. |
| `ppl` | String | Optional | A complete PPL statement without time information. Used when `queryType` is `ppl`. |

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.

## Limitations

The Data Distribution tool has the following limitations:
Expand Down
6 changes: 5 additions & 1 deletion _ml-commons-plugin/agents-tools/tools/index-mapping-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,4 +117,8 @@ The following table lists all tool parameters that are available when running th
Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`question` | String | Required | The natural language question to send to the LLM.
`index` | Array | Optional | A comma-delimited list of one or more indexes for which to obtain mapping and setting information. Default is an empty list, which means all indexes.
`index` | Array | Optional | A comma-delimited list of one or more indexes for which to obtain mapping and setting information. Default is an empty list, which means all indexes.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
2 changes: 2 additions & 0 deletions _ml-commons-plugin/agents-tools/tools/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ Specify a tool by providing its `type`, `parameters`, and, optionally, a `descri

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.

You can also run tools directly without creating an agent using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/), which is useful for testing individual tools or performing standalone operations.

|Tool | Description |
|:--- |:--- |
|[`AgentTool`]({{site.url}}{{site.baseurl}}/ml-commons-plugin/agents-tools/tools/agent-tool/) |Runs any agent. |
Expand Down
6 changes: 5 additions & 1 deletion _ml-commons-plugin/agents-tools/tools/list-index-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,4 +130,8 @@ The following table lists all tool parameters that are available when running th

Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`question` | String | Required | The natural language question to send to the LLM.
`question` | String | Required | The natural language question to send to the LLM.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
6 changes: 5 additions & 1 deletion _ml-commons-plugin/agents-tools/tools/log-pattern-analysis-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ grand_parent: Agents and tools
{: .label .label-purple }
<!-- vale on -->

The `LogPatternAnalysisTool` performs an advanced log analysis by detecting anomalous log patterns and sequences through comparative analysis between baseline and selection time ranges. It supports the following analysis modes:
The `LogPatternAnalysisTool` performs an advanced log analysis by detecting anomalous log patterns and sequences through comparative analysis between baseline and selection time ranges. It supports the following analysis modes:

- Log sequence analysis (with trace correlation)
- Log pattern difference analysis
Expand Down Expand Up @@ -192,6 +192,10 @@ The following table lists the available tool parameters for running the agent.
| `selectionTimeRangeStart` | String | Required | The start time for the analysis target period, in UTC date string format (for example, `2025-06-24 07:50:26`). |
| `selectionTimeRangeEnd` | String | Required | The end time for the analysis target period, in UTC date string format (for example, `2025-06-24 07:55:56`). |

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.

## Limitations

The Log Pattern Analysis tool has the following limitations:
Expand Down
6 changes: 5 additions & 1 deletion _ml-commons-plugin/agents-tools/tools/log-pattern-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,4 +117,8 @@ Parameter | Type | Required/Optional | Description
:--- | :--- |:-----------------------| :---
| `index` | String | Required for DSL queries | The index to search for pattern analysis. |
| `input` | String | Required for DSL queries | A DSL query JSON as a string. If both `input` and `ppl` are provided, `input` (DSL) takes precedence. |
| `ppl` | String | Required for PPL queries | A PPL query string. Ignored if `input` is also provided. |
| `ppl` | String | Required for PPL queries | A PPL query string. Ignored if `input` is also provided. |

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
8 changes: 6 additions & 2 deletions _ml-commons-plugin/agents-tools/tools/ml-model-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ plugins.ml_commons.rag_pipeline_feature_enabled: true
{: .label .label-purple }
<!-- vale on -->

The `MLModelTool` runs a machine learning (ML) model and returns inference results.
The `MLModelTool` runs a machine learning (ML) model and returns inference results.

## Step 1: Create a connector for a model

Expand Down Expand Up @@ -164,4 +164,8 @@ The following table lists all tool parameters that are available when running th

Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`question` | String | Required | The natural language question to send to the LLM.
`question` | String | Required | The natural language question to send to the LLM.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
5 changes: 5 additions & 0 deletions _ml-commons-plugin/agents-tools/tools/neural-sparse-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,3 +221,8 @@ The following table lists all tool parameters that are available when running th
Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`question` | String | Required | The natural language question to send to the LLM.


## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
8 changes: 6 additions & 2 deletions _ml-commons-plugin/agents-tools/tools/ppl-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ grand_parent: Agents and tools
**Introduced 2.13**
{: .label .label-purple }

The `PPLTool` translates natural language into a PPL query. The tool provides an `execute` flag to specify whether to run the query. If you set the flag to `true`, the `PPLTool` runs the query and returns the query and the results.
The `PPLTool` translates natural language into a PPL query. The tool provides an `execute` flag to specify whether to run the query. If you set the flag to `true`, the `PPLTool` runs the query and returns the query and the results.

## Prerequisite

Expand Down Expand Up @@ -201,4 +201,8 @@ Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`index` | String | Required | The index on which to run the PPL query.
`question` | String | Required | The natural language question to send to the LLM.
`verbose` | Boolean | Optional | Whether to provide verbose output. Default is `false`.
`verbose` | Boolean | Optional | Whether to provide verbose output. Default is `false`.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
6 changes: 5 additions & 1 deletion _ml-commons-plugin/agents-tools/tools/query-planning-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ grand_parent: Agents and tools
{: .label .label-purple }
<!-- vale on -->

The `QueryPlanningTool` generates an OpenSearch query domain-specific language (DSL) query from a natural language question. It is a core component of [agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/index/), which enables natural language query processing through agent-driven workflows.
The `QueryPlanningTool` generates an OpenSearch query domain-specific language (DSL) query from a natural language question. It is a core component of [agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/index/), which enables natural language query processing through agent-driven workflows.

The `QueryPlanningTool` supports two approaches for generating DSL queries from natural language questions:

Expand Down Expand Up @@ -522,6 +522,10 @@ GIVE THE OUTPUT PART ONLY IN YOUR RESPONSE (a single JSON object)
Output:
```

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.

## Related pages

- [Agentic search]({{site.url}}{{site.baseurl}}/vector-search/ai-search/agentic-search/index)
6 changes: 5 additions & 1 deletion _ml-commons-plugin/agents-tools/tools/rag-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,4 +144,8 @@ The following table lists all tool parameters that are available when running th

Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`question` | String | Required | The natural language question to send to the LLM.
`question` | String | Required | The natural language question to send to the LLM.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
4 changes: 4 additions & 0 deletions _ml-commons-plugin/agents-tools/tools/search-alerts-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,3 +122,7 @@ The following table lists all tool parameters that are available when running th
Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`question` | String | Required | The natural language question to send to the LLM.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
4 changes: 4 additions & 0 deletions _ml-commons-plugin/agents-tools/tools/search-anomaly-detectors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,3 +107,7 @@ The following table lists all tool parameters that are available when running th
Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`question` | String | Required | The natural language question to send to the LLM.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
4 changes: 4 additions & 0 deletions _ml-commons-plugin/agents-tools/tools/search-anomaly-results.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,3 +121,7 @@ The following table lists all tool parameters that are available when running th
Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`question` | String | Required | The natural language question to send to the LLM.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
6 changes: 5 additions & 1 deletion _ml-commons-plugin/agents-tools/tools/search-index-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,4 +117,8 @@ The following table lists all tool parameters that are available when registerin

Parameter | Type | Description
:--- | :--- | :---
`input`| String | The index name and the query to use for search, in JSON format. The `index` parameter contains the name of the index and the `query` parameter contains the query formatted in Query DSL. For example, `"{\"index\": \"opensearch_dashboards_sample_data_ecommerce\", \"query\": {\"size\": 22, \"_source\": \"category\"}}"`. The `input` parameter and the `index` and `query` parameters it contains are required.
`input`| String | The index name and the query to use for search, in JSON format. The `index` parameter contains the name of the index and the `query` parameter contains the query formatted in Query DSL. For example, `"{\"index\": \"opensearch_dashboards_sample_data_ecommerce\", \"query\": {\"size\": 22, \"_source\": \"category\"}}"`. The `input` parameter and the `index` and `query` parameters it contains are required.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
4 changes: 4 additions & 0 deletions _ml-commons-plugin/agents-tools/tools/search-monitors-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,3 +122,7 @@ The following table lists all tool parameters that are available when running th
Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`question` | String | Required | The natural language question to send to the LLM.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
4 changes: 4 additions & 0 deletions _ml-commons-plugin/agents-tools/tools/vector-db-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,3 +234,7 @@ The following table lists all tool parameters that are available when running th
Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`question` | String | Required | The natural language question to send to the LLM.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
6 changes: 5 additions & 1 deletion _ml-commons-plugin/agents-tools/tools/visualization-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ grand_parent: Agents and tools
**Introduced 2.13**
{: .label .label-purple }

Use the `VisualizationTool` to find visualizations relevant to a question.
Use the `VisualizationTool` to find visualizations relevant to a question.

## Step 1: Register a flow agent that will run the VisualizationTool

Expand Down Expand Up @@ -101,3 +101,7 @@ The following table lists all tool parameters that are available when running th
Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`question` | String | Required | The natural language question to send to the LLM.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
6 changes: 5 additions & 1 deletion _ml-commons-plugin/agents-tools/tools/web-search-tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -319,4 +319,8 @@ The following table lists all tool parameters that are available when running th

Parameter | Type | Required/Optional | Description
:--- | :--- | :--- | :---
`question` | String | Required | The natural language question to send to the LLM.
`question` | String | Required | The natural language question to send to the LLM.

## Testing the tool

You can run this tool either as part of an agent workflow or independently using the [Execute Tool API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-tool/). The Execute Tool API is useful for testing individual tools or performing standalone operations.
Loading