Tools Types

The types module in the jazzmine tool system defines the foundational data structures used to describe agent-callable skills. These types serve as the "Contract" between the Python-defined logic and the LLM's reasoning engine. By providing structured definitions for parameters and responses, jazzmine ensures that the LLM understands exactly what arguments a tool requires and how to interpret the results it returns.

Tool System: Core Types

Behavior and Context

In the jazzmine architecture, these types are used in three specific phases:

Definition: Developers use ToolParameter and Tool (via the @tool decorator) to document the interface of a function.
Prompt Engineering: The build_prompt() methods of these classes generate highly structured XML. This XML is injected into the Agent's system prompt, providing the "Manual" the LLM reads to understand its capabilities.
Execution Feedback: The ToolResponse class standardizes the output of a tool execution, whether it succeeded or failed, and formats it back into XML for the agent to "see" the result.

Purpose

Interface Abstraction: Providing a standardized way to describe function signatures across different sandboxes.
LLM Guidance: Using attributes like examples, options, and source to significantly reduce hallucination and argument errors.
Result Standardization: Ensuring that every tool call returns a consistent success/failure status and a structured data payload.
Automated Documentation: Eliminating manual prompt engineering by deriving the LLM's tool-docs directly from Python code.

Class: ToolParameter

ToolParameter describes a single input argument for a tool. It is much more than a type hint; it includes semantic information used to guide the LLM's value selection.

Attributes

Attribute	Type	Description
name	str	The actual variable name in the Python function.
type	str	The type string shown to the LLM (e.g., "int", "List[str]").
description	Optional[str]	A natural language explanation of the parameter's purpose.
default	Optional[Any]	The value used if the LLM omits this argument.
required	bool	If True, the LLM is instructed that this value is mandatory.
options	Optional[List]	A strict list of allowed values (Enums).
examples	Optional[List]	Sample values to help the LLM understand the expected format.
source	Literal	A hint on where to find the data: 'context', 'history', or 'all'.
display_name	Optional[str]	A human-friendly label for logs and UI components.

High-Level API & Examples

The build_prompt() method generates the XML schema the LLM sees.

Example: A Complex Parameter Definition

from jazzmine.core.tools import ToolParameter

param = ToolParameter(
    name="order_id",
    type="str",
    description="The unique alphanumeric ID of the customer's order.",
    required=True,
    examples=["ORD-12345", "ORD-99887"],
    source="context",
    display_name="Order Reference Number"
)

# Generated XML via build_prompt():
# <parameter name="order_id" type="str" required="True">
#   <description>The unique alphanumeric ID of the customer's order.</description>
#   <source>context</source>
#   <display_name>Order Reference Number</display_name>
#   <examples>
#     <example>ORD-12345</example>
#     <example>ORD-99887</example>
#   </examples>
# </parameter>

Class: ToolResponse

ToolResponse is the mandatory return structure for every tool. It wraps the actual business data with status metadata.

Attributes

Attribute	Type	Description
success	bool	Indicates if the tool performed its task correctly.
message	Optional[str]	A human-readable status or error message. Mandatory on failure.
data	Optional[Any]	The structured payload returned by the tool (must be JSON-safe).

High-Level API & Examples

The build_prompt() method converts the execution result into XML for the agent's context.

Example: Creating a Response

from jazzmine.core.tools import ToolResponse

# Case A: Success
res_ok = ToolResponse(
    success=True,
    data={"status": "shipped", "eta": "2023-12-01"}
)

# Case B: Soft Failure (Handled Error)
res_fail = ToolResponse(
    success=False,
    message="Order ID not found in database.",
    data={"attempted_id": "ORD-000"}
)

Class: Tool

The Tool class is the top-level aggregate that represents a complete skill. It groups a name and description with a collection of ToolParameter objects.

Attributes

Attribute	Type	Description
name	str	The unique name of the tool (usually the function name).
description	str	A high-level explanation of what the tool does.
parameters	List	A list of ToolParameter instances.

High-Level API & Examples

The build_prompt() method assembles the complete documentation block for the LLM.

Example: Defining a complete Tool

from jazzmine.core.tools import Tool, ToolParameter

inventory_tool = Tool(
    name="check_inventory",
    description="Check stock levels for a specific product in a warehouse.",
    parameters=[
        ToolParameter("product_id", "str", "The SKU of the item.", required=True),
        ToolParameter("warehouse", "str", "The city name.", default="New York")
    ]
)

print(inventory_tool.build_prompt())

Error Handling

Serialization: Both ToolParameter and ToolResponse rely on to_dict(). If you pass non-JSON-serializable objects (like a database connection handle or a custom class) into the data or default fields, serialization will fail during the transfer from the sandbox to the host.
XML Integrity: The build_prompt() methods perform basic string formatting. If your descriptions contain raw XML tags, they may interfere with the agent's parsing logic.

Remarks

Prompt Optimization: The XML format used in build_prompt() is intentionally verbose. LLMs utilize the tag structure to "anchor" their attention, leading to much higher accuracy in multi-parameter tool calls compared to JSON-schema prompts.
Identity: The name of a Tool should be unique within its assigned sandbox to prevent collisions during script generation.

On this page