DocumentationAgent Action Firewall
GitHub

Tool Discovery

Tool Discovery automatically detects the tools and operations your agents use, infers JSON schemas for their parameters, flags fields containing PII, and helps you promote trusted tools into the Tool Registry for policy authoring — no manual configuration required.

How It Works

  1. Capture: As agents submit actions to POST /v1/actions, AAF records the tool, operation, and parameter shape as discovery samples
  2. Schema inference: The system builds a JSON schema from the observed parameter shapes across samples
  3. PII detection: Samples are scanned for sensitive patterns (emails, phone numbers, credentials, and more)
  4. Review & promote: Discovered tools appear in the dashboard for review; promoting one adds it to the Tool Registry for policy targeting

Live Discovery Feed

Navigate to Tool Discovery in the dashboard sidebar to see the live feed — every action appearing in real-time as agents submit them, including:

  • Tool and operation names as they arrive
  • Parameter samples — click any sample to inspect its full shape
  • PII flags — sensitive fields highlighted before they reach policies

The feed streams over a live connection; new samples appear instantly.

Schema Inference

AAF infers JSON Schema from the parameter shapes seen in live traffic:

  • Types: string, number, integer, boolean, object, array
  • Required fields: present in all observed samples
  • Formats: email, URL, UUID, date patterns
  • Enums: small sets of observed values

For example, after observing samples like:

{"user_id": 123, "action": "create", "email": "a@example.com"}
{"user_id": 456, "action": "update", "email": "b@example.com"}
{"user_id": 789, "action": "create"}

AAF infers a schema resembling:

{
  "type": "object",
  "properties": {
    "user_id": { "type": "integer" },
    "action": { "type": "string", "enum": ["create", "update"] },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["user_id", "action"]
}

Promoting a Tool to the Registry

Once a tool has collected enough samples, promote it to the Tool Registry:

  1. Open the sample or tool in Tool Discovery
  2. Click Add to Registry — AAF runs the learning step (POST /admin/discovery/learn), which finalizes the inferred schema
  3. Review the schema in the Schema Mapper — adjust types, add descriptions, mark fields as sensitive

Registered tools can be:

  • Targeted by policies (input.tool == "stripe")
  • Assigned categories and descriptions
  • Monitored for schema drift

The Tool Registry tab on the same page lists all registered tools with operation counts and policy coverage.

PII Detection

Sampled parameters are scanned for common sensitive patterns:

  • Email addresses
  • Phone numbers
  • Social Security Numbers
  • Credit card numbers (PAN)
  • API keys and tokens
  • Passwords

Flagged fields appear with a warning indicator in the sample inspector. Use DLP policies to block or mask them, or test arbitrary parameters against the detector:

curl -X POST https://api.agentactionfirewall.com/admin/discovery/detect-pii \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{"params": {"email": "a@example.com", "count": 3}}'

API Reference

List Discovery Sessions

GET /admin/discovery/sessions?status=active

Sessions group captured samples for a discovery window (active, paused, completed).

List Samples

GET /admin/discovery/samples?tool=stripe&limit=50

Query parameters: sessionId, tool, operation, limit, offset.

Get Sample Details

GET /admin/discovery/samples/:id

Returns the full parameter payload, inferred schema, and PII detection results.

Learn a Tool (Promote to Registry)

curl -X POST https://api.agentactionfirewall.com/admin/discovery/learn \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{"tool": "stripe", "minSamples": 10, "verifyAutomatically": true}'

List the Tool Registry

GET /admin/tools

Best Practices

Tip: Review discovered tools weekly. New tools appearing in the feed may indicate agents using capabilities you haven't written policies for yet.

Tip: Promote expected tools quickly. Registered tools get schema validation and policy coverage; unregistered ones are still governed by your default decision.

Tip: Onboard new agents in test mode first. Run the agent, watch the feed, promote the expected tools, and write policies before enabling production traffic.

Next Steps