docs(configuration): document parameter required/default semantics and the default: null trap

[AndyFooBlah]

Description

Documents how required and default interact on tool parameters, and the default: null trap.

Parameters are required by default, and supplying a default silently makes one optional — the existing table implies both in single cells (Default to true, If provided, required will be false), but not the interaction, and not the failure mode. Adds an Optional Parameters section under Specifying Parameters with:

• the two ways to make a parameter optional (default: <value> vs required: false) and how they differ for an omitted argument;
• the full required × default matrix;
• a note that the effective requiredness is what reaches the agent in the tool manifest;
• a warning that default: null does not make a parameter optional.

On that last point: YAML parses default: null — and equally default: ~ or a bare default: — to a null value, which CheckParamRequired cannot distinguish from the field being absent:

func CheckParamRequired(required bool, defaultV any) bool {
	return required && defaultV == nil
}

So the parameter stays required, and an agent call that omits the argument fails at invocation time with parameter "..." is required. Writing default: null to mean "optional, no value when omitted" is a natural reading that produces a runtime error instead; required: false is the working spelling. The section also contrasts default: "", which is a real default — only null is ignored.

Docs only; no behavior change.

Verification

Every row of the matrix was exercised through the real YAML parse path (yaml.UnmarshalContext into parameters.Parameters, then Manifest() and ParseParams with the argument omitted) rather than read off the source, including all three null spellings:

config	manifest.Required	omitted-argument call
required omitted, no default	true	parameter "p" is required
required: true, no default	true	parameter "p" is required
required: false, no default	false	passes nil
required: true + default: fallback	false	uses default
required omitted + default: fallback	false	uses default
required omitted + default: ""	false	uses ""
required: true + default: null	true	parameter "p" is required
required omitted + default: null	true	parameter "p" is required
required omitted + default: ~	true	parameter "p" is required
required omitted + bare default:	true	parameter "p" is required

The {{< notice warning >}} shortcode used here is already used elsewhere in the same page.

PR Checklist

• Make sure to open an issue as a bug/issue before writing your code!
• Ensure you have manually reviewed the entire diff before requesting a review
• Ensure the tests and linter pass
• Code coverage does not decrease (if any source code was changed) — no source changes
• Appropriate docs were updated (if necessary)
• Make sure to add ! if this involves a breaking change

Issue Reference

Part of #3639 🦕 — this is gap (2) of the three in that issue, which @anubhav756 and @averikitsch both green-lit as a self-contained first step. Gap (1) is with @wangauone for cloud-gemini-data-analytics-query, and gap (3) was answered as not feasible, so I've left the issue open rather than auto-closing it.

[gemini-code-assist]

Code Review

This pull request updates the documentation in docs/en/documentation/configuration/tools/_index.md to add a new section on 'Optional Parameters'. It explains the default behavior of parameters, the two ways to make them optional (using default or required: false), and warns that default: null does not make a parameter optional. There are no review comments, so no feedback is provided.