Tool Decorator

Calling a decorated function will create a Tool Log with the following fields:

• inputs: The function arguments.
• output: The function return value.
• error: The error message if the function call fails.

1
@hl_client.tool(
2
    # Required: path on Humanloop workspace for the Tool
3
    path: str,
4
    # Optional: additional metadata for the Tool
5
    attributes: Optional[dict[str, Any]] = None,
6
    # Optional: values needed to setup the Tool
7
    setup_values: Optional[dict[str, Any]] = None
8
)
9
def function(*args, **kwargs): ...

The decorated function will have the same signature as the original function and will have a json_schema attribute containing the inferred JSON Schema.

1
@hl_client.tool(path="MyFeature/Calculator")
2
def calculator(a: int, b: Optional[int] = None) -> int:
3
    """Add two numbers together."""
4
    return a + (b or 0)

Decorating a function will set a json_schema attribute that can be used for function calling.

1
# Use with prompts.call
2
response = hl_client.prompts.call(
3
    path="MyFeature/Assistant",
4
    messages=[{"role": "user", "content": "What is 5 + 3?"}],
5
    tools=[calculator.json_schema]
6
)
7
8
# Or with OpenAI directly!
9
response = openai.chat.completions.create(
10
    model="gpt-4o-mini",
11
    messages=[{"role": "user", "content": "What is 5 + 3?"}],
12
    tools=[{
13
        "type": "function",
14
        "function": calculator.json_schema
15
    }]
16
)

In Python, the decorator automatically infers a JSON Schema from the source code, argument signature, and docstrings:

• Function name becomes the tool name
• Function docstring becomes the tool description
• Parameter type hints are converted to JSON Schema types
• Optional parameters (using Optional[T] or T | None) are marked as not required
• Return type is not included in the schema

Supported type hints:

• Function errors are caught and logged in the Log’s error field.
• The decorated function returns None when an error occurs.
• HumanloopRuntimeError is not caught and will be re-raised, as it indicates incorrect SDK or decorator usage.

1. Use clear and descriptive docstrings in Python to provide good tool descriptions
2. Ensure all function parameters have appropriate type hints in Python
3. Make return values JSON-serializable
4. Use the json_schema attribute when passing the tool to prompts.call()