Tools Overview

What Are Tools in Junis?

Tools are specialized functions that agents can call to perform specific actions or access external data. They extend your agent’s capabilities beyond text generation, enabling real-world interactions. Think of tools as skills your agents can learn:

🔍 Search tools: Find information from web, databases, or documents
📄 Document tools: Process PDF, Excel, Word, PowerPoint files
🔌 External connectors: Access Salesforce, DataLab, GitHub, Firecrawl
🧠 RAG tools: Search uploaded documents with AI-powered retrieval

Agent Intelligence: Agents automatically decide when and how to use tools based on user requests. You don’t need to manually trigger them.

Tool Types

Junis supports four types of tools, each designed for specific use cases:

Regular Tools

Python FunctionsCustom async functions you build for your specific needs.Examples: Search databases, call APIs, process data

Claude Skills

Official Anthropic ToolsPrebuilt document processors powered by Claude.Examples: PDF extraction, Excel analysis, PPTX creation

External Connectors

Third-Party IntegrationsConnect to external systems and services.Examples: Salesforce, DataLab, GitHub, Firecrawl (via MCP)

RAG Tools

Document RetrievalAuto-generated search tools for uploaded documents.Examples: Company policies, employee handbooks, product specs

How Agents Use Tools

🤖 Automatic Tool Selection

Agents use tools intelligently based on:

User Request: What the user is asking for
Tool Descriptions: What each tool can do (from docstrings)
Conversation Context: Previous messages and results

Example Workflow:

User: "Find the latest news about artificial intelligence"
  ↓
Agent thinks:
  - User wants to search the web for current information
  - I have a tool called "google_search"
  - Its description says it searches the web for real-time information
  - I should use this tool with query="latest artificial intelligence news"
  ↓
Agent calls: google_search("latest artificial intelligence news")
  ↓
Tool returns: {
  "results": [
    {
      "title": "AI Breakthrough in 2025",
      "url": "https://example.com/ai-news",
      "snippet": "Recent developments in AI technology..."
    }
  ]
}
  ↓
Agent responds: "I found recent AI news. Here are the latest developments: AI Breakthrough in 2025..."

No Manual Intervention: Once tools are configured, agents use them automatically without user or admin prompting.

📊 Tool Execution Flow

Available Built-in Tools

Junis provides a comprehensive set of prebuilt tools ready to use:

Document Processing (Claude Skills)

PDF
Excel
PowerPoint
Word

claude_pdf_processor

Extract text from PDFs
Extract tables and data
Create new PDFs
Merge multiple PDFs
Convert to images

Use Case: “Extract all customer information from this invoice PDF”

Search Tools

Web Search

google_searchSearch the web for real-time information using Google.Parameters:

query (str): Search query

Returns: Search results with titles, URLs, and snippetsUse Case: “Find the latest AI news” or “Search for Python tutorials”

Built-in Web Search (LLM Feature)

NEW: Agents can now perform web searches automatically during response generation without explicitly calling a tool.

Enable Web Search in Admin > Agents > Edit Agent:

Agent Configuration:
  Enable Web Search: ✅ ON

How It Works:

When enabled, the LLM can automatically search the web during response generation
No explicit tool call required - the model decides when to search
Uses LiteLLM’s web_search_options with search_context_size: "medium"

Difference from google_search Tool:

Feature	Built-in Web Search	google_search Tool
Activation	Automatic (LLM decides)	Explicit tool call
Configuration	Toggle in Agent settings	Assign tool to agent
Best For	General knowledge queries	Targeted searches

When to Use: Enable for agents that need to answer questions about current events, recent news, or real-time information without explicit search requests.

Payment Tools (AP2/x402 Protocol)

Premium Feature: Payment tools enable USDC-based agent usage fees with 80/20 revenue split (Agent Owner 80%, Platform 20%).

require_payment
verify_payment

require_payment(agent_id, network?)Request payment before agent execution.When to Use:

