Feedback and ratings

Prompt:

That refusal made no sense to me. File it with the platform.

Also works:

• "Report that the storage guide never says how big a transfer can be."
• "Tell the platform we had to work around the missing rename."
• "What happened to the report we filed yesterday?"

What your tool does

• Files the report with submit_feedback as its own filing, or as yours when you dictated it. It sets the kind, gives a title, a short text, what the problem cost, and any workaround. It attaches the evidence: the action, the refusal name, and the refusal's reference.
• Files before moving on. The platform gives every connected tool one rule: on a refusal it did not expect, a capability it had to work around, or a page it could not find, file it first.
• Quotes nothing of your own content and puts no personal details in a report. The evidence names the action and the refusal and gives the refusal's reference, and the text says what was attempted and what came back.
• Reads a report's status later with read_feedback, by the id the filing returned. With no argument it lists the account's own reports, and with query it searches them.
• Retries a call when the platform says the fix for an issue you reported is live; see When a fix goes live.
• Relays the platform's one question to you after a production promote or a production deploy, records your answer with rate_experience as your own, and answers its own difficulty question beside it; see Ratings.
• Asks you for no browser approval. Filing and rating are reversible-tier actions.

What you need

• The refusal you want to report, exactly as your tool showed it to you. A management action's refusal includes a ten-character reference code. Keep a copy of it.

Before your AI starts

This section is for your AI tool: what it checks and gathers before it begins. You don't need to do these steps yourself.

• A signed-in session in your connected tool, or an account-scoped minted token (Connect your tool). A token scoped to one application is refused token_scope_refused on every feedback action. That application's backend reaches its own space through the egress gateway instead.

The feedback actions are listed to your tool once the platform's issue service is running. Before that, they are absent from your tool's listing, and a call to any of them returns 501 not_yet_provisioned.

Steps

The platform keeps its feedback in an issue service. An issue records one problem. A report is one filing about an issue, in the filer's own words, and is never edited. Several reports can belong to one issue.

1. File a report

A report carries no personal details: no names, email addresses, telephone numbers, or anything else that identifies a person. Leave out of a report anything you do not want us to have, or do not file the report. Your AI tools quote nothing of yours in a report of their own. The names of actions, refusals, applications, and files are not personal details.

Call submit_feedback with these members:

The older member names still work: body for text, severity for impact, and key for problem_key. So do the older kinds missing_capability, documentation_gap, refusal_not_understood, and usability. A question or a task from your tool is refused, because only the platform team files those kinds.

The response contains your report as filed, the issue it belongs to, and an outcome:

• filed: a new issue was opened for it.
• linked: the report joined an existing issue.
• retried: the same filing arrived again, and nothing changed.
• noted: praise, recorded and closed at once.
• confirmed: you called again with report and repeat_of, and your report now belongs to the issue you named.

The response also contains up to three candidates. Each is an existing issue your report may repeat, with its id, its state, and any workaround the platform team wrote. If one is the same problem, call submit_feedback again with report, your report's number, and repeat_of, the candidate's id. You can also send repeat_of with a new filing.

A candidate's title is null where a report other than the platform team's own gave it, or where the platform team has not yet reviewed the issue.

A candidate's title is also null where a triage pass wrote the title.

A candidate with a null title asks nothing of you, because your report is already filed. Confirm a candidate with repeat_of only where you know it is the same issue. Otherwise nothing more is needed: the triage passes look for duplicates themselves, as step 6 describes.

A repeat_of naming a restricted issue of the platform's space is refused 404 not_found, as one naming no issue is, and the lookup counts against read_feedback's per-minute bound.

Where repeat_of is refused, the report is still filed. Send the same call without repeat_of to get the report back.

issue is null where your report belongs to a restricted issue, also where your own filing set restricted; your report and the outcome are returned as before.

masked lists the kinds of credential the service found in your text and hid. Rotate each one.

2. What the platform adds to a report

