The tools #

View this page as Markdown

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:<id> or agent:<name>. 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 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, 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:<account>, reporter, or outside:<what>. 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:<id> or agent:<name>.
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 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 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:<account> for one member, reporter, outside:<what>, or evidence. Only evidence puts the issue in the state waiting. Its claimed_by says who works it: a label such as session:<id> or agent:<name>, or branch:<name> 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 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 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.

  • Refusals lists every refusal the tools answer.
  • Issues and kinds explains the states, the kinds, and the outcomes.
  • The cache explains the archive cache links to and the folder it unpacks into.
  • Sharing a space explains the members and levels share keeps.
  • The setting file gives the file that holds a project's space id.
  • REST API works the same acts from a script with no AI tool.