trading_agent.terminal.tool_describer ¶

Describes tool calls in plain words: what one is doing now, and a summary of several once done.

It is a port of the web page's toolDescriber.ts, so the terminal and the browser use the same words.

Typical usage example:

describer = ToolDescriber() describer.activity('get_quote') # 'Fetching a quote' describer.summary([('get_quote', False), ('bash_run', True)])

ToolDescriber ¶

Words for tool calls, keyed by tool name.

activity ¶

activity(tool_name)

What a running tool is doing.

Parameters:

Name	Type	Description	Default
`tool_name`	`str`	The tool's name, with or without Claude Code's MCP prefix.	required

Returns:

Type	Description
`str`	Such as "Fetching a quote", or "Using " for a tool without its own words.

Source code in src/trading_agent/terminal/tool_describer.py

def activity(self, tool_name: str) -> str:
    """What a running tool is doing.

    Args:
        tool_name (str): The tool's name, with or without Claude Code's MCP prefix.

    Returns:
        str: Such as "Fetching a quote", or "Using <name>" for a tool without its own words.
    """
    known = _TOOLS.get(self.base_name(tool_name))
    if known is None:
        return f'Using {tool_name}'
    return known[0]

detail ¶

detail(arguments_text)

The most telling argument of a tool call, shortened.

Parameters:

Name	Type	Description	Default
`arguments_text`	`str`	The call's arguments as JSON text.	required

Returns:

Type	Description
`str`	Such as "RELIANCE" or "ls -la", or an empty string when there is none.

Source code in src/trading_agent/terminal/tool_describer.py

def detail(self, arguments_text: str) -> str:
    """The most telling argument of a tool call, shortened.

    Args:
        arguments_text (str): The call's arguments as JSON text.

    Returns:
        str: Such as "RELIANCE" or "ls -la", or an empty string when there is none.
    """
    try:
        values = json.loads(arguments_text)
    except ValueError:
        return ''
    if not isinstance(values, dict):
        return ''
    for key in _DETAIL_KEYS:
        value = values.get(key)
        if isinstance(value, str) and value.strip():
            line = value.strip().split('\n')[0]
            if len(line) > _DETAIL_LENGTH:
                return line[: _DETAIL_LENGTH - 1] + '…'
            return line
    return ''

summary ¶

summary(calls)

One line summing up several tool calls, as Claude Code does.

Parameters:

Name	Type	Description	Default
`calls`	`Sequence[tuple[str, bool]]`	Each call's tool name and whether it failed, in order.	required

Returns:

Type	Description
`str`	Such as "Fetched 2 quotes, ran a command (1 failed)".

Source code in src/trading_agent/terminal/tool_describer.py

def summary(self, calls: Sequence[tuple[str, bool]]) -> str:
    """One line summing up several tool calls, as Claude Code does.

    Args:
        calls (Sequence[tuple[str, bool]]): Each call's tool name and whether it failed, in order.

    Returns:
        str: Such as "Fetched 2 quotes, ran a command (1 failed)".
    """
    order = []
    counts = {}
    failures = {}
    for tool_name, failed in calls:
        kind = 'tool'
        known = _TOOLS.get(self.base_name(tool_name))
        if known is not None:
            kind = known[1]
        if kind not in counts:
            order.append(kind)
            counts[kind] = 0
            failures[kind] = 0
        counts[kind] += 1
        if failed:
            failures[kind] += 1
    parts = []
    for kind in order:
        one, many = _KINDS[kind]
        part = one
        if counts[kind] > 1:
            part = many.replace('{count}', str(counts[kind]))
        if failures[kind] > 0:
            part = f'{part} ({failures[kind]} failed)'
        parts.append(part)
    sentence = ', '.join(parts)
    return sentence[:1].upper() + sentence[1:]

base_name ¶

base_name(tool_name)

A tool's own name without the prefix Claude Code adds to tools served over MCP.

Parameters:

Name	Type	Description	Default
`tool_name`	`str`	The name as the event gives it.	required

Returns:

Type	Description
`str`	Such as "get_quote" for "mcp__trading_agent__get_quote".

Source code in src/trading_agent/terminal/tool_describer.py

def base_name(self, tool_name: str) -> str:
    """A tool's own name without the prefix Claude Code adds to tools served over MCP.

    Args:
        tool_name (str): The name as the event gives it.

    Returns:
        str: Such as "get_quote" for "mcp__trading_agent__get_quote".
    """
    return tool_name.split('__')[-1]