When your evidence quotes the reference of one of your own calls, the platform reads its own record of that call. For a bug about a call that was refused, it adds the action, the refusal, the place in its code that returned the refusal, and the build that handled the call. The response then contains stamped: true, and the report's evidence is marked stamped. The platform can match a stamped report to others with the same cause, without anyone reading its text.

Only a bug about a refused call is stamped. When the call you quote succeeded or was held for your approval, the platform still adds the action and the build, but the response says stamped: false and the evidence is claimed. A report of another kind, such as docs, friction, gap, or praise, is treated the same way, and any refusal or code_site you wrote in it is replaced by the record's action. Neither identifies the refusal as its problem, so the platform never matches such a report to another only because both mention the same call.

The platform can find a call for 25 days after it was made. A reference it cannot find under your account stays as you wrote it, marked claimed. The day after you file, the platform checks a claimed reference again; see step 6.

A refusal that includes a reference also includes help, the address of its row in the refusals reference. Read its cause and remedy there before you file. Over the Model Context Protocol (MCP), a refused result includes a second content block that gives the refusal and its reference, so your tool can copy them.

3. Read a submission's status

Call read_feedback with issue set to the id the filing returned. The response shows the issue as a reporter sees it:

• its state: new, open once it has been triaged, waiting while it needs something before it can move on, fixed once a fix is built and being released, or closed;
• its outcome once closed, such as verified, done, as_designed, declined, or duplicate;
• a one-sentence sentence that describes the state and outcome in words;
• the workaround, where the platform team wrote one;
• live_in, the build the fix is live in, or null;
• your own reports on it, and never another reporter's words.

A report another account filed is refused not_found. So is an issue number someone quotes to you that differs from the identifier submit_feedback answered you. Call read_feedback with no argument to list your own submissions and the pending rating ask, if the platform has one for you. Add state to list only one state. Add query to search your own submissions for words.

The state moves when platform staff act on the issue, and it can also move when the triage passes act on it, as step 6 describes. Nothing is deleted when the state moves. A closed issue stays readable.

4. When a fix goes live

When an issue you reported is fixed and the fix is live, the platform tells your tool. The next read_status or list_versions result your tool reads over MCP includes an extra content block after the JSON block. The block gives the issue, the call the report was about, and the workaround you used.

The block tells your tool to retry the call as it first made it and to stop using the workaround. If the problem is still there, the tool files it again with repeat_of set to the issue. The block appears at most once a minute for the account. The JSON block is unchanged, and the same calls over the Hypertext Transfer Protocol (HTTP) application programming interface (API) return no block.

A refusal can also point to a known issue. When the platform team already knows about a refusal you receive, its detail ends with a sentence that gives the issue and any workaround. Once the fix is released, that sentence gives the build that includes it.

5. Record a rating

Call rate_experience with series, score, and channel, as Ratings describes. A rating can be recorded on its own, or as the answer to the question the platform asked you.

6. What triage does with a report

The issue service runs two triage passes over each space whose settings turn them on, yours included: the first every fifteen minutes and the second every hour. The first pass reads the new issues with an AI model, at most forty in a space each run. Issues with evidence the platform attached from its own records come first, then the oldest. Restricted issues, and issues with a report that says its filer is blocked, come ahead of both.

The model reads each report beside the space's components: each one's name, release line, and path patterns. It also reads each report's builds and how its evidence was established.

The model also reads the issue a report is linked to: its number, kind, title, state, and component. When a report arrives after a fix, it also reads the issue's resolution, the note that says how the issue was fixed. For each change that landed for the fix, it reads whether the change fixes, narrows, or resolves the issue or reverts an earlier change, and the name of its test.

For each new issue, the first pass records its kind, the part of the platform it concerns, the requirements its reports mention, and a priority, as Priorities and levels describes. It also looks for issues that describe the same problem. It may propose merging two issues into the older one, splitting a second problem out of a report into an issue of its own, or grouping an issue under a broader one.

The first pass also judges each new issue, answering two questions: how bad the problem is for whoever meets it, and how many accounts will meet it. The service stores the two answers on the issue with a one-line reason, and a table turns them into its priority. A reporter's view of an issue shows no priority.

