Tools

Add native Android remote tool suites, artifact providers, or custom app tools, gate them with ToolGuard, and keep them limited to local development workflows.

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

Important Security Rule

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

Do this:

depend on the all-in-one package or individual tool packages only in local development builds
prefer debugImplementation(...) when an app should not ship tools in release variants
use the narrowest runtime guard that works for the workflow

Do not do this:

ship broad remote tools in distribution builds
expose write or delete tools when read-only inspection is enough
add secure-storage or file-system tools without explicit allow-lists

Runtime Registration

The all-in-one package registers standard native tools through AnsightStandardTools.create():

import ai.ansight.Ansight

Ansight.initializeAndActivate(
    application = application,
    options = Ansight.developerOptions(
        bundledDeveloperConfigJson = BuildConfig.ANSIGHT_DEVELOPER_PAIRING_JSON,
        clientName = "Android App",
    ),
)

Configure individual suites through AnsightOptionsBuilder extensions:

import ai.ansight.runtime.AnsightOptions
import ai.ansight.tools.database.withDatabaseTools
import ai.ansight.tools.filesystem.withFileSystemTools

val options = AnsightOptions.createBuilder()
    .withDatabaseTools()
    .withFileSystemTools {
        addRoot("exports", application.filesDir.resolve("exports"))
    }
    .withReadOnlyToolAccess()
    .build()

Registered tools stay hidden and unusable until the guard allows their scope.

Suite Registration API

Suite	Package	Common registration API
VisualTree	`ansight-tools-visualtree-android`	`withVisualTreeTools()`, `AndroidVisualTreeTools.create()`
Database	`ansight-tools-database-android`	`withDatabaseTools(...)`, `AndroidDatabaseToolsOptions.createBuilder()`, `addRoot(alias, path)`, `includePlatformRoots(...)`
FileSystem	`ansight-tools-filesystem-android`	`withFileSystemTools(...)`, `AndroidFileSystemToolsOptions.createBuilder()`, `addRoot(alias, path)`
Preferences	`ansight-tools-preferences-android`	`withPreferencesTools(...)`, `withDefaultStore(...)`, `allowStore(...)`, `allowKey(...)`, `allowKeyPrefix(...)`
SecureStorage	`ansight-tools-securestorage-android`	`withSecureStorageTools(...)`, `withPreferencesName(...)`, `allowKey(...)`, `allowKeyPrefix(...)`
Reflection	`ansight-tools-reflection-android`	`AndroidReflectionRootRegistry.register(...)`, `registerGetter(...)`, `deregister(...)`, `clear()`, `withReflectionTools(...)`, `allowRoot(...)`, `allowTypePrefix(...)`
Custom Tools	app code	`addTool(...)`, `addTools(...)`, `registerTool(...)`, `isToolRegistered(...)`
Artifacts	`ansight-core-android`	`withArtifactProviders(...)`, `addArtifactProvider(...)`, `addArtifactProviders(...)`, `containsArtifactProvider(...)`

Guard Levels

Guard	What it allows
`withToolsDisabled()` / `AnsightToolGuard.Disabled`	No discovery, no execution.
`withReadOnlyToolAccess()` / `AnsightToolGuard.ReadOnly`	Read-scoped tools only.
`withReadWriteToolAccess()` / `AnsightToolGuard.ReadWrite`	Read and write tools. Delete tools remain blocked.
`withAllToolAccess()` / `AnsightToolGuard.FullAccess`	Read, write, and delete tools.

Tool Suites

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

Suite	Package	Typical use
VisualTree	`ansight-tools-visualtree-android`	Inspect the active Android view hierarchy, capture screenshots, and manage diagnostic overlays.
Database	`ansight-tools-database-android`	Discover SQLite databases, inspect schema, and run read-only queries.
FileSystem	`ansight-tools-filesystem-android`	List directories, read files, download files, push, copy, move, and delete files inside approved roots.
Preferences	`ansight-tools-preferences-android`	Read and mutate SharedPreferences under store/key allow-lists.
SecureStorage	`ansight-tools-securestorage-android`	Read and mutate secure-storage values under explicit key allow-lists.
Reflection	`ansight-tools-reflection-android`	Inspect registered live roots and optionally set values or invoke methods.
Custom Tools	app code	Expose narrow app-specific development operations.

Recommended Defaults

For most teams:

Start with VisualTree and Database.
Use withReadOnlyToolAccess() by default.
Add FileSystem, Preferences, or SecureStorage only for a specific debugging workflow.
Add Reflection only after registering narrow roots and type 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.