kuma_kuma_memory

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

With no annotations, the description carries the full behavioral burden. It does disclose useful traits that go beyond the schema: records persist across sessions, arch_flow is scoped to a max of 5 core files, and gotcha_resolve archives rather than deletes. It says nothing about permission needs, overwrite/dedupe behavior, or failure modes, which is a real gap 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?

Front-loaded with the value proposition, then a tight action list with parenthetical triggers; every sentence earns its place. Slight redundancy in restating the action semantics that the enum already defines, but no padding overall.

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 17-parameter, 7-action tool with no annotations and no output schema, the description covers action selection well but leaves important holes: the format of the 'record' JSON string for research_save, which parameters are required per action, and what any action returns. Adequate but not complete.

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 100% and the action enum already documents each mode, so the schema does the heavy lifting — baseline 3. The description adds action-level intent but no parameter linkage (e.g., which params pair with gotcha_resolve or research_save's 'record' JSON string).

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 states a specific resource (persistent knowledge/memory store) and enumerates the seven core actions, so an agent understands it is a write/read memory tool with per-action intent. It does not, however, distinguish itself from the confusingly similar siblings kuma_memory and kuma_kuma_context, which matters a lot when names differ by one token.

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?

Strong per-action triggers are given ('IMMEDIATELY when you find a bug/quirk', 'when choosing between options', 'after tracing a complete flow, max 5 core files'), and there is an explicit exclusion: don't record what grep/glob answers faster. What is missing is routing against alternatives — there is no mention of when to use a sibling such as kuma_memory or kuma_context instead.

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