4. Filter Tools
Until now, the agent read only the diff of a public pull request. In this chapter, the agent reads the code around the change, works on your own repositories, and posts its review as a comment.
An agent with no tool fields gets every tool: all system tools, and every tool of every Integration Connection in the project. In this chapter, you connect GitHub and then filter the tools down to the ones the agent needs.
An agent gets three kinds of access:
- System tools come with Autoheal. Examples: a to-do list, a question to the user, and creating an artifact.
- Integration tools come from the project's Integration Connections, for example
github_list_repositoriesorslack_send_message. - The shell (
bash) runs in an isolated sandbox for each run. When the project has a GitHub Integration Connection, Autoheal signs inghandgitin the sandbox with that connection. The agent does most of its GitHub work with these commands.
Step 1: Let the agent read the repository
A diff shows only the lines that changed. To find more, the agent must read the code around those lines. Replace the content of instructions.md with this:
You review one pull request on GitHub.
1. The prompt has the pull request URL. Clone the repository with the `git_clone` tool. Give it the repository's https URL and the ref `pull/<number>/head`.
2. In the clone, compare the pull request with the default branch: `git diff origin/HEAD...HEAD`.
3. Read the changed files in full, not only the diff.
4. Write a verdict: merge, merge with changes, or do not merge.
5. Name the riskiest change, with its file and line.
6. Ask the author one question.
Look hardest at the `focus` input. For `correctness`, look for bugs and errors that the code does not handle. For `security`, look for secrets, unsafe input and permissions. For `tests`, say what the tests do not cover.
If the `post_comment` input is true, post the review as one comment on the pull request with `gh pr comment <URL> --body-file <file>`. If it is false, do not comment.
Do not push, approve, merge or close anything.
In agent.yaml, add this input below focus:
post_comment:
type: boolean
description: Post the review as a comment on the pull request.
default: false
Commit, and run the agent with the pull request URL from the Quick Start. You do not need an Integration Connection for this step, because the repository is public.
In the transcript, find the git_clone call. It returns the folder of the clone, and the agent then reads the files there with git and cat in its shell. Use git_clone for every clone, not git clone in the shell: the tool gives each run its own fast copy. Check that each finding now has a line number, for example recommendation_server.py:121. The agent can also talk about code that is not in the diff, because it has the full files.
Before you connect GitHub
For steps 2 to 4, you need these:
- A GitHub repository where you can open a pull request. If you do not have one, open autohealai/astronomy-shop-template and click Use this template to make your own copy.
- The Project Admin role, to connect GitHub. If you are a Member, ask a Project Admin to do step 2.
Step 2: Connect GitHub
Go to Settings → Integrations, select GitHub, and click Install GitHub. See GitHub for the steps.
The GitHub App or token that you connect decides what gh and git can do in the sandbox. For step 4, it must have write access to pull requests in your repository, because the agent posts a comment. If your agents must never write to GitHub, connect GitHub with a fine-grained token that has read-only permissions, and stop after step 3.
Step 3: Limit the agent's tools
Add these fields to agent.yaml:
system_tools: operation_type == "read"
integration_tools: integration_type == "github" && operation_type == "read"
Each field is a filter. A tool that matches the filter is available to the agent. A filter can use three fields of a tool:
| Field | Example values |
|---|---|
name | github_list_repositories, slack_send_message |
operation_type | read, write |
integration_type | github, grafana, slack |
The filters above remove write tools, such as github_create_issue, from the agent. They do not limit the shell. In step 4, the agent posts a comment with gh in its shell, although both filters allow only read tools. With the connection's credentials, gh and git can also edit releases and push. Tell the agent in its instructions what it must never change, as in step 1. To make sure that it cannot write, connect GitHub with read-only permissions.
Commit your changes.
Step 4: Review your own pull request
- Open a pull request
In your repository, change one file on a new branch and open a pull request. Copy its URL.
- Run the agent
On the agent's Overview tab, paste the pull request URL, turn on the post_comment switch, and click Start run.
- Read the comment
When the run ends, open the pull request in GitHub. Check that it has a new comment with the review. The author of the comment is the GitHub App or the user of the token that you connected.
Turn on post_comment only for pull requests in your own repositories.
What to know
- If you leave out
integration_tools, the agent gets every tool of every Integration Connection in the project. Writeintegration_tools: "false"to give it no integration tools. Start with a narrow filter. - To allow one write tool, add it by name:
operation_type == "read" || name == "slack_send_message". - The shell is always available. A filter cannot remove it, and it can use every CLI that Autoheal signs in for the project's Integration Connections. See The shell is not limited by tool filters.
- Agent policies can make a person approve a tool call before it runs. A shell command waits for approval only when it runs a CLI that an Integration Connection signs in, such as
ghorgit. A command such ascurlnever waits. - Tools and the shell read the source system during the run. Autoheal does not copy your GitHub or ServiceNow data to answer a question.
- Every run in the project can use the project's Integration Connections. To use one connection in more than one project, share it.
Bring your own tools
You can connect any MCP server with the Custom MCP Server integration, for example an internal knowledge service. Agents in the project can then call its tools.
From the CLI
autoheal agents tools pr-review
autoheal run pr-review "<pull request URL>" --arg post_comment=true --follow
The first command lists the tools that the agent gets with its current filters.
See Tools and integrations in the reference, and Using gh and git in agent sandboxes.