Tool Plugin Settings Reference

Test-reference maintenance (2026-10-12): retired-test: identifiers below name removed pytest coverage, not runnable selectors or replacement conformance. Product promises are unchanged; manual acceptance remains necessary where automated coverage was surrendered.

ToolFamily settings SHOW reference

Use this for one bounded family-owner change at a time. Production families opt in only through their own reviewed vertical change; no owner document or another family's opt-in enables them implicitly.

Opt in

1. Set settings=True on the ToolPluginDeclaration or CuratedMcpPlugin.
2. Bind a callable settings_provider to ToolFamily; the declaration opt-in plus this bound provider makes SHOW available. The presence of an owner document does not opt a family in.
3. The provider returns a fresh iterable of public SettingRow values and performs no configuration change.
4. Supply exactly key, current, default, configurable, and comment. comment is the exact family-manual section pointer. Use None when the owner has no meaningful default; raise if the current value is unavailable.
5. Put meaning, accepted values, source and precedence, config/environment key, apply timing, and the real change procedure in that manual section. Do not copy those details into each row.
6. Set the private _sensitive=True flag only when current and default must both render as <redacted>; the flag itself is never projected.

System's settings/system.json is closed and versioned. A v1 document is exactly the cache-miss-budget source. A v2 document may carry any subset of the seven ordinary System runtime-policy fields, the cache field, and Notification's file-layer cap. It may be absent; documented defaults then apply and the declaration-bound SHOW provider remains available. File presence still does not opt the family into SHOW.

Read contract

settings(input={}) is the only operation. Normal success is exactly this shape, with no projected status or extra row metadata:

{"settings":[{"key":"example.timeout","current":30,"default":15,"configurable":true,"comment":"example-manual#timeout"}]}

Any provider exception, unavailable current, malformed row, or non-JSON display value returns one fixed bounded failure with no partial rows or exception text. The complete response is measured while rows are consumed and stops at 65,536 UTF-8 bytes; oversize output becomes one fixed no-row failure.

Verify

Run retired-test:test_tool_settings_contract plus the opted-in family's real schema/dispatch/manual tests, and confirm all unrelated declarations remain opted out.