Tools & Connectors

Tools give your agents the ability to access data, call APIs, and interact with your business systems. Without tools, agents can only reason based on what you tell them. With tools, they become powerful automation engines that can look up information, update systems, and take actions.

What are Tools?

Tools are integrations that allow agents to:

Access data - Search knowledge bases, query databases, retrieve records
Call APIs - Invoke external services and platforms
Perform actions - Create records, send emails, update systems
Make decisions - Use data from multiple sources to inform responses

Tool Types

QuivaWorks supports two main types of tools:

MCP Servers (Model Context Protocol)

What is MCP?

MCP (Model Context Protocol) is an open standard for connecting AI models to data sources and tools. It provides a standardized way for agents to discover, understand, and use integrations.Benefits:

✅ Standardized interface
✅ Self-describing (agents understand how to use them)
✅ Composable and reusable
✅ Growing ecosystem of integrations

API Integrations

Pre-configured HTTP integrations for popular services with authentication and parameter mapping already set up.

Adding Tools to Agents

From the Agent Configuration

Open your agent configuration
Click the Tools tab
Click Add Tool
Select from available options:
- MCP Servers - From marketplace or custom
- API Integrations - Pre-built connectors
Configure authentication and parameters
Save

Tool Selection Best Practices

Only add relevant tools

Don’t connect everything “just in case”:❌ Bad: Add 15 tools to every agent ✅ Good: Add only tools this specific agent needsWhy:

Each tool adds tokens (descriptions, parameters)
More tools = higher costs
More tools = more confusion for agent
More tools = slower responses

Example: Customer service agent needs:

Knowledge base search
Order lookup
Refund processor

Customer service agent does NOT need:

Lead enrichment
Social media posting
Inventory management

Provide clear tool descriptions

When configuring custom tools, write clear descriptions:❌ Bad: “Gets data” ✅ Good: “Searches the knowledge base for help articles by keyword. Returns title, summary, and full article content.”Why:

Agents read descriptions to understand when to use tools
Clear descriptions = correct tool usage
Vague descriptions = wrong tool or no tool usage

Name tools descriptively

Tool names should explain what they do:❌ Bad: “API 1”, “Tool”, “Function” ✅ Good: “Get Order Status”, “Search Knowledge Base”, “Process Refund”Why:

Agents select tools by name and description
Descriptive names improve tool selection accuracy

Group related functionality

Common Tool Types

Knowledge Base / Search Tools

Allow agents to search documentation, help articles, or knowledge repositories. Use when:

Answering product questions
Providing support information
Citing policies and procedures
Referencing documentation

Example configuration:

Tool: Knowledge Base Search

Description: Search our help center for articles about products, 
policies, and troubleshooting. Returns article title, summary, and 
full content.

Parameters:
- query (string): Search keywords
- category (optional): Filter by category (billing, technical, shipping)
- limit (optional): Number of results (default 5)

Authentication: API Key

Agent usage example:

User: "What's your return policy?"

Agent thinks: Need to search knowledge base for return policy

Agent action: Call Knowledge Base Search
- query: "return policy"
- category: "policies"

Tool returns: [Article: "Return & Refund Policy", content: "We accept..."]

Agent response: "According to our return policy, we accept..."

CRM / Customer Data Tools

Access customer information, order history, and account details. Use when:

Looking up customer accounts
Checking order status
Verifying customer history
Personalizing responses

Example configuration:

Tool: Get Customer Info

Description: Retrieve customer account details including contact info, 
order history, account status, and lifetime value. Use when customer 
provides email or customer ID.

Parameters:
- email (optional): Customer email
- customer_id (optional): Customer ID
- include_orders (boolean): Include order history (default true)

Authentication: OAuth 2.0 (Salesforce)

Agent usage example:

User: "I want to check my order status. My email is [email protected]"

Agent thinks: Need customer info and orders

Agent action: Call Get Customer Info
- email: "[email protected]"
- include_orders: true

Tool returns: {
  customer_id: "C12345",
  name: "John Smith",
  orders: [
    {order_id: "O789", status: "shipped", tracking: "TRK123"}
  ]
}

Agent response: "Hi John! I found your order O789. It shipped yesterday 
and is on its way. Tracking number: TRK123"

Action / Transaction Tools

Perform actions like processing refunds, creating tickets, or updating records. Use when:

Processing refunds
Creating support tickets
Updating account information
Taking automated actions

Example configuration:

Tool: Process Refund

Description: Process a refund for an order. Can only refund orders within 
30 days. Requires order number and refund amount. Returns confirmation 
number.

Parameters:
- order_number (string): Order number
- amount (number): Refund amount in dollars
- reason (string): Reason for refund
- notify_customer (boolean): Send email notification (default true)

Authentication: API Key

Rules:
- Only orders < 30 days old
- Refund amount <= original order amount
- Requires manager approval if amount > $500

Agent usage example:

User: "I want to return order #12345 and get my money back."

Agent thinks: Need to process a refund

