Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tracectrl.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Every tool call captured by TraceCtrl is automatically classified into a risk category based on its name and description. This classification is stored in the tracectrl.tool.category span attribute. The classification happens in the TraceCtrlSpanProcessor — no configuration required beyond installing the processor on your TracerProvider.

​
Risk Categories

There are 8 categories. Rules are evaluated in priority order — the first match wins. Both the tool name and description are checked (case-insensitive).
CategoryMatchesRisk Signal
code_executionexec, run_code, python, bash, shell, eval, compileHigh — arbitrary code execution
emailsend_email, send_mail, email, smtpHigh — data exfiltration vector
external_apihttp, fetch, request, curl, scrape, browse, webMedium — network access
file_systemwrite_file, save_file, create_file, delete_file, rm , mvMedium — filesystem mutation
memory_writevector, embed, upsert, add_document, indexMedium — memory poisoning vector
memory_readsearch, query, retrieve, recall, lookupLow — information access
human_interactionhuman, approval, confirm, ask_user, hitlLow — human-in-the-loop safety
internal_api(default fallback)Low — internal function call

​
How It Works

The infer_tool_category() function matches against the tool’s name and description using keyword rules. The first matching rule wins: 
from tracectrl.inference import infer_tool_category

infer_tool_category("run_python_code")       # → "code_execution"
infer_tool_category("send_email_to_user")    # → "email"
infer_tool_category("fetch_weather_data")    # → "external_api"
infer_tool_category("write_file")            # → "file_system"
infer_tool_category("upsert_to_pinecone")    # → "memory_write"
infer_tool_category("search_documents")      # → "memory_read"
infer_tool_category("ask_user_for_approval") # → "human_interaction"
infer_tool_category("calculate_tax")         # → "internal_api"
Signature: infer_tool_category(tool_name: str, tool_description: str = "") -> str.

​
Matching Logic

Rules are evaluated in priority order — the first match wins. Both the tool name and description are checked (case-insensitive). The rules are defined in tracectrl.inference.TOOL_CATEGORY_RULES.
The description field is important for accurate classification. A tool named process_data would be classified as internal_api, but if its description contains “fetches data from external HTTP endpoint”, it would match external_api.
Alongside the category, the processor also stamps tracectrl.tool.direction via infer_tool_direction() — one of input, output, or internal. This describes whether the tool brings data into the system (e.g., receive, fetch, webhook_handler), pushes data out (e.g., send, post, publish), or operates internally.

​
Why This Matters

Tool category classification enables:
  • Risk scoring — agents with access to code_execution or email tools are inherently higher risk
  • Attack path analysis — TAGAAI identifies exploitation chains through high-risk tool categories
  • Topology visualization — the dashboard shows tool nodes colored by risk level
  • Alerting — trigger alerts when unexpected tool categories appear in agent behavior