Built-in Tools

Huf provides built-in tools for common Frappe operations. These tools enable agents to interact with DocTypes, make HTTP requests, and chain to other agents—all without writing custom code.

Overview

Built-in tools are pre-configured and ready to use. Simply create an Agent Tool Function, select the tool type, and assign it to your agent.

Available Built-in Tools:

• Get Document
• Create Document
• Update Document
• Delete Document
• Submit Document
• Get List
• Run Agent
• HTTP Request

Each tool is optimized for its specific purpose and respects Frappe’s permission system.

Get Document

Purpose: Retrieve a single document by its name or ID

Use Cases:

• “Show me customer CUST-001”
• “What’s the status of order SO-2024-123?”
• “Get details for employee EMP-00045”

Configuration

Example Tool Definition

Tool Name: get_customer
Description: Retrieve detailed information about a customer by their ID or name
Types: Get Document
Reference DocType: Customer

Example Usage

Return Value

Full document as JSON with all standard and custom fields:

{
  "name": "CUST-001",
  "customer_name": "ABC Corporation",
  "customer_type": "Company",
  "customer_group": "Wholesale",
  "territory": "United States",
  "email_id": "contact@abc.com",
  ...
}

Best Practices

• Use specific DocTypes per tool (not generic “get any document”)
• Name tools clearly: get_customer, get_invoice, get_lead
• Include DocType name in description for clarity
• Document expected ID format in description

Create Document

Purpose: Create a new document in Frappe

Use Cases:

• “Create a new lead for XYZ Company”
• “Make a support ticket for this issue”
• “Add a new employee record”

Configuration

Example Tool Definition

Tool Name: create_lead
Description: Create a new lead in the system with company name, contact info, and source
Types: Create Document
Reference DocType: Lead

Example Usage

Parameter Format

{
  "lead_name": "John Doe",
  "company_name": "XYZ Corp",
  "email_id": "john@xyz.com",
  "source": "Website",
  "status": "Lead"
}

Required Fields

The agent must provide all mandatory fields for the DocType:

• Check DocType definition for required fields
• Agent will fail if required fields are missing
• Include field requirements in tool description

Return Value

The created document with auto-generated fields:

{
  "name": "LEAD-2024-001",
  "lead_name": "John Doe",
  "creation": "2024-01-15 10:30:00",
  "owner": "user@example.com",
  ...
}

Best Practices

• List required fields in tool description
• Provide example values in description
• Use separate tools for different DocTypes
• Consider default values for optional fields
• Mention any validation rules in description

Update Document

Purpose: Modify an existing document

Use Cases:

• “Update the customer’s email address”
• “Change the order status to Confirmed”
• “Add a comment to this support ticket”

Configuration

Example Tool Definition

Tool Name: update_customer
Description: Update customer information like email, phone, address, or custom fields
Types: Update Document
Reference DocType: Customer

Example Usage

Parameter Format

{
  "name": "CUST-001",
  "fields": {
    "email_id": "newemail@company.com",
    "phone": "+1-555-0123"
  }
}

Partial Updates

Only provide fields that need to change:

• Other fields remain unchanged
• No need to pass entire document
• Validations still apply

Return Value

Updated document with modifications:

{
  "name": "CUST-001",
  "customer_name": "ABC Corporation",
  "email_id": "newemail@company.com",
  "phone": "+1-555-0123",
  "modified": "2024-01-15 11:00:00",
  "modified_by": "agent@example.com",
  ...
}

Best Practices

• Clearly state which fields can be updated
• Warn about readonly or auto-computed fields
• Mention any update restrictions (workflow states, etc.)
• Consider separate tools for different update types

Delete Document

Purpose: Remove a document from the system

Use Cases:

• “Delete draft order SO-2024-999”
• “Remove the test customer”
• “Delete cancelled invoice INV-TEST-001”

Configuration

Example Tool Definition

Tool Name: delete_draft_order
Description: Delete a draft sales order that hasn't been submitted yet
Types: Delete Document
Reference DocType: Sales Order