Agent action: Call Process Refund
- order_number: "12345"
- amount: 49.99
- reason: "customer return request"
- notify_customer: true

Tool returns: {
  success: true,
  refund_id: "REF789",
  confirmation: "Refund processed, customer will receive $49.99 in 5-7 days"
}

Agent response: "I've processed your refund for order #12345. You'll 
receive $49.99 back to your original payment method within 5-7 business 
days. Your refund confirmation number is REF789."

Data Enrichment Tools

Enrich leads or customers with external data. Use when:

Qualifying leads
Researching companies
Enriching contact information
Gathering intelligence

Example configuration:

Tool: Company Lookup

Description: Get detailed company information including size, industry, 
funding, technology stack, and contact details. Use for lead qualification 
and research.

Parameters:
- domain (string): Company website domain
- fields (array): Which fields to return (default: all)

Authentication: API Key (Clearbit/ZoomInfo)

Returns:
- Company name
- Employee count
- Industry
- Annual revenue
- Tech stack
- Key contacts

Agent usage example:

User: "I work at acme-corp.com and I'm interested in your product."

Agent thinks: Should qualify this lead and enrich company data

Agent action: Call Company Lookup
- domain: "acme-corp.com"

Tool returns: {
  name: "Acme Corp",
  employees: 250,
  industry: "SaaS",
  revenue: "$25M",
  tech: ["Salesforce", "HubSpot"]
}

Agent response: "Great to meet you! I see Acme Corp is a SaaS company 
with about 250 employees. Based on your company profile, you'd be a 
great fit for our Enterprise plan. Let me ask a few questions to 
understand your specific needs..."

Tool Authentication

Different tools require different authentication methods:

API Key

Configuration
How to Get
Best Practices

Tool: Knowledge Base API
Auth Type: API Key

API Key: sk_1234567890abcdef
Header: X-API-Key (or Authorization: Bearer)

OAuth 2.0

Configuration
How It Works
Best Practices

Tool: Salesforce CRM
Auth Type: OAuth 2.0

Click "Connect to Salesforce"
→ Authenticate with your account
→ Grant permissions
→ Token automatically managed

Basic Auth

Configuration
Security

Tool: Legacy API
Auth Type: Basic Auth

Username: api_user
Password: ************

No Auth (Public APIs)

Configuration
Considerations

Tool: Public Data API
Auth Type: None

No credentials required

Using Secrets Manager

For sensitive credentials, use the Secrets Manager:

Create a Secret

Navigate to Account → Secrets ManagerClick Create Secret

Key: SALESFORCE_API_KEY
Value: sk_abc123xyz789

Reference in Tool

In tool configuration:

API Key: SECRET::SALESFORCE_API_KEY::

The secret is automatically resolved at runtime.

Benefits

✅ Centralized credential management
✅ Encrypted storage
✅ Audit logging
✅ Easy rotation (update once, applies everywhere)
✅ Role-based access control

Learn more in the Secrets Manager Guide

Tool Usage in Agent Instructions

Tell agents how and when to use tools in your instructions:

Explicit Tool Usage

## Tool Usage Guidelines

### Knowledge Base Search
Use this tool BEFORE answering any product or policy questions.
Always search with 2-3 relevant keywords.

Example: If customer asks "What's your shipping policy?", search for 
"shipping policy" in the knowledge base first.

### Customer Lookup
Use this tool whenever a customer provides their email or order number.
Look up their account before answering account-specific questions.

### Refund Processor
Only use this tool if:
1. Customer explicitly requests a refund
2. Order is within 30 days
3. Refund amount is under $500 (escalate higher amounts)
4. You've verified the customer's identity

### Support Ticket Creator
Use this tool when:
1. You cannot resolve the issue
2. Issue requires specialized knowledge (billing, technical)
3. Customer specifically requests to speak with someone
4. Issue is time-sensitive or complex

Tool Selection Examples

## Example Scenarios

**Customer asks: "Where is my order?"**
Ask for order number or email
Use Customer Lookup tool with provided information
Get order details and tracking
Provide status and tracking number

**Customer asks: "What's your return policy?"**
Use Knowledge Base Search for "return policy"
Read the article
Summarize policy for customer
Offer to help with a specific return if needed

**Customer says: "I want a refund for order #12345"**
Use Customer Lookup to get order details
Check order date (must be < 30 days)
Use Refund Processor if eligible
If not eligible, explain why and offer alternatives

Best Practices

Start with essential tools only

Begin with the minimum tools needed:Phase 1: Core functionality

Knowledge base search
Basic customer lookup

Phase 2: Add as needed

Order management
Refund processing

Phase 3: Advanced features

Data enrichment
Complex integrations

Don’t add tools “just in case” - each one adds complexity and cost.

Test tools independently first

Before giving tools to agents:

Test tool calls manually
Verify authentication works
Check response formats
Understand error cases
Know rate limits

Then add to agent and test integration.

Provide clear tool instructions

In your agent instructions:

