Set tool annotations by decorating the tool function, not in `chat.register_tool()`

[gadenbuie]

Tool annotations should be attached to the tool definition as closely as possible. It's currently awkward to create to a tool function that has annotations because those annotations need to be passed to chat.register_tool() at registration, which might be in a different place than where the tool is defined. (The tool could be in packaged code and the registration in user code.)

Instead of this

import faicons
from chatlas import ChatOpenAI


def get_weather_forecast(
    lat: float, lon: float, location_name: str
) -> ContentToolResult:
    """Get the weather forecast for a location."""
    # Mocked weather data for demonstration purposes
    return {"temperature_2m": 18, "condition": "Partly Cloudy"}


# Create chat client and register tool
chat_client = ChatOpenAI(model="gpt-4.1-nano")
chat_client.register_tool(
    get_weather_forecast,
    annotations={  # << THIS COULD HAPPEN FAR FROM TOOL DEL
        "title": "Weather Forecast",
        "icon": faicons.icon_svg("cloud"),
    },
)

Maybe this

import faicons
from chatlas import ChatOpenAI, add_tool_annotations

@add_tool_annotations(
  title="Weather Forecast",
  icon=faicons.icon_svg("cloud")
)
def get_weather_forecast(
    lat: float, lon: float, location_name: str
) -> ContentToolResult:
    """Get the weather forecast for a location."""
    # Mocked weather data for demonstration purposes
    return {"temperature_2m": 18, "condition": "Partly Cloudy"}


# Create chat client and register tool
chat_client = ChatOpenAI(model="gpt-4.1-nano")
chat_client.register_tool(get_weather_forecast)

Advantages

This would also resolve some of the underlying issue in #169 where known standard MCP Tool Annotation properties could be named arguments that are documented, but additional kwargs are just added as tool annotations.

[gadenbuie]

I'm very convinced this is a Good Idea (unless there are technical challenges); I'm very unattached to the decorator name 😉

[gadenbuie]

Here's a basic sketch of the idea

from typing import Any, Callable, Protocol, TypeVar

from chatlas.types import ToolAnnotations


class ToolAnnotated(Protocol):
    tool_annotations: ToolAnnotations

    def __call__(self, *args: Any, **kwargs: Any) -> Any: ...


def add_tool_annotations(
    title: str | None = None,
    **kwargs: Any,
) -> Callable[[Callable[..., Any]], ToolAnnotated]:
    def decorator(func: Callable[..., Any]) -> ToolAnnotated:
        func.tool_annotations = {title: title, **kwargs}  # type: ignore
        return func  # type: ignore

    return decorator

so then for the tool def

@add_tool_annotations(
  title="Weather Forecast",
  icon=faicons.icon_svg("cloud")
)
def get_weather_forecast(
    lat: float, lon: float, location_name: str
) -> ContentToolResult:
    """Get the weather forecast for a location."""
    # Mocked weather data for demonstration purposes
    return {"temperature_2m": 18, "condition": "Partly Cloudy"}

and then to register/use the tool

chat_client = ChatOpenAI(model="gpt-4.1-nano")
chat_client.register_tool(get_weather_forecast, get_weather_forecast.tool_annotations)

# or even better, register tool can look for the annotations automatically
chat_client.register_tool(get_weather_forecast)

[cpsievert]

A annotation specific decorator doesn't seem right since the same problem exists for any additional configuration that wants to be bound to the tool (e.g., model, etc).

Seems like Tool.from_func() solves the majority of this problem (i.e., it can be used to create a tool with annotations, etc., that can be later registered downstream)?

[gadenbuie]

hmm. Tool.from_func() does do most of what I'd need. I think it's worth considering turning that into a decorator because it's not hard and is nicely ergonomic. Also using a helper function to type annotations is nice. But maybe you could solve it like this:

@tool_set_annotations(
  title="Weather Forecast",
  icon=faicons.icon_svg("cloud")
)
@tool
def get_weather_forecast(
    lat: float, lon: float, location_name: str
) -> ContentToolResult:
    """Get the weather forecast for a location."""
    # Mocked weather data for demonstration purposes
    return {"temperature_2m": 18, "condition": "Partly Cloudy"}

with similar functions for name and model. Or just

@tool(
    annotations={"title": "Weather Forecast"}
)
def get_weather_forecast(
    lat: float, lon: float, location_name: str
) -> ContentToolResult:
    """Get the weather forecast for a location."""
    # Mocked weather data for demonstration purposes
    return {"temperature_2m": 18, "condition": "Partly Cloudy"}

---

On the other hand, this raises another issue that chat.register_tool() doesn't accept Tools (#171)