Amber

Official

by ambermem

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

Check a restore in progress

amber_get_import_status

Read-onlyIdempotent

Check the progress of a memory restore by task ID: see if it is awaiting upload, queued, running, complete, or failed, and read the error reason when a restore fails.

Instructions

Check a restore in progress, whichever way it was started: the upload panel from amber_upload_backup, the browser page at https://ambermem.com/restore, a URL given to amber_import_memories, or a presigned upload from POST /import/presign. Not rate-limited. Read-only. Requires an active subscription.

Statuses: awaiting_upload (a link was handed out and no file has arrived yet; not a failure), pending (queued), running (restoring), complete, failed (error says why).

imported_count climbs while it runs, so a caller can tell progress from a stall. There is NO total to compare it against: the archive is never read in full up front, which is what lets a restore of any size cost the same per step. It counts memories PROCESSED, so re-running a restore counts them again even though nothing is written twice.

IF IT FAILED, SAY SO PLAINLY AND RELAY error, which names the cause and what to do. Starting a new restore is safe: memories keep their ids, so anything already restored is skipped rather than written twice. If the error says the file is damaged or cut short, the same file will stop at the same place, so restore from a fresh backup instead. A memory that was in the trash in the backup is restored INTO the trash, and is counted in imported_count like the rest. Errors: not_found (no task with that id, or it belongs to another account, or it aged out after 7 days), invalid_input (the id is missing or not a string -- the schema layer answers this one).

If the user still needs to get a file INTO Amber, amber_upload_backup shows them an uploader; https://ambermem.com/backups documents the scripted route.

Input Schema

Name	Required	Description	Default
`task_id`	Yes	The id returned by whichever call started the restore: `amber_upload_backup` with action `finish`, `amber_import_memories`, or `POST /import/presign`. An unknown or expired id returns `code: not_found`.

Output Schema

Name	Required	Description
`error`	Yes	Why it stopped, when status is `failed`. Re-uploading the SAME file is safe and resumes rather than duplicating, so say that when you relay this.
`status`	Yes	`awaiting_upload` set up and waiting for the file, which is the normal state for the whole upload flow and NOT an error, `pending` queued, `running` restoring, `complete` finished, `failed` stopped (see `error`). A restore never sits on `running` for ever: a stall becomes `failed` with a reason.
`task_id`	Yes	The task this report is about.
`exported_at`	Yes	When the archive was originally taken.
`imported_count`	Yes	Memories PROCESSED so far, and the final count once status is `complete`. Not a fraction: the archive is never read in full up front, so nothing knows the total until the restore finishes. Not a count of new rows either: writes are keyed on the id the memory had in the archive, so restoring a file twice counts every memory again while writing none of them twice.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.1.6Nov 5, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real behavioral context: not rate-limited, requires an active subscription, full status lifecycle, 7-day task expiry, and the `not_found`/`invalid_input` error surface. It also explains that `imported_count` counts processed memories with no total available, which prevents an agent from misreading a stall.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but front-loaded and organized into purpose, status vocabulary, progress semantics, and failure handling, with no filler sentences. The closing note on `amber_upload_backup` is slightly tangential for a status tool but earns its place as a next-step pointer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be re-specified, yet the description still defines every status value and the meaning of `imported_count`, plus the trash-restore edge case. For a single-parameter polling tool this leaves nothing an agent needs unresolved.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so `task_id` is already documented, but the description adds meaning the schema does not: it enumerates every call that can produce the id and explains that a mismatched or aged-out id surfaces as `not_found`. That is useful routing context rather than a restatement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Check a restore in progress') and immediately scopes it to every way a restore can be started, which separates it from the starter tools (`amber_upload_backup`, `amber_import_memories`) and from the export-status sibling. An agent can tell this is the polling endpoint for imports without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly covers when to use it (polling a restore regardless of origin), what to do on failure (relay `error`, restart safely, use a fresh backup if the file is damaged), and routes the agent to `amber_upload_backup` when the user still needs to get a file in. It even pre-empts a wrong inference by saying `awaiting_upload` is not a failure.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.