mcp_engram_query_with_momentum

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

No annotations are provided, so the description carries the full burden for behavioral transparency. It does disclose the ranking algorithm (80/20 blend and α re-weight) and mentions filter behavior, which is useful. However, it does not explicitly state that this is a read-only operation, what the return format is, or any side effects. For a query tool, this is a gap, though less severe than for a mutating tool.

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 a single paragraph with the core idea front-loaded and a distinct 'WHEN TO USE' section that improves scannability. However, it contains unexplained internal references like 'RSI Cycle 24' and 'goal-edge α' that an agent may not parse, and the phrasing could be tightened. Overall, it is efficient and well-structured, not overly verbose.

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?

There is no output schema, so the description should clarify what the tool returns. It implies it returns memory results (indicated by 'recall' and the k parameter), but does not explicitly state the return format or any additional behavior like pagination or sorting. Given the moderate complexity (4 parameters, no annotations), the description is adequate but leaves room for more completeness.

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 coverage is 100%, with each parameter already having a clear description. The description's explanation of alpha_weighted and zedos_filter largely repeats schema information or introduces opaque jargon (e.g., 'edge_volatility_scale', 'RSI Cycle 24') that adds little clarity. It does add context about the 80/20 blending, but not enough to elevate the score beyond the baseline.

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 clearly identifies the tool as 'Momentum-assisted recall' and specifies its core function: blending semantic similarity (q tensor, 80%) with conceptual trajectory (p tensor, 20%). It also distinguishes itself from the sibling tool mcp_engram_recall by explicitly stating 'WHEN TO USE INSTEAD OF recall', making the purpose unmistakable.

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 provides explicit usage guidance: 'WHEN TO USE INSTEAD OF recall: When you want concepts that are actively changing or evolving. Use regular recall for stable crystallized knowledge.' This clearly states when to use this tool versus the alternative. It also notes zedos_filter support including 'training', adding practical usage context.

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