# Tool Plugin Settings Reference

> Developer reference for opting one tool family into bounded, read-only settings discovery without changing other families.

- Skill: `lingtai-ai/tool-plugin-settings-reference` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lingtai-ai/tool-plugin-settings-reference`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lingtai-ai/tool-plugin-settings-reference/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: lingtai-ai (https://skillmd.com/u/lingtai-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lingtai-ai/tool-plugin-settings-reference

---

# 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:

```json
{"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 `tests/test_tool_settings_contract.py` plus the opted-in family's real
schema/dispatch/manual tests, and confirm all unrelated declarations remain
opted out.