metrecept-opensource

Cache: Manage cache tree

metrecept_manage_cache_tree

Create, fork, or promote isolated cache trees to isolate experiment or PR cache, then merge accepted entries into a parent or main tree without copying bytes.

Instructions

Create, fork or promote a cache tree (an isolated exact-replay namespace). Use it to isolate cache for an experiment or PR: fork main, send chat calls into the fork, promote it back when good, then remove it with metrecept_delete_cache_tree. Not for listing trees: use metrecept_list_cache_trees. Not for deleting a tree or entry: use metrecept_delete_cache_tree or metrecept_evict_cache_entry. create and fork give the new tree an empty local index that reads its parent chain copy-on-write, so it serves parent entries by reference with zero bytes copied; its own new entries stay local. promote adds references to tree_id's own entries in the target tree (bytes_copied is always 0) and leaves the child intact; it never swaps trees, main stays the default and cannot itself be promoted. Not billed; audit-logged. Errors return ok=false with status and error: 409 tree_exists, 404 parent_missing, 404 tree_missing, 409 cannot_promote_main, 409 parent_frozen, 409 tree_archived or parent_archived, 400 invalid_cache_tree. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Input Schema

Name	Required	Description
`into`	No	promote only: target tree id; empty means the child's parent. Use "main" to land a grandchild directly in main.
`name`	No	create/fork: optional id for the new tree, [a-z0-9_-]{1,64}; empty generates "t-" plus 10 hex characters. Ignored by promote.
`action`	Yes	"create": new tree under parent (default main). "fork": new child of tree_id. "promote": merge tree_id's own entries into the target tree (default its parent).
`parent`	No	create only: parent tree id the new tree reads through to; empty means "main".
`tree_id`	No	fork: tree to fork (main allowed). promote: tree whose entries are merged (not main). Required for fork and promote; ignored by create.

Output Schema

Name	Required	Description
`ok`	Yes	True when the gateway accepted the request (HTTP 2xx).
`name`	No	create/fork: name of the new tree (same as tree_id).
`error`	No	On failure: gateway error code, e.g. tree_exists, parent_missing, tree_missing, cannot_promote_main, parent_frozen, invalid_cache_tree, tree_id_required.
`action`	Yes	The action that was requested.
`billed`	No	Always false on success: tree management is not billed.
`status`	Yes	HTTP status returned by the gateway (200 on success).
`default`	No	create/fork: always false; main stays the tenant default.
`tree_id`	No	create/fork: id of the new tree.
`created_at`	No	create/fork: creation time, Unix seconds (UTC).
`tree_status`	No	create/fork: lifecycle status of the new tree, "active".
`bytes_copied`	No	promote: always 0; promote shares bytes by reference.
`promoted_from`	No	promote: the child tree whose entries were merged.
`promoted_into`	No	promote: the target tree that now references them.
`parent_tree_id`	No	create/fork: tree the new tree reads through to copy-on-write.
`digests_considered`	No	promote: digests in the child's local index.
`digests_referenced`	No	promote: new references added to the target (digests it could not already resolve).

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.4.1Oct 25, 2026

changedInput schema / properties / action / description

Previous value: -"\"create\": new tree under parent (default main). \"fork\": new child of tree_id. \"promote\": merge tree_id's own entries into into (default its parent)."New value: +"\"create\": new tree under parent (default main). \"fork\": new child of tree_id. \"promote\": merge tree_id's own entries into the target tree (default its parent)."

Addedv0.3.1Oct 25, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations present the description carries the full burden, and it does: copy-on-write parent-chain reads with zero bytes copied, promote adds references rather than swapping trees, the child stays intact, main cannot be promoted, no billing, audit logging, auth requirement (METRECEPT_API_KEY / Bearer) and tenant scoping. It also enumerates failure modes with status codes (409 tree_exists, 409 cannot_promote_main, 409 parent_frozen, etc.).

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?

Purpose and the recommended workflow are front-loaded, and each subsequent sentence carries real information (semantics, error codes, auth). It is dense and runs long as a single block, but nothing is purely redundant with the schema.

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?

For a multi-action mutation tool with an output schema and no annotations, the description covers semantics, side effects, error surface, auth and tenant scoping — everything an agent needs to invoke it correctly. Return values are legitimately left to the output schema.

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% and the schema already explains every parameter including action enum and the 'into'/'parent'/'tree_id' interactions, so the baseline applies. The description reinforces behavior ('create and fork give the new tree an empty local index', 'promote ... leaves the child intact') but adds no parameter-level detail the schema lacks.

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?

Names three concrete verbs (create, fork, promote) on a clearly defined resource ('an isolated exact-replay namespace'), and explicitly distinguishes itself from listing and deletion siblings. An agent can select this tool 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?

Gives a concrete workflow ('fork main, send chat calls into the fork, promote it back when good, then remove it with metrecept_delete_cache_tree') plus explicit exclusions routing to metrecept_list_cache_trees, metrecept_delete_cache_tree and metrecept_evict_cache_entry. Both when-to-use and when-not-to-use are stated with named alternatives.

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