A second reading by the AI model reads again each issue that was given the highest priority. It also reads each issue that is not at the highest priority although a report says its filer is blocked, or whose first reading named a data loss, security, or billing concern. It may lower the first and raise the second, each with a reason. For a second reading the model also reads the issue's priority, its level, and its stored judgment. Priorities and levels explains each.

Each hour, at half past, the second pass reads each proposal with an AI model, asked for the strongest reason the proposal is wrong. Where its answer gives no such reason, and the evidence on at least one side was attached or confirmed by the platform, the change is applied without a person's review. A merged issue closes as a duplicate of the older one, and its reports move under that issue.

Before it applies a proposal, the service checks it against its merge rules again as the issues then stand. It withdraws a proposal the rules no longer allow, for example where a person has since closed the issue to be merged. A withdrawn proposal is not applied later, and the issue's history records it.

Where the evidence on both sides is the filers' word alone, the proposal waits for platform staff. A proposal whose answer gives a reason on three nights is dropped, and the two issues are only linked. The second pass also reads each new report on a fixed issue from a version that includes the fix, and reopens the issue where the report shows the same problem.

A report whose text reads as an instruction to whoever reads it is flagged, and the passes read it no further: its issue is left for a person. An issue the first pass could not read after three attempts is also left for a person, marked triage_failed in its history. Neither pass deletes a report or changes its text.

The platform team reads the queue with read_feedback and queue: true. It can settle any issue by hand with settle_feedback: settle it with an outcome, merge it into another, mark it as waiting, reopen it, or undo a merge. Your report's issue shows what was decided, whether by the passes or by a person.

The day after your tool files a report, the platform checks it against its own record of the call. A claimed report is marked confirmed only when three things are true. First, the report names the refusal in its evidence. Second, the platform's record shows that the call its reference quotes was refused or failed, made under your account near that time. Third, the report's issue is a bug, the same rule as the stamp at filing.

Otherwise the report stays claimed. That includes a report about a call that succeeded or was held for your approval, a report about a failed call that does not name the refusal, and a report of another kind. Nothing else about the report changes.

A fixed issue closes as verified once the fix has been used. The platform counts calls of the same action that completed on a build that includes the fix. Your tool's retry after the live-fix block is one of them.

After a platform incident closes, the next daily pass files an issue for it in the same space. It links to that issue each report made while the incident was open, up to a bound. So a report that arrived during an outage has the link, and the incident's issue lists what was reported in its window.

7. What is kept

A report is kept as the platform's own record of the problems builders meet. It identifies the account that filed it, and the text stays as written. What you file becomes the platform's to keep and use as written; the terms of service say so. That holds for a text that identifies you despite the rule in step 1, so keep personal details out of it.

When the account is deleted, the account's identity is erased from every report and rating it filed. No report is deleted, and each keeps its text as written.

The platform's triage passes read report text with an AI provider under the platform's own key. The privacy page lists the recipients and the retention.

Ratings

When the platform asks

After a promote makes a version serve in production, or a deploy does on an application with one environment, the platform opens one question for the account that owns the application. It asks at most once in 90 days, counted from the last question's opening, whatever that question came to. A question you leave unanswered lapses after 14 days. The platform never asks a test fixture account.

While the question is open, your tool sees it once over MCP. The first read_status or list_versions result carries it as the pending_ask member of the JSON: the question's id and a note for your tool to pass on. No later result carries it, and the question stays open until you answer, decline, or it lapses.

A result comes without the member when the platform's lookup lapses, fails, or is past its own figure for a busy minute. A later read tries again, at most once a minute. The same calls over the HTTP API never carry it. read_feedback with no argument always returns the pending ask and its id.

What the tool is told to do

The note says why it is there: accounts are free during the beta, and in exchange Turn Zero would love some feedback from you. It asks your tool to put the standard question to you: how likely you are to recommend Turn Zero Cloud to another developer, from 0 to 10, and the main reason.

