> ## 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.
# Invoke tool
> Invoke a tool (Python function) from a managed-topic action to extend your agent with custom logic.
Add tools to actions to extend your agent's capabilities with custom logic – look up data, call APIs, or perform calculations during a conversation.
Tools are Python `function`s – "tool" and "function" refer to the same feature, and the `{"{{fn:…}}"}` reference syntax below keeps the `fn:` prefix for backward compatibility.
## Actions vs Content
Tools only run when referenced from the **Actions** field. Content is what the agent says; Actions are what the agent does next. If you come from an intent-based background, the mental model is:
| Field | Equivalent | Visible to retriever |
| ------- | --------------------- | -------------------- |
| Content | `say` function | Yes |
| Actions | `transition` function | No |
Putting `{"{{fn:...}}"}` in Content will not call the tool and produces no error – the reference is treated as plain text.
## Adding a tool
Add a tool to the **Actions** field of a managed topic in three ways:
1. Type `/` in the Actions field
2. Right-click in the Actions field
3. Click the **+** icon on the right side of the field
Select a tool from the menu, or create a new one to populate later. You can reuse the same tool across multiple topics and actions.
Tool references like `{"{{fn:order_lookup}}"}` are **only valid in the Actions field**. Placing them in the Content field will not trigger the tool, and no error is shown. Always add tool references in Actions.
Iterative testing helps get your agent to call tools as expected.
## `{"{{fn:...}}"}` vs `{"{{ft:...}}"}` syntax
The `{"{{fn:...}}"}` syntax references **global tools** (also called global functions), which can be used across topics, flows, and rules. This is different from **[transition functions](/flows/transition-functions)** (`{"{{ft:...}}"}` syntax), which are scoped to a single flow.
## Known limitation: tools in flows
When a tool is referenced inside a flow action, it may not be included in the LLM's tool definitions. This means the LLM cannot see or call the tool. If you encounter this, add the tool reference to the [Behavior](/agent-settings/rules) section so the LLM is aware of it.
If your topic detours through a flow and needs to return to the original topic afterwards, see [Returning to the topic after a flow](/managed-topics/introduction#returning-to-the-topic-after-a-flow) for the state-preservation pattern (storing the originating topic in `conv.state` and using the flow's exit function to direct the LLM back).
## Example prompt
Use this pattern in the **Actions** field to ensure the agent calls a tool before responding:
```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 tool's response to answer the caller.
```
The agent will always invoke the tool before responding, and ground its answer in the tool's output.
The reason this pattern is reliable: it splits the speaking turn from the tool-calling turn. Telling the agent to both say something and call a tool in the same turn is a known [anti-pattern](/managed-topics/introduction#common-anti-patterns) – the agent typically does one or the other, but not both consistently.
## Controlling agent behavior after a tool call
Tools can return values that control what the agent says or does next – for example, returning an exact `utterance` for the agent to speak, triggering a `handoff`, or ending the call with `hangup`.
See [Return values](/tools/return-values) for the full reference.
## Testing
Save your agent and click **Play** in the header to open the test chat panel.
Ask a test question like "Where is my order?" and observe how the agent handles the interaction.
Enable the **Tool calls** toggle in the test panel settings to inspect which tools were called and what parameters were passed. Use this to confirm the tool was actually triggered and that the correct arguments were sent – especially when the agent is not behaving as expected.
## Related pages
Trigger SMS messages from Managed Topic actions.
Transfer callers to live agents from topics.
Set up a new tool with parameters and Python code.
Control agent behavior with tool return values.