liveBook · Manning

Tool decorator

As explained in Digital Twins in Action

A decorator that marks a Python function as a callable tool for an AI agent.

A tool decorator marks a Python function as callable by an AI agent. In the Strands SDK, @tool lets an agent use a function to retrieve external data as part of a reasoning-and-action loop. section 8.4.3

Document when to use the function, its inputs, and the structure of its return data. This documentation tells the agent how to use the tool. section 8.4.3

Listing 8.10 Tool to query Fronius Symo inverter power data
from strands import tool

@tool  #1
def get_realtime_solar_data(scope: str = "System") -> Dict[str, Any]:
    """  #2
    Fetches real-time solar production metrics from the local Fronius
    inverter.

    Use this tool when you need to know the current solar output (PAC) or
    the total energy produced today (DAY_ENERGY).

    Args:
        scope: The data scope to query. Defaults to "System".

    Returns:
        Dict[str, Any]: A dictionary containing:
            - current_power_w: Current AC power output in Watts.
            - day_energy_wh: Total energy produced today in Watt-hours.
            - timestamp: The time of the reading.
    """
    url = "http://192.168.1.180/solar_api/v1/GetInverterRealtimeData.cgi"  #3

    try:
        response = requests.get(url, params={"Scope": scope}, timeout=5)
        response.raise_for_status()
        data = response.json()

        realtime_data = data.get("Body", {}).get("Data", {})

        pac_value = realtime_data.get("PAC", {}).get("Values", {}).
        get("1", 0)
        day_energy = realtime_data.get("DAY_ENERGY", {}).get("Values",
        {}).get("1", 0)

        return {
            "current_power_w": pac_value,
            "day_energy_wh": day_energy,
            "timestamp": data.get("Head", {}).get("Timestamp"),
            "status": "success",
        }

    except requests.RequestException as e:
        return {
            "status": "error",
            "message": f"Failed to connect to inverter: {str(e)}",
        }

The decorated function queries a local solar inverter for current power and daily energy production. Its docstring describes the scope argument and returned fields. section 8.4.3

How Digital Twins in Action covers it

How deep it goes
Shows a decorated function and its documentation, without explaining the decorator’s internals.
Examples
Uses a local Fronius inverter query that returns current power and daily energy production.
What you can do after
Apply it via the Strands SDK to make a documented Python function available as an agent tool.
How it connects
Connects AI agents, API calls, tool execution, and agent loops.

Also explained in

Compare how 2 books explain tool decorator →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Digital Twins in Action. The section links point to the parts of the book it draws on.