[agent builder] Add note about esql limitations, example parameterized query (elastic#3500)

Author: leemthompo

solutions/search/agent-builder/images/create-esql-tool-query.png

@@ -42,6 +42,12 @@ Error: Invalid function call syntax
 Error executing agent: No tool calls found in the response.
 ```
 
+### {{esql}} limitations
+
+{{esql}} tools are subject to the current limitations of the {{esql}} language itself. For example, [named parameters](elasticsearch://reference/query-languages/esql/esql-syntax.md#esql-function-named-params) (`?parameter_name`) do not currently work with the `LIKE` and `RLIKE` operators ([issue #131356](https://github.com/elastic/elasticsearch/issues/131356)).
+
+For a complete list of {{esql}} limitations, refer to the the [{{esql}} limitations documentation](elasticsearch://reference/query-languages/esql/limitations.md).
+
 ### Misinterpreted SQL syntax as ES|QL
 
 The `.execute_esql` tool is designed only for [{{esql}}](elasticsearch://reference/query-languages/esql.md) syntax, not other query languages.

solutions/search/agent-builder/limitations-known-issues.md

@@ -52,13 +52,34 @@ Parameters can be configured as:
 
 In your {{esql}} query, reference parameters using the `?parameter_name` syntax. The agent will automatically interpolate parameter values when executing the query.
 
+### Example
+
+Here's an example {{esql}} tool that searches for books using full-text search. `?search_terms` is a named parameter that the agent will provide when executing the query. 
+
+```esql
+FROM books
+| WHERE MATCH(title, ?search_terms)
+| KEEP title, author, year
+| LIMIT 10
+```
+
+You can ask the LLM to infer the parameters for the query or add them manually.
+
+:::{image} ../images/create-esql-tool-query.png 
+:alt: Creating an ES|QL tool with a parameterized query
+:::
 
 ## Best practices
 
-- **Include LIMIT clauses**: Prevent returning excessive results by setting reasonable limits
+- **Include [`LIMIT`](elasticsearch://reference/query-languages/esql/commands/limit.md) clauses**: Prevent returning excessive results by setting reasonable limits
 - **Use meaningful parameter names**: Choose names that clearly indicate what the parameter represents (e.g., `start_date` instead of `date1`)
+- **Define parameter types**: Ensure parameters have the correct type to avoid runtime errors
 - **Provide clear descriptions**: Help agents understand when and how to use each parameter
 
+## Limitations
+
+{{esql}} tools are subject to the current limitations of the {{esql}} language itself. For more information, refer to [{{esql}} tool limitations](../limitations-known-issues.md#esql-limitations).
+
 ## {{esql}} documentation
 
 To learn more about the language, refer to the [{{esql}} docs](elasticsearch://reference/query-languages/esql.md).