Amber

Official

by ambermem

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

Check export status and get the download link

amber_get_export_status

Read-onlyIdempotent

Check the status of an export started by amber_export_memories and get its download link once complete. Poll to track progress, detect failures, and retrieve a signed link valid for 7 days.

Instructions

Check an export started by amber_export_memories, and collect its download link once it is finished. Not rate-limited. Read-only. Requires an active subscription.

Statuses: pending (queued), running (writing the file), complete (ready -- download_url is set), failed (gave up; error says why).

Poll every few seconds. memory_count climbs while it runs, so a caller can tell progress from a stall. Only report the export as ready to the user once status is complete.

The download_url is signed and valid for 7 days, matching how long the export itself is kept, so an interrupted download can be RESUMED with a Range request rather than restarted. Call this again for a fresh link if it has expired, and note an old link. The export itself is kept for 7 days, after which this returns code: not_found.

Input Schema

Name	Required	Description	Default
`task_id`	Yes	The id returned by `amber_export_memories`. An unknown or expired id returns `code: not_found`.

Output Schema

Name	Required	Description
`error`	Yes	Why the export failed. Null unless status is `failed`.
`status`	Yes	`pending` queued, `running` writing, `complete` ready to download, `failed` stopped (see `error`). A stalled export becomes `failed` with a reason rather than sitting on `running`.
`task_id`	Yes	The task this report is about.
`chunk_count`	Yes	How many background passes have written a piece of the file. Progress, and the reason a large export takes more than one poll.
`exported_at`	Yes	The moment the export represents. Every memory in the file is as it was at this instant, whatever the export took to finish.
`download_url`	Yes	Signed download link, set only when status is `complete`. Short-lived: poll again for a fresh one rather than reusing it.
`memory_count`	Yes	Memories written so far. This is the FINAL count once status is complete.
`include_deleted`	Yes	Whether this archive carries TRASHED memories as well as active ones. Stated rather than inferred, because the count alone cannot tell a full backup from a partial one: `POST /backup` (the unattended route) always includes the trash, while `amber_export_memories` includes it only when asked. If the user wanted a BACKUP, this should be true.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.1.6Nov 5, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Goes well beyond the annotations: states it is not rate-limited, requires an active subscription, and documents the status semantics, progress signal (`memory_count` climbing), 7-day retention and post-expiry `code: not_found`. The resumable-Range detail is genuinely useful. Minor gap: no note on whether polling itself incurs costs or how long a `pending` task may sit before it counts as stalled.

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 purpose and usage, then statuses, then link lifetime — a sensible order. Slightly redundant: the 7-day export retention is stated twice ('valid for 7 days, matching how long the export itself is kept' and later 'The export itself is kept for 7 days').

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 needn't be spelled out, yet the description still covers statuses, error signalling and link expiry. For a one-parameter polling tool this is complete; nothing needed to call it correctly is missing.

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

Parameters3/5

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

Schema coverage is 100% and the schema already explains that `task_id` is the id returned by `amber_export_memories` and that unknown/expired ids yield `not_found`. The description repeats that provenance rather than adding new meaning, so the baseline 3 applies.

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+resource ('Check an export started by `amber_export_memories`') and adds the second function (collect the download link). It names the sibling that creates the export, so the agent can tell it apart from the import-status and store-task-status siblings.

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?

Explicit operating instructions: poll every few seconds, only report ready once status is `complete`, and call again for a fresh link if the URL expired. The lifecycle (pending/running/complete/failed) gives the agent the decision rules it needs.

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