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

# Tool Categories

> Automatic risk classification for every tool call

## 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).

| Category | Matches | Risk Signal |
| - | - | - |
| `code_execution` | `exec`, `run_code`, `python`, `bash`, `shell`, `eval`, `compile` | **High** — arbitrary code execution |
| `email` | `send_email`, `send_mail`, `email`, `smtp` | **High** — data exfiltration vector |
| `external_api` | `http`, `fetch`, `request`, `curl`, `scrape`, `browse`, `web` | **Medium** — network access |
| `file_system` | `write_file`, `save_file`, `create_file`, `delete_file`, `rm `, `mv` | **Medium** — filesystem mutation |
| `memory_write` | `vector`, `embed`, `upsert`, `add_document`, `index` | **Medium** — memory poisoning vector |
| `memory_read` | `search`, `query`, `retrieve`, `recall`, `lookup` | **Low** — information access |
| `human_interaction` | `human`, `approval`, `confirm`, `ask_user`, `hitl` | **Low** — 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:

```python theme={"dark"}
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`.

> [!NOTE]
>
> 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`.

## Related Inference: Tool Direction

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.