Tools

Tools are what make agents useful. Without tools, an agent can only chat. With tools, agents can read data, create records, call APIs, run workflows, and more.

What Are Tools?

Tools are functions that agents can call to interact with your Frappe system or external services. Think of them as the agent’s hands—they enable action, not just conversation.

The following table shows the kind of work agents do by calling tools:

The agent decides which tool to use based on the conversation and tool descriptions.

How Tools Work

The Tool Execution Flow

Every tool call follows a predictable loop between the user, the agent, and the target system. Understanding this flow helps when debugging why an agent did—or did not—use a tool.

Tool Selection

Agents choose tools by matching the user’s request against each tool’s metadata. The quality of this decision depends almost entirely on how clearly the tool is described.

Tool Types

Huf provides three categories of tools:

1. Built-in Tools

Built-in tools are pre-configured for common Frappe operations. They cover the document lifecycle and a few utility actions, so most agents can be assembled without writing any custom code.

2. Custom Tools

Custom tools are your own Python functions exposed to agents. They let you extend the platform beyond built-in operations while keeping the agent experience consistent.

Example:

def calculate_discount(customer_type, order_total):
    """Calculate discount based on customer type and order total."""
    if customer_type == "Wholesale":
        return order_total * 0.15
    elif order_total > 10000:
        return order_total * 0.10
    else:
        return order_total * 0.05

3. Discovered Tools

Discovered tools are functions auto-discovered from your Frappe apps. They reduce setup effort because they are registered automatically and can be reused across projects.

• Use the @agent_tool decorator in your app code to mark a function as a tool.
• Tools are auto-synced when the app is installed.
• No manual setup is required after the decorator is in place.
• Tools can be shared across projects because they travel with the app.

See Publishing Tools for details.

Tool Configuration

Agent Tool Function DocType

Tools are defined in Desk → Huf → Agent Tool Function. This DocType captures everything the agent needs to know in order to call the tool correctly.

Key Fields:

Adding Tools to Agents

Once created, a tool must be explicitly assigned to an agent before the agent can use it. This assignment step is also the main security gate for tool access.

In Agent DocType:

1. Scroll to the Agent Tool table.
2. Click Add Row.
3. Select the Tool Function from the dropdown.
4. Save the agent.

Agents can only use tools explicitly assigned to them.

Tool Parameters

Tools can accept parameters that the agent fills in based on conversation. Well-defined parameters make the difference between a tool that works reliably and one that the agent calls incorrectly.

Parameter Definition

For each parameter, specify the fields below so the agent understands exactly what to provide.

Example: Get Document Tool

The snippet below shows how a simple Get Document tool is declared. The agent uses this declaration to decide when to call the tool and what argument to pass.

{
  "name": "get_customer",
  "description": "Retrieve detailed information about a customer",
  "parameters": [
    {
      "name": "customer_id",
      "type": "String",
      "description": "The customer ID or name",
      "required": true
    }
  ]
}

Agent Behavior:

• The user says: “Show me info for CUST-001”.
• The agent extracts customer_id = "CUST-001".
• The agent calls get_customer("CUST-001").

Built-in Tool Details

Get Document

Get Document fetches a single document by name or ID. Use it when the user refers to a specific record and the agent needs its full details.

Parameters:

Returns: Full document with all fields.

Example:

get_document(doctype="Customer", name="CUST-001")

{ "name": "CUST-001", "customer_name": "ABC Corp", ... }

Create Document

Create Document creates a new document from a set of field values. It is the right choice when the user asks to add a record rather than update an existing one.

Parameters:

Returns: Created document.

Example:

Agent Call: create_document(
  doctype="Lead",
  fields={
    "lead_name": "John Doe",
    "company_name": "XYZ Inc",
    "email_id": "john@xyz.com"
  }
)

Update Document

Update Document modifies an existing document. Use it when the user wants to change specific fields on a known record.

Parameters:

Returns: Updated document.

Get List

