Tool facts

ToolFact

One tool call flattened for analytics, lifted from a parsed transcript.

Usage

ToolFact(
    ts,
    session_id,
    path,
    cwd,
    tool_use_id,
    tool,
    command_prefixes,
    command,
    mcp_server,
    mcp_tool,
    mcp_access,
    file_path,
    file_paths,
    is_error,
    denied,
    denial_kind,
    user_said,
    duration_ms
)

Attributes

ts: datetime | None: The timestamp of the assistant entry that made the call, or None.
session_id: SessionId: The Claude session the call belongs to.
path: Path: The transcript file the call was lifted from.
cwd: str | None: The working directory recorded on the originating event, or None.
tool_use_id: ToolUseId: The tool-use block id — the join key back to the event stream.
tool: str: The tool name exactly as invoked.
command_prefixes: tuple[str, …]: The permission-style prefixes of each Bash command segment; () for non-Bash calls.
command: str | None: The shell command for a Bash call, else None.
mcp_server: str | None: The MCP server segment for an mcp__server__tool call, else None.
mcp_tool: str | None: The MCP tool segment for an mcp__server__tool call, else None.
mcp_access: Literal["read", "write"] | None: Whether the MCP tool reads or writes, else None.
file_path: str | None: The file the call targets, when it targets one.
file_paths: tuple[str, …]: Every file the call touches, apply_patch multi-file included; file_path mirrors the first entry.
is_error: bool: Whether the call’s result reported a failure.
denied: bool: Whether the result is a user rejection of the tool use.
denial_kind: str | None: The structured tool-denial kind (user-rejected for a human rejection, permission-rule for a hook/guard block), or None.
user_said: str | None: The user’s verbatim instruction embedded in a denial, else None.
duration_ms: int | None: Milliseconds from the call to its result, or None without one.

tool_facts()

Yields one ToolFact per tool call across every transcript file.

Usage

Source

tool_facts(paths, *, max_events)

Each path is parsed and projected by the native core over its first max_events events; a file whose events carry no session identity yields nothing. Every fact re-attaches its source path and rehydrates the native projection — command prefixes, MCP split, denial fields, and duration — into the typed ToolFact. Calls are yielded per file, then in turn order, then call order.

Parameters

paths: Sequence[str | Path]: The transcript files to project, in order.
max_events: int: The per-file cap on parsed events to project.

Yields

ToolFact: A flattened fact per tool use, in file order.

command_prefix_counts()

Counts every Bash command prefix across facts, most frequent first.

Usage

Source

command_prefix_counts(facts)

Flattens each fact’s ToolFact.command_prefixes, so a piped command contributes one count per segment.

Parameters

facts: Iterable[ToolFact]: The tool facts to tally.

Returns

dict[str, int]: Prefix-to-count pairs ordered by descending frequency.

mcp_summary()

Summarizes MCP usage per server across facts.

Usage

Source

mcp_summary(facts)

Groups the facts whose ToolFact.mcp_server is set, tallying read and write access, the total call count, and a per-tool frequency map. Servers are ordered by descending total then name; each tools map is ordered by descending frequency.

Parameters

facts: Iterable[ToolFact]: The tool facts to summarize.

Returns

dict[str, dict[str, int | dict[str, int]]]: A mapping from server to {"read", "write", "total", "tools"}.