metrecept-opensource

Cache: Evict cache entry

metrecept_evict_cache_entry

Evict a stale or wrong cached response by request digest so the next identical request becomes a fresh upstream miss; only this tree's own entry is removed.

Instructions

Evict one cached response from a cache tree by its request digest, so the next identical request in that tree is a fresh miss sent upstream and billed as a miss. Use it to drop a stale or wrong cached answer. Get the digest from metrecept_list_cache_entries. Not for removing a whole tree: use metrecept_delete_cache_tree. Ownership: eviction removes only this tree's own copy or reference. An entry inherited from a parent is untouched; evict it in the parent. If this tree owns the bytes, trees referencing them after a promote also lose the entry. Destructive and immediate, no undo; not billed. Errors: 404 tree_missing or entry_missing (also on a repeat), 409 tree_frozen, 400 invalid_digest. 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	Default
`digest`	Yes	Request digest exactly as returned in entries[].digest by metrecept_list_cache_entries: a 64-character lowercase hex SHA-256 of the normalized request (the server accepts 8-200 characters of A-Z a-z 0-9 : _ - and rejects anything else with 400 invalid_digest).
`tree_id`	No	Cache tree id that holds the entry (default "main").	main

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.3.1Oct 25, 2026

addedInput schema / properties / digest / description

Added value: +"Request digest exactly as returned in entries[].digest by metrecept_list_cache_entries: a 64-character lowercase hex SHA-256 of the normalized request (the server accepts 8-200 characters of A-Z a-z 0-9 : _ - and rejects anything else with 400 invalid_digest)."

addedInput schema / properties / tree_id / description

Added value: +"Cache tree id that holds the entry (default \"main\")."

Addedv0.1.4Oct 25, 2026

TDQS

A4.8/5.0

Behavior5/5

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

No annotations, so the description carries the full burden and does so: it discloses destructive/immediate/no-undo semantics, that the action is not billed but forces a billed miss, ownership/inheritance rules (parent-owned entries untouched, shared-bytes loss after promote), plus the full error set (404, 409, 400) and auth/tenant scoping requirements.

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 routing before edge-case ownership and error details. Dense but each sentence carries distinct behavioral information; minor redundancy between 'billed as a miss' in the opening and 'not billed' later could be tightened.

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?

The tool has an output schema, so return values needn't be explained; the description instead covers the non-obvious essentials an agent needs to call it correctly: digest sourcing, tree inheritance, destructive consequences, error codes, and auth scoping. Nothing material 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%, so baseline is 3; the description adds value by naming the digest source and by surfacing the ownership semantics tied to tree_id that the schema only labels 'Cache tree id that holds the entry'. It stops short of adding anything not reinforced elsewhere, but the extra semantic context exceeds the schema baseline.

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 ('Evict'), resource ('one cached response') and scope ('in a cache tree by its request digest'), plus the consequence ('fresh miss sent upstream'). It explicitly distinguishes itself from metrecept_delete_cache_tree, so an agent can route correctly without opening schemas.

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 when-to-use ('drop a stale or wrong cached answer'), where to source the digest (metrecept_list_cache_entries), and an explicit when-not with the named alternative (whole tree -> metrecept_delete_cache_tree). Nothing is left to inference.

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