Example Usage

Return Value

Success message or error if deletion failed:

{
  "message": "Document deleted successfully"
}

Safety Considerations

Deletion is permanent. Best practices:

• Only allow deleting specific document states (drafts, cancelled)
• Add clear warnings in tool description
• Consider requiring confirmation in agent instructions
• Log deletions for audit trail
• Restrict to trusted agents only

Permissions

Deletion respects Frappe permissions:

• User must have delete permission for DocType
• Document must be deletable (not submitted, not linked, etc.)
• Frappe may prevent deletion if linked documents exist

Submit Document

Purpose: Submit a submittable DocType (move from Draft to Submitted state)

Use Cases:

• “Submit the sales order”
• “Submit invoice INV-2024-001”
• “Approve and submit the purchase order”

Configuration

Example Tool Definition

Tool Name: submit_sales_order
Description: Submit a sales order to confirm it and make it official
Types: Submit Document
Reference DocType: Sales Order

Example Usage

Submittable DocTypes

Only certain DocTypes can be submitted:

• Sales Order, Purchase Order
• Sales Invoice, Purchase Invoice
• Delivery Note, Purchase Receipt
• Payroll Entry, Journal Entry
• Custom submittable DocTypes

Check DocType definition: is_submittable = 1

Return Value

Submitted document with updated status:

{
  "name": "SO-2024-123",
  "docstatus": 1,
  "status": "To Deliver and Bill",
  ...
}

Docstatus values:

• 0 = Draft
• 1 = Submitted
• 2 = Cancelled

Best Practices

• Validate document is ready before submitting
• Check required fields are filled
• Mention any submission validations in tool description
• Consider pre-submission checks in agent instructions

Get List

Purpose: Query multiple documents with filtering, sorting, and pagination

Use Cases:

• “List all open support tickets”
• “Show top 10 customers by revenue”
• “Find leads created this week”

Configuration

Example Tool Definition

Tool Name: list_support_tickets
Description: Search and filter support tickets by status, priority, customer, or date
Types: Get List
Reference DocType: Support Ticket

Example Usage

Filter Syntax

Simple Filters:

{
  "status": "Open",
  "priority": "High"
}

→ status = "Open" AND priority = "High"

Operator Filters:

{
  "creation": [">", "2024-01-01"],
  "grand_total": [">=", 10000]
}

Available Operators:

• =, !=: Equality
• >, <, >=, <=: Comparison
• like, not like: Pattern matching
• in, not in: List membership
• is, is not: NULL checks
• between: Range

Complex Filters:

{
  "status": ["in", ["Open", "Working"]],
  "priority": ["!=", "Low"],
  "creation": ["between", ["2024-01-01", "2024-01-31"]]
}

Selecting Fields

Return only needed fields to reduce token usage:

{
  "filters": {"status": "Open"},
  "fields": ["name", "subject", "priority", "creation"]
}

Benefits:

• Faster queries
• Lower token costs
• More focused results

Sorting

Format: "fieldname asc" or "fieldname desc"

Examples:

"order_by": "creation desc"  // Newest first
"order_by": "name asc"       // Alphabetical
"order_by": "priority desc, creation desc"  // Multi-level sort

Pagination

For large result sets:

{
  "limit": 20,        // Results per page
  "limit_start": 0    // Offset (0, 20, 40, ...)
}

Page 1: limit=20, limit_start=0
Page 2: limit=20, limit_start=20
Page 3: limit=20, limit_start=40

Return Value

Array of documents:

[
  {
    "name": "TICKET-001",
    "subject": "Login issue",
    "priority": "High",
    "status": "Open"
  },
  {
    "name": "TICKET-002",
    "subject": "Payment failed",
    "priority": "High",
    "status": "Open"
  }
]

Best Practices

• Start with limit=10 or 20 to avoid overwhelming agent
• Use filters to narrow results
• Select only necessary fields
• Include meaningful sort order
• Handle empty results gracefully in agent instructions

Run Agent

