Suggest an improvement and track it

The job

Tell the Sasha team about one thing that got in your way, and later find out what they did about it.

Prerequisites

No scope is needed. Any authenticated connection can call suggestImprovement and checkSuggestion, including a member's.
A member's connection can check only the suggestions that the same connection filed. An admin or staff connection can check any suggestion on the instance. See checkSuggestion.

Steps

File the issue at the moment it gets in your way. File one call for each distinct issue. Do not put a whole session into one report.
```
{
  "kind": "feature",
  "summary": "searchKnowledge should return every matching line in a file, not only the first",
  "detail": "I searched northwind-advisory for 'discount'. pricing-policy.md mentions discounts on several lines, but only the first line came back, so I had to read the whole document to find the approval rule.",
  "toolName": "searchKnowledge",
  "project": "northwind-advisory",
  "severity": "minor"
}
```
```
{ "id": "sug_4f1c9a2e7b3d5a6c8e0f1b2d", "status": "received" }
```
Read status:
- received: the suggestion is recorded. Keep the id, and tell the person that you filed it.
- duplicate: this connection filed the same summary in the last hour. The id is that of the earlier suggestion.
- rate-limited or not-recorded: nothing is recorded. These are answers, not errors. Continue your main task, and try once more near the end of the session if it still matters.
A failed filing never blocks your main task.

In a later session, check the suggestion by its id.

{ "id": "sug_4f1c9a2e7b3d5a6c8e0f1b2d" }

{
  "id": "sug_4f1c9a2e7b3d5a6c8e0f1b2d",
  "kind": "feature",
  "severity": "minor",
  "summary": "searchKnowledge should return every matching line in a file, not only the first",
  "disposition": "shipped-canary",
  "dispositionNote": "Added an option to return more than one line for each file.",
  "pr": "#800",
  "liveVersion": "v1.0.1500",
  "createdAt": "2026-10-02T10:41:07.233Z",
  "updatedAt": "2026-10-03T08:15:52.019Z"
}

disposition says what happened. dispositionNote says why, when it has a value. For the meaning of each disposition, see checkSuggestion. For already-covered, dispositionNote names the tool that already does the job: use it.

To see the suggestions from the last 30 days that this connection can see, without an id, read the improvements section of the guide. It ends with a table of them. When there are none, the section ends with No suggestions in the last 30 days.
```
{ "section": "improvements" }
```

What can go wrong

A value outside the limits is refused as invalid arguments: a kind or severity outside its list, a summary shorter than 10 or longer than 300 characters, a detail longer than 2 KiB, or a toolName or project that is too long or has the wrong form. Correct the value and call again. The limits are in suggestImprovement.
Error in checkSuggestion: Suggestion not found: no suggestion has that id, or a member's connection asked for a suggestion that another connection filed. Use the id that suggestImprovement returned to this connection.
An id that is not sug_ followed by 24 lowercase hexadecimal characters is refused as invalid arguments.

Before you file blocking, check the cause against document text or tool results, not memory. Do not file a problem in the knowledge content that a write tool can fix.

Suggest an improvement and track it

The job

Prerequisites

Steps

What can go wrong

Related notes