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

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.