Purpose: Chain to another specialized agent

Use Cases:

• Delegate to specialized agents
• Multi-domain workflows
• Complex multi-step processes

Configuration

Example Tool Definition

Tool Name: ask_sales_agent
Description: Delegate sales-related questions to the specialized sales agent
Types: Run Agent

Example Usage

Agent Chaining Strategies

Specialization:

Main Agent (general)
  ├─> Sales Agent (sales queries)
  ├─> Support Agent (technical issues)
  └─> HR Agent (employee questions)

Sequential Processing:

Intake Agent
  └─> Validation Agent
      └─> Processing Agent
          └─> Notification Agent

Parallel Consultation:

Decision Agent
  ├─> Risk Assessment Agent
  ├─> Financial Analysis Agent
  └─> Legal Review Agent
→ Decision Agent synthesizes all responses

Return Value

The other agent’s response:

{
  "response": "Based on current pipeline and historical data, Q2 forecast is $2.5M with 15% growth over Q1. Key drivers are..."
}

Best Practices

• Create focused, specialized agents
• Define clear handoff criteria
• Avoid circular agent calling (A calls B calls A)
• Consider conversation history management
• Monitor costs (multiple agents = multiple runs)

Limitations

• Each chained agent call adds latency
• Costs multiply with each agent
• Deep chains can lose context
• Consider flattening chains if performance suffers

HTTP Request

Purpose: Call external APIs and webhooks

Use Cases:

• Send Slack notifications
• Look up external data
• Trigger webhooks
• Integrate with third-party services

Configuration

Example Tool Definition

Tool Name: send_slack_notification
Description: Send a message to a Slack channel via webhook URL
Types: HTTP Request

Example Usage

{
"url": "https://hooks.slack.com/services/T00/B00/XXXX",
"method": "POST",
"headers": {"Content-Type": "application/json"},
"body": {
  "text": "New high-priority ticket: TICKET-123",
  "channel": "#support"
}
}

Security Considerations

Webhook URLs contain secrets:

• Store URLs in agent instructions (not tool)
• Use environment variables for sensitive endpoints
• Restrict agent access appropriately
• Audit HTTP request logs

Common Integrations

Slack:

{
  "url": "https://hooks.slack.com/...",
  "method": "POST",
  "body": {"text": "Message"}
}

Twilio SMS:

{
  "url": "https://api.twilio.com/2010-04-01/Accounts/ACCOUNT_SID/Messages.json",
  "method": "POST",
  "headers": {"Authorization": "Basic ..."},
  "body": {"To": "+1555...", "Body": "Message"}
}

REST API:

{
  "url": "https://api.example.com/v1/resource",
  "method": "GET",
  "headers": {"Authorization": "Bearer TOKEN"}
}

Return Value

HTTP response:

{
  "status_code": 200,
  "body": {
    "success": true,
    "message_id": "12345"
  }
}

Best Practices

• Validate URLs in agent instructions
• Handle API errors gracefully
• Rate-limit external calls
• Cache responses when appropriate
• Log all external requests

Permissions

All built-in tools respect Frappe’s permission system:

• User permissions apply: Agent runs with user’s permissions
• Role-based access: Standard Frappe roles control access
• No elevation: Tools cannot bypass permissions
• Audit trail: All operations logged

Example:

User with “Sales User” role runs agent:

Error Handling

Tools return errors when:

• Document not found
• Permission denied
• Validation failures
• Required fields missing
• DocType doesn’t exist

Agent should handle errors gracefully:

Performance Tips

1. Use Get List efficiently: Filter and limit results
2. Select fields: Don’t fetch unnecessary data
3. Batch operations: Group similar queries
4. Cache results: In conversation memory for multi-turn interactions
5. Minimize tool calls: One good query > multiple small queries

What’s Next?

• Creating Custom Tools - Build your own tools
• Publishing Tools - Share tools via apps
• Tools Concept - Tool fundamentals
• Creating Agents - Assign tools to agents

Questions? Visit GitHub discussions .