tools

Attribute FORMAT_TOOL_NAME

Type: '__mirascope_formatted_output_tool__'

Reserved name of the formatted output tool.

Any call to a tool with this name is NOT considered a regular tool call, but will instead be converted into textual output containing the arguments to the tool call.

Class AsyncContextTool

Protocol defining an async tool that can be used by LLMs with context.

An AsyncContextTool represents an async function that can be called by an LLM during a call. It includes metadata like name, description, and parameter schema.

This class is not instantiated directly but created by the @tool() decorator.

Bases: ToolSchema[AsyncContextToolFn[DepsT, AnyP, JsonableCovariantT]], Generic[DepsT, JsonableCovariantT, AnyP]

Function execute

Execute the async context tool using an LLM-provided ToolCall.

Class AsyncContextToolkit

A collection of AsyncContextTools, with helpers for getting and executing specific tools.

Bases: BaseToolkit[AsyncTool | AsyncContextTool[DepsT]], Generic[DepsT]

Function execute

Execute an AsyncContextTool using the provided tool call.

Class AsyncTool

An async tool that can be used by LLMs.

An AsyncTool represents an async function that can be called by an LLM during a call. It includes metadata like name, description, and parameter schema.

This class is not instantiated directly but created by the @tool() decorator.

Bases: ToolSchema[AsyncToolFn[AnyP, JsonableCovariantT]], Generic[AnyP, JsonableCovariantT]

Function execute

Execute the async tool using an LLM-provided ToolCall.

Class AsyncToolkit

A collection of AsyncTools, with helpers for getting and executing specific tools.

Bases:

Function execute

Execute an AsyncTool using the provided tool call.

Class BaseToolkit

Base class for tool collections.

Provides common functionality for managing collections of tools, including name validation and tool lookup.

Bases:

Function get

Get a tool that can execute a specific tool call.

Class ContextTool

Protocol defining a tool that can be used by LLMs.

A ContextTool represents a function that can be called by an LLM during a call. It includes metadata like name, description, and parameter schema.

This class is not instantiated directly but created by the @tool() decorator.

Bases: ToolSchema[ContextToolFn[DepsT, AnyP, JsonableCovariantT]], Generic[DepsT, JsonableCovariantT, AnyP]

Function execute

Execute the context tool using an LLM-provided ToolCall.

Class ContextToolkit

A collection of ContextTools, with helpers for getting and executing specific tools.

Bases: BaseToolkit[Tool | ContextTool[DepsT]], Generic[DepsT]

Function execute

Execute a ContextTool using the provided tool call.

Class Tool

A tool that can be used by LLMs.

A Tool represents a function that can be called by an LLM during a call. It includes metadata like name, description, and parameter schema.

This class is not instantiated directly but created by the @tool() decorator.

Bases: ToolSchema[ToolFn[AnyP, JsonableCovariantT]], Generic[AnyP, JsonableCovariantT]

Function execute

Execute the tool using an LLM-provided ToolCall.

Class ToolDecorator

Protocol for the tool decorator.

Class ToolParameterSchema

JSON Schema for tool parameters (always an object with properties).

This contains real JSON Schema as generated by Pydantic, with full support for complex schemas like anyOf, nested objects, validation constraints, etc. Including $defs for complex type references.

Bases:

Class ToolSchema

Underlying schema defining a tool that can be used by LLMs.

A ToolSchema represents a function that can be called by an LLM during a call. It includes metadata like name, description, and parameter schema.

This class is not instantiated directly but created by the @tool() decorator.

Bases:

Function can_execute

Check if a ToolCall can be executed by tools with this ToolSchema.

This method is a convenient way to determine if a ToolCall is likely intended to be executed by a tool with this ToolSchema. It does so by checking whether the name on the call matches the name on the schema. No other validation is performed.

Attribute ToolSchemaT

Type: TypeVar('ToolSchemaT', bound='ToolSchema')

Attribute ToolT

Type: TypeVar('ToolT', bound='Tool | AsyncTool | ContextTool[Any] | AsyncContextTool[Any]', covariant=True)

Class Toolkit

A collection of Tools, with helpers for getting and executing specific tools.

Bases:

Function execute

Execute a Tool using the provided tool call.

Attribute ToolkitT

Type: TypeVar('ToolkitT', bound='Toolkit | AsyncToolkit | ContextToolkit[Any] | AsyncContextToolkit[Any]', covariant=True)

Module protocols

Function tool

Decorator that turns a function into a tool definition.

This decorator creates a Tool or ContextTool that can be used with llm.call. The function's name, docstring, and type hints are used to generate the tool's metadata.

If the first parameter is named 'ctx' or typed as llm.Context[T], it creates a ContextTool. Otherwise, it creates a regular Tool.

Examples:

Regular tool:

from mirascope import llm

@llm.tool
def available_books() -> list[str]:
    """Returns the list of available books."""
    return ["The Name of the Wind"]

Context tool:

from dataclasses import dataclass

from mirascope import llm


@dataclass
class Library:
    books: list[str]


library = Library(books=["Mistborn", "Gödel, Escher, Bach", "Dune"])

@llm.tool
def available_books(ctx: llm.Context[Library]) -> list[str]:
    """Returns the list of available books."""
    return ctx.deps.books