Tools¶
Define tools that the LLM can call during execution.
Authoring¶
The @arcana.tool decorator and the Tool adapter cover most cases.
tool(*, name: str | None = None, description: str | None = None, when_to_use: str | None = None, what_to_expect: str | None = None, failure_meaning: str | None = None, side_effect: str = 'read', requires_confirmation: bool = False) -> Callable
Decorator to register a function as an Arcana tool.
Usage
@arcana.tool(when_to_use="When you need current information") async def search(query: str) -> str: return await do_search(query)
Non-decorator tool registration.
Use this when you want to register tools without importing arcana at module level, or when the tool function is defined elsewhere.
Example::
from arcana import Tool
def my_search(query: str) -> str:
"""Search the web."""
return requests.get(f"https://api.example.com/search?q={query}").text
search_tool = Tool(fn=my_search, when_to_use="Search the web for information")
runtime = Runtime(tools=[search_tool])
Contracts¶
The Pydantic models that flow through the Tool Gateway. These are stable as data contracts (see stability spec ยง1.4).
Bases: BaseModel
Specification of a tool.
Bases: BaseModel
A tool call to be executed.
Bases: BaseModel
Result of tool execution.
Bases: BaseModel
Error from tool execution.
The category field is the single source of truth for retry policy;
is_retryable is derived. Tool authors classify; the runtime decides.
Enums¶
Bases: str, Enum
Classification of tool errors driving retry policy.
Categories in _RETRY_ELIGIBLE (TRANSPORT, TIMEOUT, RATE_LIMIT) trigger
the ToolGateway's exponential backoff loop. All others are surfaced
immediately so the LLM can react with a different strategy. This is
the engineering form of CONSTITUTION's fourth prohibition,
No Mechanical Retry: the runtime retries only failures that are
structurally transient.
Bases: str, Enum
Type of side effect a tool may have.
Constants¶
ASK_USER_TOOL_NAME is the reserved name for the built-in
ask-user clarification tool.