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 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

SuitePackageCommon registration API
VisualTreeansight-tools-visualtree-androidwithVisualTreeTools(), AndroidVisualTreeTools.create()
Databaseansight-tools-database-androidwithDatabaseTools(...), AndroidDatabaseToolsOptions.createBuilder(), addRoot(alias, path), includePlatformRoots(...)
FileSystemansight-tools-filesystem-androidwithFileSystemTools(...), AndroidFileSystemToolsOptions.createBuilder(), addRoot(alias, path)
File Descriptor Diagnosticsansight-tools-filedescriptordiagnostics-androidwithFileDescriptorDiagnosticsTools(...), AndroidFileDescriptorDiagnosticsOptions.createBuilder(), includeTargets(...), maximumReturnedDescriptors(...)
JNI Reference Diagnosticsansight-tools-jnireferencediagnostics-androidwithJniReferenceDiagnosticsTools(...), maximumGraphNodes(...), maximumGraphEdges(...), maximumGraphDepth(...)
Preferencesansight-tools-preferences-androidwithPreferencesTools(...), withDefaultStore(...), allowStore(...), allowKey(...), allowKeyPrefix(...)
SecureStorageansight-tools-securestorage-androidwithSecureStorageTools(...), withPreferencesName(...), allowKey(...), allowKeyPrefix(...)
Reflectionansight-tools-reflection-androidAndroidReflectionRootRegistry.register(...), registerGetter(...), deregister(...), clear(), withReflectionTools(...), allowRoot(...), allowTypePrefix(...)
Custom Toolsapp codeaddTool(...), addTools(...), registerTool(...), isToolRegistered(...)
Artifactsansight-core-androidwithArtifactProviders(...), addArtifactProvider(...), addArtifactProviders(...), containsArtifactProvider(...)

Guard Levels

GuardWhat it allows
withToolsDisabled() / AnsightToolGuard.DisabledNo discovery, no execution.
withReadOnlyToolAccess() / AnsightToolGuard.ReadOnlyMaximum policy Read.
withReadWriteToolAccess() / AnsightToolGuard.ReadWriteMaximum policy Write.
withAllToolAccess() / AnsightToolGuard.FullAccessMaximum 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.

SuitePackageTypical use
VisualTreeansight-tools-visualtree-androidInspect the active Android view hierarchy, capture screenshots, and manage diagnostic overlays.
Databaseansight-tools-database-androidDiscover SQLite databases, inspect schema, and run read-only queries.
FileSystemansight-tools-filesystem-androidList directories, read files, download files, push, copy, move, and delete files inside approved roots.
File Descriptor Diagnosticsansight-tools-filedescriptordiagnostics-androidCount and inspect open process descriptors, limits, and utilization.
JNI Reference Diagnosticsansight-tools-jnireferencediagnostics-androidCapture a bounded, redacted Android heap graph rooted at JNI references.
Preferencesansight-tools-preferences-androidRead and mutate SharedPreferences under store/key allow-lists.
SecureStorageansight-tools-securestorage-androidRead and mutate secure-storage values under explicit key allow-lists.
Reflectionansight-tools-reflection-androidInspect registered live roots and optionally set values or invoke methods.
Custom Toolsapp codeExpose narrow app-specific development operations.

For most teams:

  1. Start with VisualTree and Database.
  2. Use withReadOnlyToolAccess() by default.
  3. Use File Descriptor Diagnostics for resource-leak investigations, with targets disabled unless paths are needed.
  4. Sample JNI reference count before using JNI Reference Diagnostics; HPROF capture should be an explicit investigation step.
  5. Add FileSystem, Preferences, or SecureStorage only for a specific debugging workflow.
  6. Add Reflection only after registering narrow roots and type filters.
  7. Add Artifacts when app-specific output should become a streamed file or durable session artifact.
  8. Add Custom Tools only for narrow operations that packaged suites cannot cover.
  9. Keep write and delete operations off unless the workflow genuinely depends on them.