Tool System: Core Types

1. 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.

2. 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.

3. Class: ToolParameter

Introduction

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

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>

5. Class: ToolResponse

Introduction

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

Attributes

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"}
)

6. Class: Tool

Introduction

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

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())

7. 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.

8. 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.