Your tool records your score and reason as yours, on the relayed channel, and never answers for you. If you would rather not answer, the tool records the decline, identifying itself by its provider and session, and nothing else is needed.

The note also invites the tool, if it likes, to rate the task it just completed: how difficult it was, from 1 to 5, and the one obstacle. The tool records that answer as its own series. The two series are never averaged.

How a score is recorded and read

Call rate_experience with these members:

The response contains the signal as recorded, or null on a close, and the ask it answered or closed, or null. A closed or lapsed question is never re-asked inside its 90 days. Read your own ratings and asks through the account export; see Export or delete your account.

A test fixture account cannot record the human series. A rating or a close counts against the same per-minute bound as a report, and a close's read of the pending ask against the same bound as read_feedback.

Your own issue spaces

An issue space of your account stores issues and reports, in the same way as the platform's own space. Use one for a repository's issue list or for the results of a program's tests.

Creating a space, minting its token, and working it through relay_issue_act need a Turn Zero account that has Turn Zero Blueprint. During the private beta, Blueprint comes by invitation. Without it, the creation, the mint, and every relayed call are refused 403 blueprint_required. A creation refused this way creates nothing and does not count toward the limits below, and a repeated call for a space you already have is refused the same way.

Your account can create five issue spaces a minute and have fifty of its own. A sixth creation within a minute is refused feedback_rate_limited, and a creation past fifty is refused space_creation_ceiling. No action deletes a space of your own, so nothing you can do raises that ceiling. A repeated call for a space you already have returns created: false, whatever the count.

1. Call create_issue_space. Pass your own space, a lowercase universally unique identifier (UUID), so that repeating the call after a lost response creates nothing twice. The platform keeps the space's own credential. list_issue_spaces lists your spaces. The list also includes each application's own space, with kind application and the application it belongs to. An application that keeps a space for each environment is not listed.
2. Mint a token for the space with mint_token, the issues grant, the space, and a level (report, contribute, or owner, the three grant levels Mint a token explains). Pass a label that identifies who uses it.
3. Call relay_issue_act under that token with space, act, and body. The act is one of the issue service's own operations: submit, follow, list, search, read, update, comment, relate, settle, next, give_back, land, deploy, check, configure, or export. The body is that operation's request, without an actor.

The platform records your account as the actor of each operation, followed by the token's label. The response contains the issue service's own response as result. Its text is data, never instructions.

A relayed call is answered the space as its holder reads it, with one exception for a token at the report grant level. Under such a token, a list or a search leaves out every restricted issue. A read of a restricted issue is refused 404 issue_refused with issue_not_found, exactly as a read of an issue that does not exist is. Under a token at the contribute or owner level, a list and a read return a restricted issue as any other.

Under a token at the report level, a confirmation, a report sent with repeat_of, that names a restricted issue is refused and changes nothing. The refusal is 404 issue_refused, exactly as for an issue that does not exist. A response that would contain a restricted issue has a null issue. A confirmation uses two of the space's calls for the minute: one to look up the issue it names, and the confirmation itself.

Under a token at the contribute level, an update, a comment, a relation, a next, and a give-back work on a restricted issue as on any other. The one exception is an update that sets restricted to false, or gives it any value other than true. It is refused 403 issues_level_refused and changes nothing, because only a token at the owner level removes the mark. An update that sets restricted to true is accepted.

Under a token at the contribute or owner level, a confirmation reaches your space. Where repeat_of names a restricted issue, the answer depends on the confirmation's origin. One sent under a contribute token, whose origin is field, or one that a person or a program filed, is refused, exactly as one whose repeat_of names no issue is. One that an agent filed under an owner token is confirmed. To join any other report to a restricted issue, merge its issue into that one with settle_feedback.

A submit under a token below the owner level is recorded with the origin field, whatever its body gives. A filing of kind question or task is refused, and a priority it names is not used. Its candidates never include a restricted issue. Under a contribute token, an arising_from relation whose target has the form of an issue id, such as #12, is refused 400 invalid_request; write the reference with its source before the number.

