Give agents access to your app's live state

Let agents investigate UI, stored data, and app-specific state in your Android app with tools scoped to development.

Use remote tools to answer questions about what the app is showing, what it has stored, and which app-specific state is driving its behavior. Enable only the inspection or development actions your workflow needs.

Remote tools let the local host player and CLI 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 critical 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(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 policy.

Runtime Availability

tool.query evaluates each visible tool against current app state. Catalog entries include runtime.available, reasonCode, reason, requiredState, remediation, retryable, and evaluatedAtUtc, plus a top-level executable flag. Availability is evaluated again immediately before tool.call; an unavailable call returns a structured tool_unavailable-style error instead of running the handler. Tools without prerequisites return ToolAvailability.Available.

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)`
File Descriptor Diagnostics	`ansight-tools-filedescriptordiagnostics-android`	`withFileDescriptorDiagnosticsTools(...)`, `AndroidFileDescriptorDiagnosticsOptions.createBuilder()`, `includeTargets(...)`, `maximumReturnedDescriptors(...)`
JNI Reference Diagnostics	`ansight-tools-jnireferencediagnostics-android`	`withJniReferenceDiagnosticsTools(...)`, `maximumGraphNodes(...)`, `maximumGraphEdges(...)`, `maximumGraphDepth(...)`
Preferences	`ansight-tools-preferences-android`	`withPreferencesTools(...)`, `withDefaultStore(...)`, `allowStore(...)`, `allowKey(...)`, `allowKeyPrefix(...)`
Clipboard	`ansight-tools-clipboard-android`	`withClipboardTools()`; included by `ansight-android`
Purchases	`ansight-core-android`; optional `ansight-purchases-googleplay-android`	`withPurchaseTools()`, `GooglePlayPurchaseObserver`
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`	Maximum policy `Read`.
`withReadWriteToolAccess()` / `AnsightToolGuard.ReadWrite`	Maximum policy `Write`.
`withAllToolAccess()` / `AnsightToolGuard.FullAccess`	Maximum policy `Critical`.

Tool Suites

Artifacts are a core provider model rather than a separate tool package. Registering artifact providers adds the Read policy 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.
File Descriptor Diagnostics	`ansight-tools-filedescriptordiagnostics-android`	Count and inspect open process descriptors, limits, and utilization.
JNI Reference Diagnostics	`ansight-tools-jnireferencediagnostics-android`	Capture a bounded, redacted Android heap graph rooted at JNI references.
Preferences	`ansight-tools-preferences-android`	Read and mutate SharedPreferences under store/key allow-lists.
Clipboard	`ansight-tools-clipboard-android`	Read, check, set, and clear the focused app’s device clipboard.
Purchases	`ansight-core-android`; optional `ansight-purchases-googleplay-android`	Record and validate Google Play evidence on recognized emulators.
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.
Use File Descriptor Diagnostics for resource-leak investigations, with targets disabled unless paths are needed.
Sample JNI reference count before using JNI Reference Diagnostics; HPROF capture should be an explicit investigation step.
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.