> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/guides-and-quickstarts/agent-builder-and-skills/give-an-agent-tools.md).

# Give an agent tools

Tools let an agent perform actions, such as finding a file or updating a record in another application. Configure the action and its inputs, then tell the agent when to use it.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FI8Qw17BPz60mGQTpWW9n%2FG014.mp4?alt=media&token=bd21bc90-635e-46d6-921a-b894e5e7fcb9>" %}

## Describe the task

In the agent’s instructions, describe when it should use a tool and what result it should return.

![Agent instructions describing tool use](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/zpMURZlyoIMd5yZbOzpe/assets/g014-g014-01-instructions.png)

## Add an action

Select **Add Tools**. Search for the provider you need and choose an action.

![Tool library provider and action selection](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/80OYNOlyoCVZ1nLoCugC/assets/g014-g014-02-tool-library.png)

Open the tool configuration. Select an authorized connection and review the required inputs. If no suitable connection is available, follow the provider’s setup instructions in the [Provider Catalog](https://docs.stackai.com/integrations/catalog.md), then return to this tool.

![Tool connection and required inputs](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/STbwRzgQuSMqV8wE68Ql/assets/g014-g014-03-tool-inputs.png)

## Set the inputs

Choose **AI auto-fill** when the agent should obtain a value from the user’s request, such as search terms. Choose **Set manually** for values that must stay fixed, such as the destination selected by the builder. Review each required field; adding the tool alone does not supply its inputs.

![AI auto-fill and manual input modes](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/lJKxDXfyGlt73CIbD5hZ/assets/g014-g014-04-input-modes.png)

## Check the response

Send a request that requires the tool. Compare the agent’s answer with the tool result.

![Agent answer and expanded tool result](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/uleJ9xQk6HGFQr3WXHRt/assets/g014-g014-05-expanded-result.png)

If the tool finds no matching records, the agent should explain that result. It should not invent a record or link.

![Tool response when no matching record is found](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/foGjygZ9aR41u4HADO41/assets/g014-g014-06-no-match.png)

## Important behavior

The connected account must have permission to perform the action. Resolve missing connections and required inputs in the tool configuration.

An action that changes data can affect the external application when the agent uses it. Choose the operation and inputs accordingly.

## Work with uploaded files

An interface attachment needs the correct input mapping and references in the agent’s Prompt. For the file-processing setup, enable **File Access** and add **Terminal** from **StackAI Computer**. The current builder can offer **Enable File Access for better file handling** after inserting a file reference; check the resulting setting and tool.

Follow [Let an agent work with uploaded files](https://docs.stackai.com/guides-and-quickstarts/interfaces-and-end-user-experiences/let-an-agent-work-with-uploaded-files.md) to test a real interface upload, a grounded answer, and a generated download. Use [Troubleshoot uploaded files and downloads](https://docs.stackai.com/guides-and-quickstarts/interfaces-and-end-user-experiences/let-an-agent-work-with-uploaded-files/troubleshoot-uploaded-files-and-downloads.md) if any part of that path fails.

## Continue testing

If the tool does not run or returns an error, use [Configure and test an action](https://docs.stackai.com/guides-and-quickstarts/using-tools-and-actions/configure-and-test-an-action.md) to check the connection and required inputs. After the tool behaves as expected, use [Agent appearance and security](https://docs.stackai.com/guides-and-quickstarts/agent-builder-and-skills/agent-appearance-and-security.md) to publish the agent for its intended users.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/guides-and-quickstarts/agent-builder-and-skills/give-an-agent-tools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