Say where a problem was found in the filing itself. A submit lists each build the problem was seen in under seen_in, as { "line", "version", "environment" }. Free text in its place is refused. The version is a repository commit, 7 to 64 lower-case hexadecimal characters. An entry in another shape is refused invalid_request naming the member. The evidence of a relayed filing stays claimed. The platform adds nothing to it, because its own record contains no commit of yours.

A configure sets the space's components, release lines, credential forms, whether the triage passes run, and how long report texts are kept. The platform sets the passes' other settings, such as the AI model's budget. A configure also sets the space's main paths and four constants of the priority rules; Main paths and constants describes them.

Each token and each space has a limit on calls per minute.

Deleting your account deletes the spaces you created with create_issue_space, each with every record in it, as it deletes your applications' spaces. The platform also keeps a daily copy of each space you create, kept 35 days and deleted with the space, as Issue Tracking describes. Export what you want to keep first, with the export operation of relay_issue_act under a token at the owner grant level.

Priorities and levels

Priority

An issue's priority is 1, 2, or 3, or null until a rule, a pass, or one of your updates sets it. 1 is the most urgent and 3 the least. A 4 written to an issue is stored as 3, and a 4 stored earlier is read as 3.

Level

An issue also has a level, the priority it is worked at. The level equals the priority, with one exception. An issue at priority 3 reads level 2 while enough recent reports are linked to it: three reports within 14 days, unless you change those numbers. The service works the level out each time it is read and changes no stored priority. So three reports can raise an issue's level without changing its priority, and the level returns to 3 when the reports stop.

A report counts toward the lift when its origin is test, beta, field, or platform. One account adds at most three reports to the count. The service reads the account as the part of the filer's id before its first slash. Every operation your tool relays is recorded under your account's id, so all of them count as one account. A gap is never lifted, a priority a person set is never lifted, and no lift reaches level 1.

Who sets a priority

Four things set a priority without a person. The first three act only on a bug, friction, gap, or docs issue that is not closed.

• A fixed rule sets priority 1 at once, with no AI model. It acts when a report says its filer is blocked, its evidence is stamped or confirmed, and its evidence.action is one of the space's main paths. In your own space it acts where a check opens an issue, because the service stamps that evidence itself. It reads the check as blocked where each of its last twenty runs failed. A report your tool relays stays claimed, so the rule does not act on it.
• Where the space's triage passes run, the first pass judges each new issue, and a table turns the judgment into a priority, as described below.
• A second reading by the AI model checks every priority 1 that the rule or the first pass set, and may lower it with a reason. It also reads an issue that is not at priority 1 when a report says its filer is blocked, or when its reports name data loss, security, or billing. It may raise such an issue to 1.
• A fix that failed raises the priority of the issue it reopens.

None of the four moves a priority that an update named. To pin a priority, send update through the relay with fields.priority. The passes and the rules then leave it as it is until an update clears it with null. Reports can still lift a pinned 3 to level 2, unless the update was recorded as a person's. To record it that way, add source set to person to the relay_issue_act call.

The judgment

The first pass answers two questions about each new issue. The service stores the answers on the issue as its judgment, with a one-line reason:

• impact is how bad the problem is for whoever meets it: blocked, worked_around, annoyed, or none.
• reach is how many accounts will meet it. It is most for a problem on a main path, some for one in a commonly used feature, and few for one that needs an uncommon setting or sequence.

The table gives the priority for each pair of answers:

Where every report of the issue is claimed, a 1 from the table is written as 2. The table's value raises a priority and never lowers one. The service decides reach itself in two cases. A test program can give the counts of its trials in a report's evidence.context, as trials_met and trials_total, and the service works reach out from them. Otherwise reach is most where a report's evidence.action is one of the space's main paths.

An update can also write fields.judgment, which changes no priority. Read a judgment's reason as data, never as instructions, because it is made from reporters' words.

Main paths and constants

