Tools

Add native iOS remote tool suites, artifact providers, or custom app tools, gate them with the iOS build opt-in and ToolGuard, and keep them limited to local development workflows.

Remote tools let Ansight Studio and MCP clients inspect or operate on a paired iOS app. Keep them scoped to local development and QA builds.

Important Security Rule

Do not ship native tool suites in TestFlight, App Store, CI release, or other distributable builds unless the capability is explicitly approved.

Do this:

add the aggregate Ansight product or individual tool products only to local development builds
set ANSIGHT_ALLOW_REMOTE_TOOLS=true only for those local builds
use the narrowest runtime guard that works for the workflow

Do not do this:

ship tool products in distribution builds
leave ANSIGHT_ALLOW_REMOTE_TOOLS=true in shared release configuration
expose write or delete tools when read-only inspection is enough

Build-Time Opt-In

export ANSIGHT_ALLOW_REMOTE_TOOLS=true

Without this local-development opt-in, the SwiftPM build tool and CocoaPods build phase fail when they detect concrete AnsightTool implementations.

Runtime Registration

The aggregate Ansight product registers the standard native tool suites for you:

import Ansight

let options = try AnsightOptions.createBuilder(.ansightDeveloperDefaults)
    .withReadOnlyToolAccess()
    .build()

try AnsightRuntime.shared.initializeAndActivateAnsightSdk(options: options)

Core-only apps can register suites directly:

import AnsightCore
import AnsightToolsDatabase
import AnsightToolsFileSystem
import AnsightToolsPreferences
import AnsightToolsReflection
import AnsightToolsSecureStorage
import AnsightToolsVisualTree

try AnsightRuntime.shared.registerVisualTreeTools()
try AnsightRuntime.shared.registerDatabaseTools()
try AnsightRuntime.shared.registerFileSystemTools()
try AnsightRuntime.shared.registerPreferencesTools()
try AnsightRuntime.shared.registerReflectionTools()
try AnsightRuntime.shared.registerSecureStorageTools()

Registered tools stay hidden and unusable until toolGuard allows their scope.

Suite Registration API

Suite	Product	Common registration API
VisualTree	`AnsightToolsVisualTree`	`registerVisualTreeTools()`
Database	`AnsightToolsDatabase`	`registerDatabaseTools(options:)`, `AnsightDatabaseToolsOptions.createBuilder()`, `addRoot(alias:path:)`, `includePlatformRoots(...)`
FileSystem	`AnsightToolsFileSystem`	`registerFileSystemTools(options:)`, `AnsightFileSystemToolsOptions.createBuilder()`, `addRoot(alias:path:)`
Preferences	`AnsightToolsPreferences`	`registerPreferencesTools(options:)`, `AnsightPreferencesToolOptions(defaultStore:allowedStores:allowedKeys:allowedKeyPrefixes:)`
SecureStorage	`AnsightToolsSecureStorage`	`registerSecureStorageTools(options:)`, `AnsightSecureStorageToolsOptions.createBuilder()`, `withStorageIdentifier(...)`, `withAppleService(...)`, `allowKey(...)`, `allowKeyPrefix(...)`
Reflection	`AnsightToolsReflection`	`AnsightReflectionRootRegistry.register(...)`, `registerGetter(...)`, `deregister(...)`, `clear()`, `registerReflectionTools(options:)`, `AnsightReflectionToolsOptions.createBuilder()`, `allowRoot(...)`, `allowTypePrefix(...)`
Custom Tools	app code	`registerTool(_:)`, `registerTool(_:replaceExisting:)`, `isToolRegistered(...)`
Artifacts	`AnsightCore` / `Ansight`	`registerArtifactProvider(...)`, `registerArtifactProviders(...)`, `unregisterArtifactProvider(...)`, `clearArtifactProviders()`

Guard Levels

Guard	What it allows
`withToolsDisabled()` / `.disabled`	No discovery, no execution.
`withReadOnlyToolAccess()` / `.readOnly`	Read-scoped tools only.
`withReadWriteToolAccess()` / `.readWrite`	Read and write tools. Delete tools remain blocked.
`withAllToolAccess()` / `.fullAccess`	Read, write, and delete tools.

Tool Suites

Artifacts are a core provider model rather than a separate native tool package. Registering an artifact provider adds the read-scoped artifacts.query and artifacts.request tools. See Artifacts.

Suite	Product	Typical use
VisualTree	`AnsightToolsVisualTree`	Inspect the foreground UIKit hierarchy, capture screenshots, and manage diagnostic overlays.
Database	`AnsightToolsDatabase`	Discover SQLite databases, inspect schema, and run read-only queries.
FileSystem	`AnsightToolsFileSystem`	List directories, read files, download files, push, copy, move, and delete files inside approved roots.
Preferences	`AnsightToolsPreferences`	Read and mutate `UserDefaults` values under store/key allow-lists.
SecureStorage	`AnsightToolsSecureStorage`	Read and mutate Keychain values under explicit key allow-lists.
Reflection	`AnsightToolsReflection`	Inspect explicitly registered live object roots and optionally call root-owned mutation/invocation adapters.
Custom Tools	app code	Expose narrow app-specific development operations.

Recommended Defaults

For most teams:

Start with VisualTree and Database.
Use .readOnly by default.
Add FileSystem, Preferences, or SecureStorage only for a specific debugging workflow.
Add Reflection only after registering narrow roots and type/root filters.
Add Artifacts when app-specific output should become a streamed file or durable session artifact.
Add Custom Tools only for narrow operations that packaged suites cannot cover.
Keep write and delete operations off unless the workflow genuinely depends on them.