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

# Using tools

> Attach functions to Managed Topics actions to call APIs and perform logic when topics match.

Functions let your agent call APIs, look up data, or perform logic when a Managed Topic matches. This page shows how to add a function to a topic and test it.

## Adding a function

After creating and testing your function, integrate it into your agent's Managed Topics so it can be invoked during conversations.

You can add a function in three ways:

1. **Type `/`** in the Actions field of a Managed Topic card to open the function menu.
2. **Right-click** in the Actions field to access the function menu.
3. **Click the `+` icon** on the right side of the Actions field.

Each method lets you search for and select a function, or create a new one to populate later.

You can reuse the same function across multiple topics and actions.

<Warning>
  Function references like `{"{{fn:order_lookup}}"}` are only valid in the **Actions** field of a Managed Topic. Placing them in the **Content** field will not trigger the function, and no error is shown. Always add function references in Actions.
</Warning>

The `{"{{fn:...}}"}` syntax references **global functions**, which can be used across topics, flows, and rules. This is different from **transition functions** (`{"{{ft:...}}"}` syntax), which are scoped to a single flow. See [Transition functions](/flows/transition-functions) for details.

## Best practices

Function invocation requires testing and iteration. Here is a recommended prompting pattern for the Actions field:

```plaintext theme={"theme":{"light":"github-light","dark":"github-dark"}}
When the user asks "where is my order," do not respond until you have called {{fn:order_lookup}} with an order number. If you don't have the order number, ask for it first, then call {{fn:order_lookup}}. Use the function's response to answer the caller.
```

The agent will always invoke the function before responding, and ground its answer in the function's output.

To control what the agent says or does after a function runs, use [return values](/tools/return-values). For example, you can return an exact `utterance` for the agent to speak, trigger a `handoff`, or end the call with `hangup`.

## Testing

<Steps>
  <Step title="Save your agent">
    Save your agent and click **Play** in the header to open the test chat panel.
  </Step>

  <Step title="Test the invocation">
    Ask a test question like "Where is my order?" and observe how the agent handles the interaction.
  </Step>

  <Step title="Verify tool calls">
    In the test chat panel, enable the **tool calls** toggle in settings to inspect which functions were called and what parameters were passed. This is useful for confirming whether the function was actually triggered and whether the correct arguments were sent – especially when the agent is not behaving as expected.
  </Step>
</Steps>

## Related pages

<CardGroup cols={3}>
  <Card title="Create a function" icon="plus" href="/tools/how-to-setup">
    Set up a function with naming conventions, parameters, and Python code.
  </Card>

  <Card title="Return values" icon="reply" href="/tools/return-values">
    Control agent behavior with function return types.
  </Card>

  <Card title="Managed Topics actions" icon="bolt" href="/managed-topics/how-to-setup-action/introduction">
    Configure actions that trigger alongside topic responses.
  </Card>
</CardGroup>