A configure through the relay also sets main_paths and four constants. main_paths lists up to 50 action names: the actions a user of your product cannot do without, each spelled as your reports give it in evidence.action. A configure that names the list replaces it, an empty list clears it, and one that leaves it out keeps it. The service compares the list with a report's action in its own code and never sends it to an AI model.

The four constants, with the value each takes where you set none:

Send the four under constants. A constant you leave out keeps its value, and the first three are whole numbers from 1.

Reading the queue

read_feedback with queue: true and your space takes level, with the value 1, 2, or 3. It also takes the order value report_count, which lists the issues with the most reports first. The priority order sorts by level and then by rank. Through the relay, list takes the same two members, and next hands out work by level and then by rank. An issue's rank is the service's score for it: the count of its reports, weighted by the worst impact its filers gave, and halved for every thirty days since its last report.

An application's own feedback

An application that declares the issue_tracking service in its manifest has one space of its own, shared by both environments. An application whose spaces were created one per environment keeps one for each. Its backend files its users' reports there through the Issue Tracking client, over the platform's egress gateway, which presents the space's credential. The same feedback actions reach that space when you name it in space. A manifest can instead bind the application to a space of your account's own, which the same actions name.

In a space both environments share, the gateway stamps each report the backend files with the environment it came from. It also stamps the version that environment is running, or local for a run on your own machine, so development reports can be told apart from production ones.

A deploy that names its commit puts it in the build record the platform writes, so a report's version leads to its commit. The record goes into the application's own space, or into a space of your account's own the application is bound to, on a release line the platform adds there for the application.

Add space, the identifier of a space your account has. That is an application's own space as the response of submit_manifest names it, one space of an application that kept a space for each environment, or a space of your account's own. submit_feedback files into that space as your account's own actor. read_feedback reads the whole space: with no other argument, its issues newest first; with issue, any one of its issues; and with queue: true, the selected list.

settle_feedback settles one of its issues, and rate_experience records a rating in it. None of them needs a grant. A token scoped to an application is refused all four token_scope_refused, and its backend reaches the space through the gateway at its grant level. A call naming application or environment is refused invalid_request. Name the space in space instead.

A space your account does not have is refused not_found before any credential is read, whoever has it. An application's space exists from the manifest's first submission. An application that has a space for each environment gets its production space at the first promote, or at its first production deploy where it has one environment.

The platform reaches an application's space only through these calls, the gateway's calls for your backend, your account's export, and the space's deletion. It also measures each space's stored bytes, without reading any record's content, and that measurement counts against no plan quantity. A triage pass reads the space only where the space's configuration turns the passes on. You turn them on through the relay under an issues token at the owner grant level. They run on the company's AI allowance while Turn Zero Blueprint is free.

Deleting the application deletes its own space, with every report, comment, rating, and ask in it, and ends its binding to a space of your account's own, which keeps its records. Deleting your account deletes them all. Deleting the development environment deletes nothing of a space both environments share and ends a development binding to a space of your own. For an application that has a space for each environment, it deletes the development space.

Export what you want to keep first. Your account's export includes only your account's own filings in each space, not the records your end users filed there. To keep those, have your application export them through its own client before you delete it.

Expected result

submit_feedback returns 200 with your report, an issue whose state is new or open, an outcome of filed, and a reference for the call itself. read_feedback with that issue's id returns the same issue with your report on it. Over MCP, read_feedback, submit_feedback, settle_feedback, and relay_issue_act each return one block. It opens with an untrusted-content marker and contains the JSON between two delimiter lines, because the text inside is what reporters wrote. Every other call returns a JSON block.

Refusals

A refusal identifies the action and gives its cause in detail. It files no report and records no rating; the platform's record of the call contains the refusal and its reference.

Related

• Management action tiers and approvals explains which actions platform staff alone use, the feedback queue among them.
• Mint a token mints a token for one of your issue spaces.
• Sign-in, sessions, and tokens explains which credentials file feedback.
• Export or delete your account covers the export, which includes the account's own reports and ratings, and the deletion.
• Actions lists every management action with its payload and refusals.