Preferences

Register the preferences tool suite to read and mutate shared preferences or user defaults under explicit store and key restrictions.

Install

dotnet add package Ansight.Tools.Preferences --prerelease

Register the Suite

using Ansight;
using Ansight.Tools.Preferences;

var options = Options.CreateBuilder()
    .WithPreferencesTools(preferences =>
    {
        preferences.WithDefaultStore("com.example.app");
        preferences.AllowStore("com.example.app");
        preferences.AllowKeyPrefix("ansight.");
    })
    .WithReadWriteToolAccess()
    .Build();

Registration API

WithPreferencesTools(): registers the suite with default platform behavior.
WithPreferencesTools(preferences => ...): configures the allow-lists and default store.
WithDefaultStore(...): set the store used when a tool call omits store.
AllowStore(...) / AllowStores(...): restrict which stores can be queried.
AllowKey(...) / AllowKeys(...): allow specific keys.
AllowKeyPrefix(...) / AllowKeyPrefixes(...): allow groups of keys by prefix.

Specific Concerns

Preference values often include configuration or user state.
Restrict stores, keys, or key prefixes at registration time.
prefs.remove_key is delete-scoped and stays blocked unless you use WithAllToolAccess() or a custom ToolGuard.
Non-string values are normalized into strings plus a valueType.
string_array values are represented as JSON arrays encoded in the returned value string.

Available registration constraints:

WithDefaultStore(...)
AllowStore(...) / AllowStores(...)
AllowKey(...) / AllowKeys(...)
AllowKeyPrefix(...) / AllowKeyPrefixes(...)

Tool Matrix

Name	Id	Scope	Description	Security
`List Preference Keys`	`prefs.list_keys`	`Read`	Lists keys from a shared preferences or user defaults store.	Moderate
`Get Preference Value`	`prefs.get_value`	`Read`	Reads a value from shared preferences or user defaults.	High
`Set Preference Value`	`prefs.set_value`	`Write`	Writes a value into shared preferences or user defaults.	High
`Remove Preference Key`	`prefs.remove_key`	`Delete`	Deletes a key from shared preferences or user defaults.	High

List Preference Keys

Arguments:

store: optional store or suite name
prefix: optional key prefix filter
maxResults

Returns:

store
keys
truncated
capturedAtUtc

Example:

{
  "toolId": "prefs.list_keys",
  "arguments": {
    "store": "com.example.app",
    "prefix": "ansight.",
    "maxResults": 100
  }
}

Get Preference Value

Arguments:

key: required key
store: optional store override

Returns:

store
key
exists
value
valueType
capturedAtUtc

When valueType is string_array, value contains a JSON array string.

Example:

{
  "toolId": "prefs.get_value",
  "arguments": {
    "store": "com.example.app",
    "key": "ansight.last_session"
  }
}

Set Preference Value

Arguments:

key: required key
value: required stringified value
valueType: one of string, boolean, integer, number, string_array
store: optional store override

Returns:

store
key
valueType
updated
capturedAtUtc

Example:

{
  "toolId": "prefs.set_value",
  "arguments": {
    "store": "com.example.app",
    "key": "ansight.enabled",
    "value": "true",
    "valueType": "boolean"
  }
}

Remove Preference Key

Arguments:

key: required key
store: optional store override

Returns:

store
key
removed
capturedAtUtc

Example:

{
  "toolId": "prefs.remove_key",
  "arguments": {
    "store": "com.example.app",
    "key": "ansight.last_session"
  }
}

This tool is delete-scoped. Use it sparingly.