Understand the saved settings affecting app behavior

Inspect approved preference values in your .NET app and make targeted changes during local debugging.

Preferences tools help explain behavior that depends on saved configuration or user state. Read the allowed stores and keys, then enable writes or removal only when you need to test or repair a specific setting.

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 uses ToolPolicy.Critical and stays blocked unless you use WithAllToolAccess() or a critical-enabled 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	Policy	Description
`List Preference Keys`	`prefs.list_keys`	`Read`	Lists keys from a shared preferences or user defaults store.
`Get Preference Value`	`prefs.get_value`	`Read`	Reads a value from shared preferences or user defaults.
`Set Preference Value`	`prefs.set_value`	`Write`	Writes a value into shared preferences or user defaults.
`Remove Preference Key`	`prefs.remove_key`	`Critical`	Deletes a key from shared preferences or user defaults.

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 uses ToolPolicy.Critical. Use it sparingly.