Tool maintenance

Documentation Index

Fetch the complete documentation index at: https://docs.poly.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Quick reference

​

Updating tool code

1. Go to Build > Tools and select the tool
2. Edit the Python function in the Function Editor
3. Save, then test in Agent Chat
4. Review logs in Conversation Review → Diagnosis
5. Publish when satisfied

​

Example: updating an API endpoint

def book_reservation(date, time, party_size, special_requests=None):
    conv.log.info(f"Booking for {party_size} guests on {date} at {time}")

    response = requests.post(
        "https://api.example.com/v2/bookings",
        json={"date": date, "time": time, "guests": party_size,
              "special_requests": special_requests or ""},
        headers={"Authorization": f"Bearer {conv.utils.get_secret('booking_api_key')}"}
    )

    if response.status_code == 200:
        conv.log.info("Booking successful")
        return {"utterance": "Your reservation is confirmed."}
    else:
        conv.log.error(f"Booking failed: {response.text}")
        return {"utterance": "I'm having trouble completing your reservation. Let me transfer you to someone who can help."}

​

Debugging

​

Using conv.log

conv.log.info("Starting payment processing")       # general flow
conv.log.warning("Customer account has low balance") # potential issues
conv.log.error(f"Payment API returned: {error}")     # failures
conv.log.info("Processing order", pii=True)          # sensitive data

​

Common debugging steps

1. Review Diagnosis logs for the failing tool
2. Reproduce the issue in Agent Chat
3. Check tool inputs – are parameters being passed correctly?
4. Validate external APIs directly (Postman, curl)
5. Review the tool description – is it clear when the tool should trigger?

​

Common errors

​

Managing secrets

1. Go to the Secrets tab on the workspace homepage
2. Find and edit the secret
3. Save, then test all tools using it

api_key = conv.utils.get_secret("my_api_key")
headers = {"Authorization": f"Bearer {api_key}"}

• Rotate credentials every 90 days
• Use descriptive names (stripe_live_api_key, not key1)
• Test all dependent tools after rotation

​

Managing API integrations

• Sandbox – test/staging endpoints
• Pre-release – UAT endpoints
• Live – production endpoints

​

Optimizing performance

1. Add delay controls with filler phrases (“Let me check that for you.”)
2. Cache frequently-accessed data
3. Reduce unnecessary API calls
4. Simplify logic and remove unnecessary processing

​

Improving tool triggering

1. Simplify the description – make it clear when to call the tool
2. Update KB actions – ensure topics reference the tool correctly
3. Check for conflicts – ensure other tools aren’t being called instead

​

Related pages

• Tools overview – tool capabilities
• Secrets – credential management
• conv.log reference – structured logging
• Delay controls – managing latency
• Test sets – automated regression testing to verify tool changes
• Alerts API – automated alerts for tool errors, latency, and API failures