> ## 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.

# Tool maintenance

> Update tool code (Python functions), debug errors using logs, manage credentials, and fix integration issues.

Update tool code, debug errors using `conv.log`, rotate API credentials, and fix integration issues without taking the agent offline.

## Quick reference

| I need to...            | Action                                                         |
| ----------------------- | -------------------------------------------------------------- |
| Update tool code        | Edit in Function Editor → Save → Test in Agent Chat            |
| Debug a tool error      | **Analytics > Conversations > Voice** → Diagnosis → check logs |
| Update API credentials  | Workspace homepage > Secrets tab → Edit → Save                 |
| Add logging             | Use `conv.log.info()` in code                                  |
| Fix tool not triggering | Review KB action or rules → clarify description                |
| Update API integration  | **Configure > APIs** → edit endpoint                           |

## 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

<Tip>Always test tool changes in Sandbox before promoting to Live.</Tip>

### Example: updating an API endpoint

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```

Logs appear in **Conversation Review → Diagnosis**, **Agent Chat** (during testing), and the [Conversations API](/api-reference/conversations/introduction).

### 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

| Error               | Likely cause                     | Fix                                                       |
| ------------------- | -------------------------------- | --------------------------------------------------------- |
| Tool not triggering | Unclear description or KB action | Simplify description; clarify when to call it             |
| Wrong parameters    | LLM misunderstanding             | Improve parameter names and descriptions                  |
| Timeout             | Slow API or complex logic        | Add [delay controls](/tools/delay-control); optimize code |
| Auth failures       | Expired credentials              | Update [secrets](/secrets/introduction)                   |
| Import errors       | Missing library                  | Check [available libraries](/tools/import-library)        |

## Managing secrets

When API keys or credentials change:

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

Configure per-environment endpoints in **Configure > APIs**:

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

You won't call production APIs during testing.

## Optimizing performance

If tools are slow:

1. Add [delay controls](/tools/delay-control) 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

<Tip>You can reference state variables in delay responses using `$`. For example: `Still checking availability at $branch_name...`</Tip>

## Improving tool triggering

If the agent isn't calling your tool when expected:

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

**Bad description:** "Handles reservations"

**Good description:** "Call this tool when the user wants to book a table. Required: date, time, party\_size. Only call after confirming all three with the user."

## Related pages

* [Tools overview](/tools/introduction) – tool capabilities
* [Secrets](/secrets/introduction) – credential management
* [conv.log reference](/tools/classes/conv-log) – structured logging
* [Delay controls](/tools/delay-control) – managing latency
* [Test sets](/analytics/test-suite/introduction) – automated regression testing to verify tool changes
* [Alerts API](/api-reference/alerts/introduction) – automated alerts for tool errors, latency, and API failures