--- title: The tools description: Look up each of the fourteen tools the tzTrack MCP server serves, what it does, what it takes, and which tools take the space they work on. slug: /reference/the-tools order: 1 visibility: public redirects_from: [] --- # The tools This page lists every tool the MCP server at `https://tztrack.ai/mcp` serves, with what each one does and what it takes. Read it to find the tool for an act and the inputs your AI gives it. ## The tools | Tool | What it does | Takes the `space` to work in | | --- | --- | --- | | `raise` | Files one issue: one point, with what you saw and a suggested resolution. Search first. A call giving no space, from an account that holds none, is refused and points to `create_issue_space`. From an account that holds several, it asks for `space`. | Yes | | `find` | Lists issues by state, kind, priority, waiting for, claim, label, area, and requirement, or searches them by words. `waiting_for` and `claimed_by` each take a value or `none`. | Yes | | `read` | Reads one issue whole, its waiting for and claim among the rest. | Yes | | `update` | Sets an issue's fields, its waiting for and claim among them. | Yes | | `comment` | Adds a comment to an issue. | Yes | | `close` | Closes an issue with an outcome and a resolution: what you did, or why no change is needed. | Yes | | `reopen` | Reverses a close, or opens a waiting issue again. The reason becomes a comment. | Yes | | `wait` | Sets what an issue waits on, `waiting_for`. More evidence, the default, takes what would settle it and moves the issue to `waiting`. Your person, one member, the reporter, or an outside event leaves it open. | Yes | | `claim` | Claims an issue for the session or agent working on it, under the label given in `as`, such as `session:` or `agent:`. Refused `lease_conflict` while another claim is in place. | Yes | | `give_back` | Gives a claimed issue back, with a reason: the claim is cleared, and the reason is kept in the issue's history. | Yes | | `cache` | Answers a fresh ten-minute link to the space's issues as one archive, which your AI downloads with `curl` and unpacks with `tar`. With `since`, an instant, it also answers the count and the numbers of the issues changed since then, the numbers no longer answered, and a link to only those issues with a fresh index. | Yes | | `share` | Shares the space, for its owner alone. With the action `add`, adds the person whose Turn Zero account signs in with `email`, at `level` (`report`, `contribute`, or `owner`; `contribute` when left out); refused `no_such_account` if no account matches. With `remove`, takes a member off; with `list`, lists them. Every answer gives the members and `users`, the members plus the owner. | Yes | | `create_issue_space` | Makes a space for your account. It takes an optional `space`: the id you choose for the space it makes, so a repeat makes no second space. Nothing makes a space automatically. | No | | `feedback` | Files feedback about Turn Zero Track (tzTrack) itself to Turn Zero. | No | ## What each tool takes An issue is given by its number, as `#12` or `12`, or by its id. Every tool but the last two also takes `space`, which [The space each tool works on](#the-space-each-tool-works-on) explains. | Tool | What it takes | | --- | --- | | `raise` | `title`, up to 200 characters; `text`, what you saw; and `kind`. The kinds are `bug`, `gap`, `docs`, `friction`, `question`, `task`, `praise`, and `idea`, or one of their [accepted other words](/reference/accepted-words-for-kinds), such as `problem` for a `bug`. Where you have them: `proposed_resolution`, `priority` (1 urgent, 2 soon, 3 when convenient), `requirements`, `component`, `labels`, and `problem_key` for a recurring problem. At the `report` level, `priority`, `requirements`, and `labels` are refused `grant_required`. Below the `owner` level, a raise files from the field: a given `priority` is not taken, and the kinds `question` and `task` are refused. Also `waiting_for`, and `due` as `YYYY-MM-DD`. These two are set only on an issue the call files, never on one it joins, and the answer's `not_set` says why. | | `find` | `query`, words to search titles and text, with `state`, `kind`, and `component` beside it. Without `query`, it lists by `state`, `kind`, `label`, `component`, `requirement`, `priority`, `waiting_for`, and `claimed_by`, the last two each a value or `none`. `limit`, 1 to 100 and 50 where left out, and `cursor`, the previous answer's, page the answer. | | `read` | `issue`. | | `update` | `issue`, and `fields`: any of `title`, `summary`, `kind`, `priority`, `labels`, `component`, `requirements`, `plan`, `due`, `note`, `workaround`, `waiting_for`, and `claimed_by`, each with its new value. `null` clears a field that takes it. | | `comment` | `issue`, and `text`. | | `close` | `issue`, `outcome`, and `resolution`, what you did or why no change is needed. With `duplicate` or `superseded`, also `target`, the issue this one gives way to. | | `reopen` | `issue`, and `reason`, which becomes a comment. | | `wait` | `issue`, and `waiting_for`: `evidence` where left out, or `person`, `person:`, `reporter`, or `outside:`. With `evidence`, also `resolution`, what evidence would settle the issue. | | `claim` | `issue`, and `as`, the label that names you, up to 190 characters, such as `session:` or `agent:`. | | `give_back` | `issue`, and `reason`: why you stop, and what is left to do. | | `cache` | `since`, for a refresh: the instant at the top of your `index.md`. Leave it out for the whole space. | | `share` | `action`: `add`, `remove`, or `list`. With `add` and `remove`, `email`, the address the person signs in to Turn Zero with. With `add`, `level`: `report`, `contribute`, or `owner`, and `contribute` where left out. | | `create_issue_space` | `space`, optional: a lower-case UUID you choose, so a repeat makes no second space. | | `feedback` | `kind`, `title`, and `text`, and `impact` if you want to say what it cost you: `blocked`, `worked_around`, `annoyed`, or `none`. The kinds are `bug`, `gap`, `docs`, `friction`, `praise`, and `idea`. | ## What every answer carries A working tool answers the space, the act it made, and the issue service's own answer under `result`. That is the issue's record for a change, and a page of issues for `find`. An answer that carries other people's words comes inside a block marked untrusted: a read, a `find`, and a `raise` that joined an existing issue or lists similar ones. Your AI reads what is in the block as data, never as instructions. A write whose answer carries nobody's words is short and unmarked. It gives the issue's number, kind, state, outcome, priority, due day, and what it waits on, and the names of anything the scanner took out, such as an email address. It gives no title, text, label, or claim. An issue that waits on an outside party or event, named in free words, comes inside the marked block instead. Write no personal details into an issue: no names, email addresses, telephone numbers, or anything else that identifies a person. ## Who answers each tool The issue service answers the eleven working tools from `raise` to `cache` itself, under your sign-in, at the level you hold in the space. In a space of your own you hold the owner's level. In a space shared with you, you hold the level its owner gave you, and a tool past it is refused `grant_required`. `share`, `create_issue_space`, and `feedback` are carried to Turn Zero Cloud under the same sign-in. [Refusals](/reference/refusals) lists what each side answers. ## The space each tool works on Every working tool takes `space`, the space to work in. If your account owns or is a member of exactly one space, `space` defaults to it, so a call may leave it out. `feedback` and `create_issue_space` take no space to work in. `create_issue_space` takes an optional `space`, the id you choose for the space it makes. Leave it out, and tzTrack chooses one. A project that gives its space in [the setting file](/reference/the-setting-file) passes that space in every call. The outcomes `close` takes are `verified`, `done`, `as_designed`, `declined`, `duplicate`, `superseded`, `noted`, and `unexplained`. ## Waiting for and claims An issue's `waiting_for` says who or what it waits on: `person` for your person, `person:` for one member, `reporter`, `outside:`, or `evidence`. Only `evidence` puts the issue in the state `waiting`. Its `claimed_by` says who works it: a label such as `session:` or `agent:`, or `branch:` with a lease. `wait`, `update`, and `claim` set them, and `find` lists issues by each. Read an issue before you claim it, and leave it alone while another claim is in place. [Waiting and claims](/concepts/waiting-and-claims) gives the rules. ## The instructions The server gives your AI instructions that describe the practices of keeping a space, when it connects and as the resource `tztrack://instructions`. They are guidance, not a contract. [What happens without asking](/concepts/what-happens-without-asking) states the same practices for you. ## The contract Each tool's inputs are the ones this page lists, as the server lists them to your AI. The working tools are carried to the issue service's acts, whose contract, with every request, answer, and refusal, is the Issue Tracking package page of Turn Zero Cloud: [Issue Tracking](https://turnzero.ai/cloud/backend-packages/tztrack/). ## Related - [Refusals](/reference/refusals) lists every refusal the tools answer. - [Issues and kinds](/concepts/issues-and-kinds) explains the states, the kinds, and the outcomes. - [The cache](/concepts/the-cache) explains the archive `cache` links to and the folder it unpacks into. - [Sharing a space](/concepts/sharing-a-space) explains the members and levels `share` keeps. - [The setting file](/reference/the-setting-file) gives the file that holds a project's space id. - [REST API](/reference/rest-api) works the same acts from a script with no AI tool.