Agent tools

gritz adds an MCP server named gritz to every agent it runs, alongside the MCP servers in the task’s workspace. Its tools let the agent read and update its own task, and nothing else: they work with a token that only grants access to that task (see Task tokens).

What agents are told

On a task’s first run, before your instructions, gritz tells the agent to:

• name the task with update_my_task if it has no name;
• create a link with subscribe=true for each resource it creates, such as a pull request, an issue or a comment, so replies reach the task even after it finishes, and subscribe=false for reference links it didn’t create;
• prefer URLs a person can open over API URLs;
• use report for anything you should see, since its text replies aren’t shown;
• answer questions or problems on the platform the latest instruction or event came from, such as the pull request, and say which task it is from;
• call get_my_task if it needs to check for updates mid-run.

Then it gives the agent the task: its instructions, events and links, so it doesn’t need a tool call to start. On later runs the agent gets only what is new. See Instructions and runs.

Tools

get_my_task

Returns the task: its ID, name, status, workspace, namespace and URL, its links, and its instructions and events in order. Reports and status changes aren’t included.

update_my_task

Renames the task. It takes name, the new name. Agents can’t change anything else about their task, including its auto-archive delay.

create_link

Links the task to an external resource, and appears on the task’s timeline and in its sidebar.

Parameter
url	The resource’s URL.
relevance	How the resource relates to the task, such as “PR implementing the fix”.
title	Optional. A title to show for the link.
subscribe	Optional. true to have events about the resource delivered to the task.

A subscribed link is how a task hears about review comments on its pull request, or replies on its Jira issue. Which events wake it is up to the organisation’s routing rules. See Events and links.

report

Posts message to the task’s timeline. This is how an agent tells you what it did, what it found or what is blocking it: the agent’s own replies only appear in the task’s log.

get_github_token

Meant to return a short-lived GitHub token for the organisation’s GitHub App installation. Only tasks whose workspace has the github_token capability get this tool, and the server doesn’t issue these tokens yet, so the tool always fails.

Agents get GitHub access today from their workspace instead: a token under secrets:, such as GH_TOKEN, which gh, git and the GitHub MCP server can use. See secrets.

Writing instructions that use them

The agent already uses these tools as above without being asked. Mention them when you want something specific:

• To get a summary where you’ll see it: “When you’re done, report a summary of the changes and anything you couldn’t do.”
• To keep a task listening: “Open a draft pull request and link it with subscribe=true.” The task finishes, and a review comment on the pull request wakes it if a routing rule matches.
• To link context you gave it: “Link the incident page as a reference, not subscribed.”
• To name it predictably: “Name this task deps: bump <package>.”

The agent’s other tools, such as for GitHub or Jira, come from the MCP servers and credentials in its workspace. Ask your operator what a workspace provides, or see workspaces.yaml.