toolkit_per_tool_instructions.py
"""
Toolkit Per-Tool Instructions
=============================
Demonstrates @tool(instructions=...) works both as a bare function
and inside a Toolkit.
Previously, per-tool instructions were silently dropped when tools
were registered via a Toolkit. This cookbook verifies both paths
now work correctly.
"""
from unittest.mock import MagicMock
from agno.agent import Agent
from agno.agent._tools import parse_tools
from agno.models.openai import OpenAIResponses
from agno.tools import Toolkit, tool
# Path 1: Bare function with instructions
@tool(instructions="Always explain your reasoning when subtracting.")
def subtract(a: int, b: int) -> int:
"""Subtract b from a."""
return a - b
# Path 2: Toolkit with per-tool instructions
class MathToolkit(Toolkit):
def __init__(self):
super().__init__(name="math_toolkit", tools=[self.add, self.multiply])
@tool(instructions="Always show your work step-by-step when adding numbers.")
def add(self, a: int, b: int) -> int:
"""Add two numbers together."""
return a + b
@tool(instructions="When multiplying, mention if the result is even or odd.")
def multiply(self, a: int, b: int) -> int:
"""Multiply two numbers together."""
return a * b
if __name__ == "__main__":
agent = Agent(
model=OpenAIResponses(id="gpt-5.4"),
tools=[subtract, MathToolkit()],
)
# Trigger tool parsing to populate _tool_instructions
mock_model = MagicMock()
mock_model.supports_native_structured_outputs = False
parse_tools(agent=agent, tools=agent.tools, model=mock_model)
# Inspect what instructions reached the agent
print("=" * 70)
print("INSPECTING: agent._tool_instructions")
print("=" * 70)
for i, instruction in enumerate(agent._tool_instructions, 1):
print(f"\n[{i}] {instruction}")
print("\n" + "=" * 70)
expected_count = 3 # 1 bare function + 2 from toolkit
if len(agent._tool_instructions) == expected_count:
print(f"SUCCESS: All {expected_count} per-tool instructions captured")
print(" - 1 from bare function (subtract)")
print(" - 2 from Toolkit (add, multiply)")
else:
print(
f"FAILURE: Expected {expected_count}, got {len(agent._tool_instructions)}"
)
Run the Example
1
Set up your virtual environment
uv venv --python 3.12
source .venv/bin/activate
uv venv --python 3.12
.venv\Scripts\activate
2
Install dependencies
uv pip install -U agno openai
3
Run the example
Save the code above as
toolkit_per_tool_instructions.py, then run:python toolkit_per_tool_instructions.py