Skip to main content
Glama

optimize_stage

Stage memory curation suggestions for human review in the dashboard, skipping invalid ones and reporting errors before application.

Instructions

Stage a batch of curation suggestions for human review in the dashboard.

Step 2 of the "optimize my memories" workflow. NOT applied here: the user reviews and applies or rejects each one in the admin dashboard, which backs up before the first apply and can undo any of them.

Invalid suggestions are skipped and reported in errors, as many as fit one page, with errors_total counting them all when some are left out; the rest are staged. Returns {run_id, staged, errors}.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
noteNoone short summary of the pass, at most 250 characters; a longer one raises and stages nothing. What a single suggestion needs said belongs in its own `rationale` and `verified`, which are not capped.
suggestionsYeseach one {"kind", "target_uid", "payload", "rationale", "verified"}. Kinds: compact/reword {"new_content"}, retag {"tags"}, retitle {"title"}, redomain {"domain"}, crosslist {"also": [...]} (replaces the whole set), set_confidence {"confidence"}, review {"review_after"} (a date or a span like '180d'; '' clears it), archive {"reason"}, link {"from_uid","to_uid","relation_type"}, merge {"keep_uid","drop_uid"}, distill {"source_uids","new_type","new_content", "title"}, unleak {"field": "content|tags|source_ref"} (the repair is computed at staging). link/merge derive target_uid from the payload and distill creates its target -- omit it for those. Destructive kinds (archive, set_confidence=contradicted, merge, distill) require a non-empty `verified` describing the live-facts check behind them.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.16.1
    • addedInput schema / properties / note / description
      Added value: +"one short summary of the pass, at most 250 characters; a longer one raises and stages nothing. What a single suggestion needs said belongs in its own `rationale` and `verified`, which are not capped."
    • removedInput schema / properties / note / title
      Removed value: -"Note"
    • addedInput schema / properties / suggestions / description
      Added value: +"each one {\"kind\", \"target_uid\", \"payload\", \"rationale\", \"verified\"}. Kinds: compact/reword {\"new_content\"}, retag {\"tags\"}, retitle {\"title\"}, redomain {\"domain\"}, crosslist {\"also\": [...]} (replaces the whole set), set_confidence {\"confidence\"}, review {\"review_after\"} (a date or a span like '180d'; '' clears it), archive {\"reason\"}, link {\"from_uid\",\"to_uid\",\"relation_type\"}, merge {\"keep_uid\",\"drop_uid\"}, distill {\"source_uids\",\"new_type\",\"new_content\", \"title\"}, unleak {\"field\": \"content|tags|source_ref\"} (the repair is computed at staging). link/merge derive target_uid from the payload and distill creates its target -- omit it for those. Destructive kinds (archive, set_confidence=contradicted, merge, distill) require a non-empty `verified` describing the live-facts check behind them."
    • removedInput schema / properties / suggestions / title
      Removed value: -"Suggestions"
    • removedInput schema / title
      Removed value: -"optimize_stageArguments"
  2. First observedv0.1.0

TDQS

A4.4/5.0
Behavior5/5

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

Adds substantial behavior beyond the annotations: staging is non-committal because the user applies or rejects in the dashboard, which backs up before the first apply and can undo any change — this explains the destructiveHint=false despite destructive kinds being stageable. It also discloses partial-failure semantics (invalid suggestions skipped, reported in `errors`, capped to one page with `errors_total` counting the rest) and the verified-required rule for destructive kinds.

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 purpose, then workflow position, then the non-application guarantee, then error handling — a logical order with no filler. It is dense and slightly long for a two-parameter tool, but every sentence carries information an agent needs.

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?

With no output schema, the description supplies the return shape ({run_id, staged, errors}) and the truncated-error accounting. Combined with the staging/undo guarantee and the workflow position, nothing material is missing for correct invocation.

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 description coverage is 100%, so the schema already carries the full parameter burden, including the kind/payload matrix and the `verified` requirement for destructive kinds. The description's own parameter-adjacent content concerns return fields (`errors`, `errors_total`), not new input semantics, so 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 (stage) and resource (a batch of curation suggestions) plus the destination (human review in the dashboard). It also positions itself in the optimize workflow, which cleanly separates it from optimize_scan, optimize_runs and optimize_status among the siblings.

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

Usage Guidelines4/5

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

Explicitly says it is 'Step 2 of the "optimize my memories" workflow' and that nothing is applied here, so the agent knows when this tool belongs in a sequence. It never names the prerequisite sibling (e.g. optimize_scan) or states an explicit exclusion, so it stops short of a full when/when-not map.

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