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