✅ Good:
"Use the Order Lookup tool whenever a customer mentions an order 
number or asks about order status. Call it with the order_number 
parameter."

❌ Bad:
"Use tools as needed"

Specific instructions = correct tool usage.

Handle tool errors gracefully

Tools can fail. Prepare agents:

If a tool call fails:
1. Acknowledge the issue to the customer
2. Explain what you tried
3. Offer alternative solutions
4. Escalate if necessary

Example: "I tried to look up your order but encountered a system 
error. Let me create a support ticket for our team to investigate. 
They'll contact you within 2 hours."

Monitor tool usage

Track which tools are being used:

Which tools are called most?
Which tools are never used? (consider removing)
Are tools being used correctly?
Are error rates acceptable?

Optimize based on actual usage patterns.

Secure sensitive tools

For tools that perform actions (refunds, deletions, updates):

Add approval steps (Human-in-the-Loop)
Set monetary limits in tool configuration
Require additional verification
Log all actions
Monitor for suspicious activity

Example: Refunds over $200 require human approval.

Version and document tools

Maintain documentation:

What the tool does
When to use it
Parameters and their meanings
Expected responses
Error conditions
Usage examples

Good documentation = easier troubleshooting and onboarding.

Troubleshooting

Agent not using tools

Possible causes:

Tools not properly connected
Instructions don’t mention tools
Tool descriptions unclear
Agent hitting reasoning step limit

Solutions:

Check tool is connected and enabled
Add explicit tool usage instructions
Improve tool descriptions
Increase reasoning step limit
Test tool manually first

Agent using wrong tool

Possible causes:

Similar tool names/descriptions
Vague tool descriptions
Missing usage guidelines

Solutions:

Make tool names more distinct
Improve tool descriptions (be specific)
Add explicit usage guidelines in instructions
Remove similar/redundant tools
Provide examples in instructions

Tool authentication failing

Check:

Is API key correct?
Is OAuth token expired?
Are credentials stored in Secrets Manager?
Do credentials have required permissions?
Is the service API working?

Solutions:

Verify credentials are correct
Reconnect OAuth if expired
Check service status page
Verify permissions on service side
Test credentials outside of agent

Tool calls timing out

Possible causes:

External API is slow
Complex query
Rate limiting
Network issues

Solutions:

Increase timeout setting if available
Simplify query parameters
Check API rate limits
Add caching for common queries
Consider async processing for slow tools

Rate limit errors

When agent hits provider rate limits:Short term:

Reduce tool usage frequency
Add caching
Batch requests when possible

Long term:

Upgrade provider plan
Use multiple API keys (rotation)
Implement request queuing
Consider alternative providers

Next Steps

Custom MCP Servers

Build your own tool integrations

API Connections

Connect to external APIs

Prompt Engineering

Write better tool usage instructions

Best Practices

Optimize agent performance

Get Started

Flows

Agents

Account Management

Advanced

Tools & Connectors

Tools & Connectors

What are Tools?

Tool Types

MCP Servers (Model Context Protocol)

What is MCP?

API Integrations

Adding Tools to Agents

From the Agent Configuration

Tool Selection Best Practices

Common Tool Types

Knowledge Base / Search Tools

CRM / Customer Data Tools

Action / Transaction Tools

Data Enrichment Tools

Tool Authentication

API Key

OAuth 2.0

Basic Auth

No Auth (Public APIs)

Using Secrets Manager

Tool Usage in Agent Instructions

Explicit Tool Usage

Tool Selection Examples

Best Practices

Troubleshooting

Next Steps

Custom MCP Servers

API Connections

Prompt Engineering

Best Practices

Get Started

Flows

Agents

Account Management

Advanced

​Tools & Connectors

​What are Tools?

​Tool Types

​MCP Servers (Model Context Protocol)

What is MCP?

​API Integrations

​Adding Tools to Agents

​From the Agent Configuration

​Tool Selection Best Practices

​Common Tool Types

​Knowledge Base / Search Tools

​CRM / Customer Data Tools

​Action / Transaction Tools

​Data Enrichment Tools

​Tool Authentication

​API Key

​OAuth 2.0

​Basic Auth

​No Auth (Public APIs)

​Using Secrets Manager

​Tool Usage in Agent Instructions

​Explicit Tool Usage

​Tool Selection Examples

​Best Practices

​Troubleshooting

​Next Steps

Custom MCP Servers

API Connections

Prompt Engineering

Best Practices

Tools & Connectors

What are Tools?

Tool Types

MCP Servers (Model Context Protocol)

API Integrations

Adding Tools to Agents

From the Agent Configuration

Tool Selection Best Practices

Common Tool Types

Knowledge Base / Search Tools

CRM / Customer Data Tools

Action / Transaction Tools

Data Enrichment Tools

Tool Authentication

API Key

OAuth 2.0

Basic Auth

No Auth (Public APIs)

Using Secrets Manager

Tool Usage in Agent Instructions

Explicit Tool Usage

Tool Selection Examples

Best Practices

Troubleshooting

Next Steps