Amber

Official

by ambermem

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

Restore memories from a backup URL

amber_import_memories

Idempotent

Restore an Amber backup directly from an HTTPS URL without storing a copy; use a long-lived presigned link and poll the returned task until complete.

Instructions

Restore an Amber backup from a URL. Amber reads the archive DIRECTLY from that URL and never stores a copy of it.

Use this when the user has their .json.gz backup somewhere reachable over HTTPS -- S3, R2, Backblaze, Google Cloud Storage, a self-hosted MinIO, or any presigned link. IF THE FILE IS ONLY ON THEIR COMPUTER this tool cannot reach it: send them to https://ambermem.com/backups, which explains how to upload it directly. Do not ask them to paste the file contents; a backup is far too large and it is not text you can retype.

THE LINK MUST STAY VALID FOR THE WHOLE RESTORE, which runs for hours on a large account -- tell the user to use one good for at least 30 days. Amber re-reads the URL as it works, so a link that expires part-way stops the restore.

SAFE TO RUN AGAIN. Memories keep the ids they had in the archive, so re-running cannot duplicate anything -- and a restore that stopped part-way resumes rather than starting over. This ADDS to the account; it never deletes or replaces what is already there.

Returns a task_id. Poll amber_get_import_status until it says complete, and tell the user the count when it does. Requires an active subscription.

Errors: invalid_params (the URL is not https, points back at Amber, carries credentials, cannot be read right now, does not support range requests, or what is behind it is not an Amber archive). All of that is checked BEFORE any task is created, so a rejected URL leaves nothing behind.

Input Schema

Name	Required	Description	Default
`url`	Yes	HTTPS URL of the .json.gz backup, exactly as /backup produced it. Must be readable without credentials (a presigned link is ideal) and must support HTTP range requests, which every major object store does.

Output Schema

Name	Required	Description
`status`	Yes	Always `pending` here: the restore is queued, not done. Nothing has been written yet.
`message`	Yes	A human-readable summary of what was accepted and what happens next.
`task_id`	Yes	Poll this with `amber_get_import_status` until it says `complete`.

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 cover idempotency and non-destructiveness, but the description adds far more: no copy is stored, the link must remain valid for the whole multi-hour restore and is re-read as work proceeds, a partial restore resumes, and the operation is additive only. It also discloses the subscription requirement and the full set of invalid_params causes, plus the fact that validation happens before any task is created.

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?

Front-loaded with the core action and scope, then organized into short scannable blocks for usage, link lifetime, re-run safety, return value, and errors. It is long, and the capitalized emphasis plus slight repetition about link validity cost a little, but nearly every sentence carries decision-relevant information for an agent.

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?

Despite an output schema existing, the description still names the returned task_id and the required follow-up (poll amber_get_import_status until complete, then report the count), which closes the loop for a long-running async operation. Nothing an agent needs to call this correctly — prerequisites, link requirements, resume semantics, error handling — is missing.

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% and already documents HTTPS, credential-free access, and range-request support, so the schema does the heavy lifting. The description still adds operational meaning the schema lacks — that the link must survive at least 30 days for a large account, and that URLs pointing back at Amber or carrying credentials are rejected.

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 — restore an Amber backup from a URL — and immediately distinguishes it from the sibling paths (amber_upload_backup for local files, amber_export_memories for the reverse direction) by explaining that Amber reads the archive directly from the URL. An agent can route correctly without opening any 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?

Gives explicit when-to-use conditions (file reachable over HTTPS: S3, R2, Backblaze, GCS, MinIO, presigned link) and an explicit when-not with a named alternative destination (https://ambermem.com/backups for files only on the user's computer). It also pre-empts a wrong workaround ("Do not ask them to paste the file contents").

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