Premium agents that charge per use
Computationally expensive operations
Third-party API costs

Returns:

Payment requirements (amount, wallet, network)
EIP-3009 nonce for signature
80/20 split details

When to Use Tools

✅ Use Tools When You Need To:

Access External Data: Databases, APIs, file storage
Perform Complex Operations: File processing, calculations, analysis
Integrate Third-Party Services: Salesforce, GitHub, Firecrawl
Retrieve Uploaded Documents: RAG search through company docs

❌ Don’t Build Tools For:

Simple Text Generation: Agents already excel at this
One-Time Tasks: Better to do manually
Highly Variable Logic: Better in agent instructions
Duplicate Functionality: Use existing tools or MCP platforms

Getting Started with Tools

Step 1: Choose Your Approach

Use Built-in Tools
Connect MCP Platforms
Build Custom Tools
Upload Documents (RAG)

Fastest: Junis provides 15+ prebuilt tools.

Go to Admin > Agents
Edit your agent
Select tools from the Tools section
Save

Done! Your agent can now use those tools.

Step 2: Configure Agent Tools

Admin Dashboard → Agents → Edit Agent

Agent Configuration:
  Name: Customer Support Agent
  Type: LLM_AGENT
  Tools:
    Regular Tools:
      - claude_pdf_processor
      - google_search
    RAG Tools:
      - rag_company-policies_1234567890
  MCP Platforms:
    - GitHub (for repository management)
    - Firecrawl (for web scraping)

Step 3: Test with Chat

You: "Search for recent AI trends and create a GitHub issue to track them"

Agent:
1. Uses google_search("recent AI trends 2025")
2. Formats the results
3. Uses GitHub MCP to create issue

Response: "I found the latest AI trends and created a tracking issue in your repository."

Tool Best Practices

✅ DO:

Choose specific tools for specific tasks
Write clear tool descriptions (docstrings)
Test tools individually before assigning to agents
Monitor tool usage in logs
Handle errors gracefully
Use RAG for frequently accessed documents

❌ DON’T:

Add too many tools (max 10 per agent recommended)
Use tools with unclear purposes
Forget to update tool descriptions
Ignore tool errors in production
Hard-code sensitive data in tools

Real-World Examples

1. Customer Support Agent

Tools:

claude_pdf_processor: Extract info from uploaded docs
GitHub MCP: Create support tickets as issues
rag_faq_documents: Search company FAQ

User: “A customer asked about our return policy” Agent Flow:

Search rag_faq_documents for “return policy”
Extract relevant sections
Format a friendly response
Optionally create GitHub issue for tracking

2. Data Analysis Agent

Tools:

claude_xlsx_processor: Analyze Excel files
google_search: Find market trends and research
claude_pptx_creator: Generate presentation

User: “Analyze Q4 sales and create a presentation” Agent Flow:

Use claude_xlsx_processor to analyze sales spreadsheet
Use google_search for market research and context
Use claude_pptx_creator to generate slides

3. Premium Agent with Payments

Tools:

require_payment: Gate agent access with USDC payment
claude_pdf_processor: Document processing
google_search: Research capabilities

User: “Run premium analysis workflow” Agent Flow:

Call require_payment(agent_id="premium_agent")
Wait for user payment (MetaMask)
Verify payment signatures
Proceed with premium analysis using available tools

Tool Categories Reference

Category	Tools	Primary Use
Document Processing	claude_pdf_processor, claude_xlsx_processor, claude_pptx_creator, claude_docx_processor	File analysis, creation, extraction
Web Search	google_search	Real-time web information retrieval
Payment	require_payment, verify_payment	Premium agent gating
RAG	rag_ (auto-generated)	Document knowledge retrieval
External	MCP platform tools	Third-party service integration

Performance Considerations

⚡ Tool Execution Speed

