# Tools Often you don't want your agent to have every tool of a connector. For instance, your support agent needs to read issues, not search all your code. This page is about the tools that connectors bring. Your own functions are in [Tool calling and dispatch](https://getstream.io/agents/docs/tool-calling-and-dispatch/). ## See a connection's tools ```sh getstream agents connections tools company ``` ```text TOOL READS ONLY NEEDS SCOPES actions_get yes actions_list yes actions_run_trigger no add_comment_to_pending_review no add_issue_comment no add_reply_to_pull_request_comment no assign_copilot_to_issue no create_branch no create_or_update_file no create_pull_request no ... ``` The CLI validates the connection first, so the list is what the provider offers now. Each row is one tool: READS ONLY is `yes` for a tool the connector marks as read-only, and NEEDS SCOPES names the scopes a call of the tool needs. Here it is empty for every tool. The output is cut to ten rows. A connection that needs a reconnect, new scopes or an approval prints why and fails: ```text Error: connection company: The provider rejected the stored token or key; replace it with PUT /v1/agents/connections/{id}/credentials ``` To replace the token or key, save it again as in [Save the token](https://getstream.io/agents/docs/connectors/shared-account/#save-the-token). The command takes only an app connection, by its label or its id. In the Dashboard: 1. **Open the connection** In the [Stream Dashboard](https://getstream.io/signin/), go to **Agents > Library > Connectors**, open the connector, then click the connection in its list. 2. **Validate it** Click **Validate**. The **Tools** section lists each tool with its description and **Needs scopes**, under the time it was listed. Until the first validate, it says "Validate the connection to list the tools it offers." ## See what the agent gets ```sh getstream agents tools support ``` ```text CONNECTOR NAME ACCOUNT GRANT REQUIRED SANDBOX github github App connection company All tools no no ``` It shows each connector as stored now: as last synced, plus any change saved in the Dashboard since. GRANT reads `All tools` when every tool is offered, and otherwise the tool names or patterns as written in `agent.yaml`. ACCOUNT reads `Each user's own` for a connector with no `connection`. In the Dashboard, open the agent and go to its **Tools** tab. Each row under **Connectors** shows the same: whose account, such as `App connection company`, and the grant, such as `All tools` or `Tools matching list_issues, get_*`. ## Offer only some tools `tools` names the tools to offer, or a pattern such as `get_*`: ```yaml title="agents/support/agent.yaml" name: support mode: text llm: llm-fast connectors: - name: github connection: company tools: [list_issues, get_*] # list_issues, and every tool whose name starts with get_ ``` Sync the agent, then check the new grant: ```sh getstream agents sync support getstream agents tools support ``` ```text CONNECTOR NAME ACCOUNT GRANT REQUIRED SANDBOX github github App connection company list_issues, get_* no no ``` Leave `tools` out to offer every tool. The agent then stores the pattern `*`, which is what the Dashboard shows as "All tools". In the Dashboard: 1. **Edit the connector** Open the agent's **Tools** tab and click **Edit** on the connector, or **Add connector** for a new one. 2. **Pick the tools** Under **Grant**, pick **Chosen tools** and check each tool to offer. Or pick **Patterns** and type names or patterns, such as `get_*`. `*` is every tool. 3. **Save** Click **Done**, or **Add connector** for a new one. Then click **Save** on the agent. ## Give a connector another name The model sees each tool as `__`. Set `connector` when that name should differ from the connector id: ```yaml connectors: - name: code # the model sees code__list_issues connector: github connection: company ``` In the Dashboard, it is the **Name** field of **Edit**. The NAME column of `getstream agents tools support` shows it. ## Require a connector By default a connector is optional: when its connection is missing or not connected, the session goes on without its tools. `required: true` refuses to open the session instead: ```yaml connectors: - name: github connection: company required: true ``` A test with a connection that is not connected yet stops before the conversation: ```sh getstream agents test support ``` ```text Error: cannot start a conversation with support: session: required connector "github" cannot be used: not_connected: the connection is not connected ``` In the Dashboard, it is the **Required** checkbox of **Edit**. The REQUIRED column of `getstream agents tools support` shows `yes`. ## Where to manage connectors > > **Warning:** If `agent.yaml` has a `connectors` key, add and remove connectors only there, because every sync replaces the whole list with it. > If `agent.yaml` has no `connectors` key, manage them in the Dashboard. When someone changed the connectors in the Dashboard since your last sync, `getstream agents sync` stops and shows the change. Copy the change into `agent.yaml` and sync again, or sync with `--overwrite` to replace it. ## agent.yaml keys Each entry under `connectors` takes these keys: | Key | What it sets | Default | | ------------ | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | `name` | The name the model sees each tool under, as `__` | Required | | `connector` | The connector id, such as `linear` or `custom_wiki` | `name` | | `connection` | The app connection to use, by its label or its id. See [App connection](https://getstream.io/agents/docs/connectors/shared-account/) | Each user's own account | | `tools` | Tool names or patterns to offer. See [Offer only some tools](#offer-only-some-tools) | Every tool | | `required` | `true` refuses a session whose connection is missing or not connected | Optional: the session goes on without it | | `sandbox` | `true` lets code in the agent's sandbox call the connector's API. See [Sandbox](https://getstream.io/agents/docs/connectors/sandbox/) | No access | A name alone, such as `- linear`, is the same as `name: linear`. When the agent syncs, a connector whose `connection` the app doesn't have is left out with a warning, and the rest of the agent syncs. With `required: true`, the sync fails instead. Leaving `connectors` out of `agent.yaml` keeps what is already stored, and an empty list removes it. ## Going further - [Connectors](https://getstream.io/agents/docs/connectors/): What a connector is, a quickstart, and whose account it uses. - [App connection](https://getstream.io/agents/docs/connectors/shared-account/): One account the app owns, for every conversation. - [Custom MCP servers](https://getstream.io/agents/docs/connectors/mcp/): Any MCP server: a public one, or one behind a key. - [Tool calling and dispatch](https://getstream.io/agents/docs/tool-calling-and-dispatch/): Your own functions, run in your process. - [Troubleshooting](https://getstream.io/agents/docs/connectors/troubleshooting/): Errors you may see, why, and what to do. --- For the most recent version of this documentation, visit [https://getstream.io/agents/docs/connectors/choosing-tools/](https://getstream.io/agents/docs/connectors/choosing-tools/).