Tools¶

alloy.tool ¶

tool ¶

tool(fn=None)

Decorator to mark a Python function as an Alloy tool.

The decorated callable still runs locally in Python, but carries metadata and contracts to teach the AI how to use it.

Usage¶

from alloy import command, tool

@tool
def word_count(text: str) -> int:
    return len(text.split())

@command(tools=[word_count])
def analyze(text: str) -> str:
    return f"Use word_count(text), then suggest one clarity improvement.\\nText: {text}"

print(analyze("Alloy makes typed AI functions feel like normal Python."))

Contracts (Design by Contract)

from alloy import tool, require, ensure

@tool
@require(lambda ba: ba.arguments.get("x", 0) >= 0, "x must be non-negative")
@ensure(lambda r: r >= 0, "result must be non-negative")
def sqrt_floor(x: int) -> int:
    import math
    return int(math.sqrt(x))

Optional parameters¶

Tool parameters with default values are optional. Only parameters without defaults are included in the JSON Schema required list.
Nested dataclasses in tool parameters also respect defaults (their fields with defaults are not required).
Applies across OpenAI, Anthropic, and Gemini; unknown top‑level keys are rejected (additionalProperties: false).