Get List queries multiple documents with filtering, sorting, and pagination. It is useful whenever the user asks for a set of records rather than a single one.

Parameters:

Returns: Array of documents.

Example:

get_list(
doctype="Support Ticket",
filters={"status": "Open", "priority": "High"},
order_by="creation desc",
limit=10
)

[ {...}, {...}, ... ]

Run Agent

Run Agent chains to another agent for specialized tasks. It lets you keep each agent focused while still handling cross-domain requests in a single conversation.

Parameters:

Returns: The other agent’s response.

Use Case: Route work to specialized agents for different domains:

• Main agent → Sales agent (for sales questions)
• Main agent → Support agent (for technical issues)

Permissions and Security

Tool Execution Context

Tools execute with the permissions of the user who triggered the agent. This keeps the agent inside the same authorization boundaries as a normal Frappe user.

Security Best Practices

Follow these practices to keep agent capabilities aligned with what each user and agent actually needs.

1. Least Privilege: Only assign necessary tools to each agent.
2. Validate Inputs: Custom functions should validate parameters before acting on them.
3. Audit Logs: All tool calls are logged in Agent Run for review.
4. Permission Checks: Tools respect Frappe’s permission system by default.
5. No Elevation: Agents cannot escalate permissions beyond those of the triggering user.

Tool Performance

Optimizing Tool Calls

Every tool assigned to an agent adds decision overhead and tokens. Keeping the toolset tight improves both speed and accuracy.

• Minimize tool count: Only assign tools the agent is actually expected to use.
• Clear descriptions: Help agents choose correctly the first time, avoiding repeated calls.
• Efficient queries: Use filters in Get List to reduce data transfer.
• Batch when possible: Group similar operations in custom functions instead of making many small calls.

Tool Call Costs

Tool calls affect agent costs in a few concrete ways. Being aware of them makes it easier to control token usage.

• Tool definitions add tokens to the prompt.
• Tool results add tokens to the conversation.
• More tools means more tokens, which means higher cost.

Optimization Tips:

• Assign only relevant tools per agent.
• Use specific DocTypes instead of overly generic tools.
• Return only needed fields in Get List.
• Keep tool descriptions concise but clear.

Troubleshooting

When an agent misbehaves, the cause usually falls into one of four patterns. Use the checklist below to narrow it down quickly.

Agent doesn’t use a tool:

Tool call fails:

Wrong tool selected:

Slow performance:

Best Practices

Tool Design

Well-designed tools are easier for agents to understand and harder to misuse. Use the guidelines below when creating or naming tools.

Tool Assignment

Assign tools strategically so each agent has exactly the capabilities it needs and no more. Specialized agents are generally more reliable than general-purpose ones.

Strategic Assignment:

• Give agents only the tools they need.
• Create specialized agents with focused toolsets.
• Use agent chaining for cross-domain tasks.
• Test with minimal tools, then add as needed.

Example:

Not: One agent with all 20 tools

Documentation for Tools

Good documentation inside your custom functions directly improves agent behavior, because Huf uses docstrings and parameter descriptions as part of the tool metadata.

When creating custom tools:

• Write a function docstring; it becomes part of the tool description.
• Add parameter descriptions so the agent understands inputs.
• Include return value comments to clarify what the agent will receive.
• Provide examples in docstrings to improve agent behavior.

def send_slack_notification(channel, message):
    """
    Send a notification message to a Slack channel.
    
    Args:
        channel (str): Slack channel name (e.g., "#support")
        message (str): The message text to send
        
    Returns:
        dict: Success status and message ID
        
    Example:
        send_slack_notification("#alerts", "New high-priority ticket!")
    """
    # Implementation
    pass

What’s Next?

Now that you understand tools:

• Built-in Tools - Detailed guide to each built-in tool
• Creating Custom Tools - Build your own tools
• Publishing Tools - Share tools via apps
• Conversations - How agents maintain context

Need help with tools? Check the GitHub discussions  or open an issue.