memory_digest

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

With no annotations provided, the description carries the full behavioral burden and delivers richly: it discloses determinism ('deterministic digest'), internal aggregation mechanics across multiple memory sources, that 'raw source ids are always returned,' that include_related_hops is 'capped at 3,' and that synthesize is 'Reserved for future LLM synthesis. False by default' — a stub parameter clearly flagged. It even explains the debug payload contents. These are behavioral facts absent from the schema and critical for an agent to predict tool behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but length is justified by 14 parameters with 0% schema coverage — the prose is the only parameter documentation. It is well-structured: core purpose, then behavioral context, then the always-returned guarantee, then Args. Every sentence earns its place, though a few lines (e.g., 'Optional metadata filters') are thinner than their siblings. Minor tightening would be possible, but overall it is dense without bloat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a high-complexity tool (14 params, nested objects, no annotations) the description is remarkably complete: it explains what the tool aggregates, what it always returns, all parameter semantics, the future synthesize stub, and fallback behavior. An output schema exists, so the description rightly omits return-value details. The only conceivable gap is explicit sibling routing, which is already covered by the purpose framing. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 0%, so the description must fully compensate — and it does. Every one of the 14 parameters receives semantic elaboration beyond the schema: k bounds both search hits and TODO matches, include_todos explains the matching rules and legacy memora/ prefixes, include_related_hops clarifies the cap, date_from/date_to specify ISO or relative '7d' formats, and seed_ids explains it 'expands lineage/related from' the given ids. This is exemplary compensation for an undocumented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Return a deterministic digest of memories related to a topic.' It immediately distinguishes itself from siblings by framing the tool as an 'aggregation surface... not a narrative generator' and enumerating exactly what it combines (hybrid-search hits, supersession lineage, related ids, TODO/issue memories). This clearly differentiates it from memory_get, memory_list, and memory_hybrid_search without needing to open any sibling schema.

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

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

The description gives clear context for when to use the tool: 'aggregation surface for agents that need current context.' It also provides an implicit when-not ('not a narrative generator') and a fallback hint that callers can 'inspect primitives if the digest is too broad or too narrow.' However, it stops short of naming explicit sibling alternatives (e.g., 'use memory_hybrid_search for raw ranked hits') or stating hard exclusions, so the routing guidance is context rather than explicit alternatives.

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