[agent builder] Document default values for optional params in ESQL tools

[leemthompo]

Narrative docs (i.e. handwitten docs) component of #4007

Note

I'm not up to speed on why the frontend component of this work was paused, so I might be missing a lot of context here, but still felt it was easier to get started with a PR 🙂

👁️👁️ URL preview links

Summary

• Added default value support for ES|QL tool optional parameters (9.3+)
• Updated narrative docs with version-conditional content (9.2 uses null, 9.3 requires defaults)
• Added "Default values for optional parameters" section with API-only notice
• Created new API example showing tool creation with defaultValue fields
• Updated best practices to recommend sensible defaults

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

Tool(s) and model(s) used: Claude Code, Opus 4.1.

[github-actions]

Vale Linting Results

Summary: 1 suggestion found

💡 Suggestions (1)

File	Line	Rule	Message
solutions/search/agent-builder/tools/esql-tools.md	11	Elastic.Capitalization	'tools' should use sentence-style capitalization.

[github-actions]

🔍 Preview links for changed docs

• solutions/search/agent-builder/kibana-api.md
• solutions/search/agent-builder/tools/esql-tools.md

[chrisbmar]

defaultValue is still optional in the API when using optional: true - I will have to find the Slack thread as to why we never made this field required on the API when optional was set to true 🤔 it might have been to do with backwards compatibility, but I will check and get back to you.

We definitely are planning on making it appear on the UI as required though when a user selects that a tool parameter is optional. However, the reason we never merged the frontend changes are purely due to the fact that we haven't had design resources yet to tell us how to show an input box for the defaultValue when a user selects that a parameter is optional.. there isn't a lot of space to just add this in conditionally when a user selects that a parameter is optional (see screenshot before from the POC I created with no design input).

I hope what you've done in this PR won't be wasted work..