Chapter 2: Working with Tools
This introduction explains how tools expand LLM agents’ capabilities and outlines the basic tool-calling process.
After this chapter you will be able to
- Tools Expand Agent Capabilities. Explain how tools expand the range of tasks LLM agents can perform, using an example from the section.
- Tool Calling Process. Describe the role of a textual tool description and trace the basic tool-calling process through the returned result.
- Standardized Tool Interface. Explain why tools with different functionality need a common interface and standardized textual descriptions, and how BaseTool establishes that standard.
- Structured Tool Calling Flow. Trace how an LLM's tool request becomes a ToolCall, is executed through a tool, and returns as a ToolCallResult.
- Tool call request representation. Explain how a ToolCall packages an LLM’s tool request, including its identifier, selected tool name, and invocation arguments.
- Tool call result outcomes. Describe how ToolCallResult links an execution outcome to its request and represents success or failure.
- BaseTool interface contract. Explain the roles of BaseTool’s three attributes and its abstract __call__ method, and describe how abstract properties enforce a consistent subclass interface.
- Tool parameter JSON schemas. Explain how JSON Schema describes data requirements and why the framework uses it for tool parameters.
- Hailstone tool subclass example. Trace how the Hailstone BaseTool subclass describes its input and executes one Hailstone step.
- Non-blocking tool execution. Explain how AsyncBaseTool differs from synchronous BaseTool while waiting for external results, and why that can improve performance.
- AsyncBaseTool interface. Describe how the AsyncBaseTool interface compares with BaseTool.
- Coroutine invocation in Python. Describe how Python declares and runs an asynchronous function, including how to obtain its result from asynchronous and synchronous code.
- Automatic function tool wrapping. Explain how SimpleFunctionTool turns a Python function into a tool and what it automatically implements.
- Function Derived Tool Metadata. Explain how SimpleFunctionTool obtains its name and description from the wrapped Python function.
- Signature Based Schema Generation. Describe how function_signature_to_json_schema derives a parameter schema from a function signature.
- Validated Function Call Execution. Trace how SimpleFunctionTool validates a ToolCall, delegates to the wrapped function, and reports failures.
- Asynchronous function tool wrapping. Explain how AsyncSimpleFunctionTool adapts SimpleFunctionTool for asynchronous functions and delegates calls to the wrapped function.
- Pydantic function tool usage. Describe how PydanticFunctionTool wraps a function whose parameters are supplied through a Pydantic BaseModel and can accept ToolCall objects.
- Pydantic schema and validation. Explain how PydanticFunctionTool uses Pydantic to generate its parameter schema and validate inputs.
- Tool-Based Agent Specialization. Explain how an agent’s available tools can reflect its responsibilities and distinguish it from other agents in a MAS.
- Tools for Subtask Delegation. Describe the role tools can play in dispatching other agents to handle subtasks during a larger task.
What it builds on
- The processing loop (chapter 1) · The previously introduced tool-calling process.
- The basics of UML diagrams (chapter 1) · UML class diagrams distinguish attributes from methods.
- Assembling LLM agents into MAS (chapter 1) · Assembling LLM agents into a multi-agent system
Section by section
Introduction
This introduction explains how tools expand LLM agents’ capabilities and outlines the basic tool-calling process.
- Tools Expand Agent Capabilities: Explain how tools expand the range of tasks LLM agents can perform, using an example from the section.
Why it matters: Tools let an agent tackle tasks beyond producing text alone. - Tool Calling Process: Describe the role of a textual tool description and trace the basic tool-calling process through the returned result.
Why it matters: This sequence shows how a tool’s output becomes part of the LLM’s response.
Key terms: tools, LLM agents, textual description, tool-calling process, tool-call request
2.1 BaseTool: a blueprint for tools
This section introduces a standardized tool interface, the data structures used in tool calls, and their representation in UML.
- Standardized Tool Interface: Explain why tools with different functionality need a common interface and standardized textual descriptions, and how BaseTool establishes that standard.
Why it matters: A common interface lets an agent work consistently with tools that do very different things. - Structured Tool Calling Flow: Trace how an LLM's tool request becomes a ToolCall, is executed through a tool, and returns as a ToolCallResult.
Why it matters: This flow shows how the common interface connects an LLM's request to a tool's result. - Tool Class Structural Overview: Describe the attributes shown for BaseTool, ToolCall, and ToolCallResult, and distinguish the input and output structures.
Why it matters: The class overview identifies the pieces that will be implemented for the interface and call data. - UML Inheritance and Abstraction: Describe how the UML diagram represents inheritance and an abstract class, including what abstract methods require of BaseTool subclasses.
Why it matters: Reading these UML conventions reveals which classes inherit and what tool subclasses must implement.
Key terms: BaseTool, textual descriptions, standard interface, ToolCall, ToolCallResult, __call__(), name, description, parameters_json_schema, id_
2.1.1 Implementing ToolCall and ToolCallResult
This section implements Pydantic data structures for representing tool-call requests and their execution results.
- Tool call request representation: Explain how a ToolCall packages an LLM’s tool request, including its identifier, selected tool name, and invocation arguments.
Why it matters: This representation gives the framework the information needed to identify and invoke a requested tool. - Tool call result outcomes: Describe how ToolCallResult links an execution outcome to its request and represents success or failure.
Why it matters: A consistent result object lets the framework associate an outcome with the request and distinguish success from failure. - Pydantic model construction: Describe how Pydantic supports defining and constructing ToolCall and ToolCallResult, including the default for a ToolCall identifier.
Why it matters: These Pydantic features keep the data structure definitions and object creation concise. - Structured tool request formats: Explain why provider APIs and SDKs typically elicit tool-call requests in a pre-specified structured format rather than relying on free text.
Why it matters: It explains why the natural-language example differs from the usual practical approach.
Key terms: ToolCall, id_, tool_name, arguments, ToolCallResult, tool_call_id, content, error, pydantic.BaseModel, model fields
2.1.2 Defining BaseTool
This section defines the BaseTool interface, explains its use of JSON Schema, and implements a Hailstone tool as an example subclass.
- BaseTool interface contract: Explain the roles of BaseTool’s three attributes and its abstract __call__ method, and describe how abstract properties enforce a consistent subclass interface.
Why it matters: This contract makes different tools usable through a consistent interface. - Tool parameter JSON schemas: Explain how JSON Schema describes data requirements and why the framework uses it for tool parameters.
Why it matters: Parameter schemas communicate the expected inputs in a format widely supported by LLM tooling. - Hailstone tool subclass example: Trace how the Hailstone BaseTool subclass describes its input and executes one Hailstone step.
Why it matters: The example shows how the abstract tool interface becomes an executable tool.
Key terms: BaseTool, name, description, parameters_json_schema, __call__, @abstractmethod, JSON Schema, properties, required, type
2.1.3 The AsyncBaseTool
This section introduces AsyncBaseTool, explains its non-blocking execution and interface, and describes how to call asynchronous Python functions.
- Non-blocking tool execution: Explain how AsyncBaseTool differs from synchronous BaseTool while waiting for external results, and why that can improve performance.
Why it matters: This distinction helps you choose asynchronous tools for operations that spend time waiting on external services. - AsyncBaseTool interface: Describe how the AsyncBaseTool interface compares with BaseTool.
Why it matters: The familiar interface makes the asynchronous variation easier to relate to the tool blueprint. - Coroutine invocation in Python: Describe how Python declares and runs an asynchronous function, including how to obtain its result from asynchronous and synchronous code.
Why it matters: Knowing how to run and await a coroutine lets you invoke an asynchronous tool correctly.
Key terms: AsyncBaseTool, BaseTool, asynchronous execution, blocking, concurrent execution, __call__(), async, coroutine, await, asyncio.run()
2.2 SimpleFunctionTool: a subclass of BaseTool
This section introduces function-wrapping tool classes and contrasts their synchronous and asynchronous forms.
- Automatic function tool wrapping: Explain how SimpleFunctionTool turns a Python function into a tool and what it automatically implements.
Why it matters: Wrapping a function makes it more convenient to provide a tool for an LLM or agent. - Synchronous and asynchronous wrappers: Distinguish SimpleFunctionTool from AsyncSimpleFunctionTool in their base classes and wrapped functions.
Why it matters: The two wrappers accommodate different kinds of Python functions while retaining the appropriate tool base class.
Key terms: SimpleFunctionTool, BaseTool, name, description, parameters_json_schema, __call__(), AsyncSimpleFunctionTool, AsyncBaseTool, func
2.2.1 Implementing SimpleFunctionTool
This section implements SimpleFunctionTool by deriving tool metadata and a parameter schema from a Python function, then validating and delegating tool calls to it.
- Function Derived Tool Metadata: Explain how SimpleFunctionTool obtains its name and description from the wrapped Python function.
Why it matters: This pattern turns a Python function into a tool without requiring its name and description to be written separately. - Signature Based Schema Generation: Describe how function_signature_to_json_schema derives a parameter schema from a function signature.
Why it matters: The generated schema describes the function's inputs for tool use without being written manually. - Validated Function Call Execution: Trace how SimpleFunctionTool validates a ToolCall, delegates to the wrapped function, and reports failures.
Why it matters: Validation and structured error reporting make calls to wrapped functions usable as tool calls.
Key terms: SimpleFunctionTool, BaseTool, func, name, description, function_signature_to_json_schema(), parameters_json_schema, function signature, JSON Schema, default values
2.2.2 The AsyncSimpleFunctionTool
This section adapts automatic function-tool creation to asynchronous Python functions, highlighting the constructor and call differences from SimpleFunctionTool.
- Asynchronous function tool wrapping: Explain how AsyncSimpleFunctionTool adapts SimpleFunctionTool for asynchronous functions and delegates calls to the wrapped function.
Why it matters: This adaptation lets the tool wrapper work with asynchronous functions without changing the validation approach. - Awaitable function type annotation: Describe what the constructor's Callable[…, Awaitable[Any]] annotation says about func and how Awaitable relates to coroutines.
Why it matters: The annotation expresses the kind of result the wrapper must be able to await.
Key terms: AsyncSimpleFunctionTool, SimpleFunctionTool, func, __call__, await, Callable[…, Awaitable[Any]], typing.Awaitable, typing.Coroutine, asyncio.Futures, asyncio.Tasks
2.3 PydanticFunctionTool: another subclass of BaseTool
This section introduces PydanticFunctionTool as a function wrapper that uses Pydantic for tool parameter schemas and validation.
- Pydantic function tool usage: Describe how PydanticFunctionTool wraps a function whose parameters are supplied through a Pydantic BaseModel and can accept ToolCall objects.
Why it matters: This wrapper makes a function available as a tool while defining its parameters with a Pydantic model. - Pydantic schema and validation: Explain how PydanticFunctionTool uses Pydantic to generate its parameter schema and validate inputs.
Why it matters: Pydantic provides the wrapper's schema generation and input validation rather than relying on the earlier from-scratch approach.
Key terms: PydanticFunctionTool, BaseTool, pydantic.BaseModel, ToolCall, parameters_json_schema, __call__, BaseModel.model_json_schema(), BaseModel.model_validate()
2.4 Extending to MAS: Tools
This section connects the chapter’s tool abstractions to agent specialization and subtask delegation in multi-agent systems.
- Function-Based Tool Wrappers: Explain how SimpleFunctionTool and AsyncSimpleFunctionTool make Python functions usable by LLMs and LLM agents.
Why it matters: Function wrappers connect ordinary Python code to the tools agents can use. - Tool-Based Agent Specialization: Explain how an agent’s available tools can reflect its responsibilities and distinguish it from other agents in a MAS.
Why it matters: Choosing tools helps align each agent’s capabilities with its role. - Tools for Subtask Delegation: Describe the role tools can play in dispatching other agents to handle subtasks during a larger task.
Why it matters: Tools can support delegation as well as provide ordinary capabilities to an individual agent.
Key terms: SimpleFunctionTool, AsyncSimpleFunctionTool, Pydantic, JSON schema validation, tools, responsibilities, MAS, dispatching, subtasks, LLM agents
2.5 Summary
Where this is used later
- Hailstone tool call with OllamaLLM (chapter 3) · Applies tool calling with an LLM.
- Defining BaseLLM (chapter 3) · Uses the standardized tool interface when working with LLMs.
- (chapter intro) (chapter 4) · The framework’s tool blueprint.
- Designing a processing loop (chapter 4) · Places tool calling in an agent processing loop.
- LLMAgent: a simple LLM agent class (chapter 4) · The framework's tool abstraction.
- The tool-calling process for an MCP tool (chapter 5) · The framework's existing blueprint for tools.
- Implementing CompleteResult, ChatMessage, and ChatRole (chapter 3) · The ToolCall data structure.
- Implementing LLMAgent: Part 1 (chapter 4) · The asynchronous tool abstraction included in the Tool type.
Concepts explained in this chapter
- ToolCallResultToolCallResult is a framework data structure that records a tool-call identifier, its execution result, and whether an error occurred.
- tool useToolCall is a data structure representing a requested tool invocation and its arguments.
- __call__() methodThe __call__() method is a Python special method that defines how an object behaves when invoked with function-call syntax.
- basetoolBaseTool is the book-specific base class defining the common interface for callable tools in the framework.
- JSON SchemaJSON Schema is a standard for describing and validating the structure, data types, and constraints of JSON data.
- asyncbasetoolAsyncBaseTool is a framework base class for tools whose operations execute asynchronously and can avoid blocking while awaiting external results.
- SimpleFunctionToolSimpleFunctionTool is a book-specific tool wrapper that automatically exposes a synchronous Python function as an invocable agent tool.
- toolA tool is an externally executable capability that an LLM agent can invoke to perform an operation or obtain information.
- abstract methodAn abstract method is a method that concrete subclasses must implement before they can be instantiated.
- BaseModelPydantic BaseModel is a base class for defining typed data models that validate and serialize structured data.
- concurrencyConcurrency is the coordination of multiple tasks whose execution can overlap in time.
- BaseModel.model_json_schema()BaseModel.model_json_schema() is a Pydantic method that generates a JSON Schema describing a model.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
