Tools Reference

ToolBank

The unified container for callable tools and their JSON-schema specifications.

@dataclass(slots=True)
class ToolBank:
    functions: dict[str, Callable[..., Any]]
    schema: list[ToolSchema]

    async def execute(
        self,
        name: str,
        parameters: dict[str, Any] | None = None,
        context: dict[str, Any] | None = None,
    ) -> Any: ...

Class methods

ToolBank.from_module(module_path)

Load tools from a Python module. Functions are discovered via inspect.getmembers. Docstrings are parsed with numpydoc to generate JSON schemas.

bank = ToolBank.from_module("my_tools.search")

Requires the [tools] extra: pip install alquimia-core[tools].

ToolBank.from_mcp(config)

Load tools from an MCP server.

bank = await ToolBank.from_mcp({
    "url": "http://my-mcp-server:8000",
    "auth": "Bearer my-token",
})

ToolBank.from_llama_stack(config)

Load tools from a Llama Stack instance.

bank = await ToolBank.from_llama_stack({
    "tool_group_id": "my-tools",
})

execute(name, parameters, context)

Execute a tool by name.

result = await bank.execute(
    "search_web",
    parameters={"query": "capital of France"},
    context={"user_id": "user-1"},
)

Raises ToolsUnknownName if the tool is not in the bank.

---

ToolConfig (discriminated union)

ToolConfig is a discriminated union on provider_id:

ToolConfig = Annotated[
    MCPToolConfig | LlamaStackToolConfig | A2AConfig,
    Field(discriminator="provider_id"),
]

---

MCPToolConfig

class MCPToolConfig(BaseToolConfig):
    provider_id: Literal["mcp"] = "mcp"
    url: str | SecretRef | None = None
    auth: str | SecretRef | None = None
    args: list[SecretStr] | None = None
    env: dict[str, SecretStr] | None = None
    headers: dict[str, SecretStr] | None = None
    command: str | None = None
    transport: str | None = None

Field	Type	Description
provider_id	"mcp"	Required
url	string | SecretRef	MCP server URL (HTTP transport)
auth	string | SecretRef	Bearer token or auth method
command	string	Command to launch (stdio transport)
args	string[]	Arguments for the command
env	dict[str, string]	Environment variables
headers	dict[str, string]	Additional HTTP headers
transport	string	Transport type
human_approval	"NONE" | "LAZY" | "REQUIRED"	Approval requirement

---

LlamaStackToolConfig

class LlamaStackToolConfig(BaseToolConfig):
    provider_id: Literal["llama-stack"] = "llama-stack"
    tool_group_id: str | None = None
    authorization: str | SecretRef | None = None
    extra_headers: dict[str, SecretStr] | None = None

Field	Type	Description
provider_id	"llama-stack"	Required
tool_group_id	string	Filter tools by group
authorization	string | SecretRef	Provider authorization header
extra_headers	dict[str, string]	Additional headers

Environment variables used by Llama Stack:

Variable	Description
LLAMA_STACK_BASE_URL	Llama Stack server URL
LLAMA_STACK_API_KEY	API key
LLAMA_STACK_TIMEOUT	Request timeout
LLAMA_STACK_MAX_RETRIES	Max retries (default: 3)

---

A2AConfig

class A2AConfig(BaseToolConfig):
    provider_id: Literal["a2a"] = "a2a"
    context: dict[str, Any] | None = None
    selector: dict[str, Any]

Field	Type	Description
provider_id	"a2a"	Required
selector	dict	TinyDB-style filter to find agents
context	dict	Extra context passed to discovered agents

A2ASchema

Represents an agent exposed as a tool:

class A2ASchema(BaseModel):
    assistant_id: str
    nickname: str
    description: str

    @property
    def as_toolname(self) -> str: ...  # "agent_{nickname}"
    def to_spec(self) -> ToolSchema: ...

A2AQueryInput

The input schema for A2A tool calls:

Field	Type	Description
query	string	The full task to send to the other agent
hands_off	bool	If true, the other agent responds directly to the user

---

ToolSchema

The JSON schema representation of a tool:

class ToolSchema(BaseModel):
    name: str                              # serialized as "title"
    description: str | None = ""
    type: str | None = None
    properties: dict[str, Any] | None = None
    required: list[str] | None = None
    parameters: dict[str, Any] | None = None

---

Elicitation handler

When an MCP tool requires fields that are not in the call parameters, the elicitation handler automatically fills them from runtime_context:

async def elicitation_handler(
    runtime_context: dict[str, Any],
    message: str,
    response_type: type,
    params: Any,
    context: dict[str, Any],
) -> ElicitResult | dict[str, Any]: ...

If a required field cannot be found in runtime_context, the handler returns ElicitResult(action="cancel") to abort the tool call.

---

Environment variables

Variable	Default	Description
TOOLS_BANK_BASE_MODULE	"tools"	Python module path for built-in tools
ALQUIMIA_A2A_TOOLNAME_PREFIX	"agent-"	Prefix for A2A tool names
LLAMA_STACK_BASE_URL	—	Llama Stack server URL
LLAMA_STACK_API_KEY	—	Llama Stack API key
LLAMA_STACK_TIMEOUT	—	Request timeout
LLAMA_STACK_MAX_RETRIES	3	Max retries

Related pages

• Tools & Integrations — conceptual overview
• Evaluation Strategies — how tools are bound to the LLM