Tool Type	Typical Latency	Notes
Database Query	100-500ms	Depends on query complexity
External API	1-5 seconds	Network dependent
Claude Skills	2-10 seconds	File processing time
RAG Search	1-3 seconds	Vertex AI Search latency
Payment	5-30 seconds	User signature + on-chain settlement

Optimization Tip: Group multiple simple queries into batch tools rather than making agents call tools repeatedly.

Troubleshooting

Agent not using available tools

Symptom: Tool is configured but agent doesn’t call itPossible Causes:

Tool description (docstring) unclear
Agent instruction doesn’t mention tool usage
Tool name not intuitive

Solution:

Review tool docstring for clarity
Add tool usage examples to agent instruction
Test with explicit request: “Use [tool_name] to…”

Tool execution fails silently

Symptom: Tool called but no result returnedPossible Causes:

Tool has unhandled exception
Missing required parameters
External service down

Solution:

Check agent session logs for errors
Test tool directly via API
Verify all environment variables set
Check external service status

RAG tool returns no results

Symptom: RAG search completes but finds nothingPossible Causes:

Documents not indexed yet (still processing)
Search query too specific
DataStore not created properly

Solution:

Go to Team > RAG Knowledge and check indexing status
Wait for “COMPLETED” status (can take 5-60 minutes)
Try broader search terms
Re-upload documents if status is “FAILED”

Payment tool timeout

Symptom: require_payment call takes too longPossible Causes:

Network congestion (Base blockchain)
CDP Facilitator API slow
User hasn’t signed MetaMask prompt

Solution:

Payment tools have 30-second timeout
Check Base network status: https://status.base.org
Ensure user completes MetaMask signature promptly
For testnet, use Base Sepolia (faster, free)

What’s Next?

Custom Integrations

Build custom MCP integrations

RAG Setup

Upload documents and create knowledge bases

Payment Integration

Set up USDC payments for premium agents

MCP Platforms

Connect external services via MCP

Additional Resources

Claude Skills: https://docs.anthropic.com/en/docs/build-with-claude/tool-use - Official Anthropic documentation on tool use

Need Help? Contact us at [email protected] for assistance with tool development and custom implementations.

User Guides

​What Are Tools in Junis?

​Tool Types

Regular Tools

Claude Skills

External Connectors

RAG Tools

​How Agents Use Tools

​🤖 Automatic Tool Selection

​📊 Tool Execution Flow

​Available Built-in Tools

​Document Processing (Claude Skills)

​Search Tools

Web Search

​Built-in Web Search (LLM Feature)

​Payment Tools (AP2/x402 Protocol)

​When to Use Tools

​✅ Use Tools When You Need To:

​❌ Don’t Build Tools For:

​Getting Started with Tools

​Step 1: Choose Your Approach

​Step 2: Configure Agent Tools

​Step 3: Test with Chat

​Tool Best Practices

​Real-World Examples

​1. Customer Support Agent

​2. Data Analysis Agent

​3. Premium Agent with Payments

​Tool Categories Reference

​Performance Considerations

​⚡ Tool Execution Speed

​Troubleshooting

​What’s Next?

Custom Integrations

RAG Setup

Payment Integration

MCP Platforms

​Additional Resources

What Are Tools in Junis?

Tool Types

How Agents Use Tools

🤖 Automatic Tool Selection

📊 Tool Execution Flow

Available Built-in Tools

Document Processing (Claude Skills)

Search Tools

Built-in Web Search (LLM Feature)

Payment Tools (AP2/x402 Protocol)

When to Use Tools

✅ Use Tools When You Need To:

❌ Don’t Build Tools For:

Getting Started with Tools

Step 1: Choose Your Approach

Step 2: Configure Agent Tools

Step 3: Test with Chat

Tool Best Practices

Real-World Examples

1. Customer Support Agent

2. Data Analysis Agent

3. Premium Agent with Payments

Tool Categories Reference

Performance Considerations

⚡ Tool Execution Speed

Troubleshooting

What’s Next?

Additional Resources