memory_store

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

With no annotations provided, the description itself reveals key behaviors: near-duplicates are dropped with 'stored=False, reason="below_surprise_threshold"', and the return object includes 'stored, surprise, reason, cortex_promoted'. This goes beyond the basic 'store' semantics. However, it does not explain the meaning of 'surprise' or 'cortex_promoted', nor any side effects beyond persistence, so it stops short of complete transparency.

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 well-organized: a one-line purpose, then usage rationale, then duplicate-handling detail, a pointer to an alternative, a compact Args block, and Returns. Every sentence carries distinct information, with no filler or redundancy.

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?

Given the tool's moderate complexity (5 params, no annotations), the description covers the main usage scenarios, return format, and duplicate behavior. It does not explain the semantics of 'surprise' or 'cortex_promoted', which an agent might need to fully interpret the result, but the overall guidance is sufficient for correct invocation.

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 carry the parameter meaning. It does: each argument (text, source, tags, origin, episode) gets a concise purpose, e.g., 'source: Stable per-project/topic tag for later filtering.' This is a strong compensation. It misses noting schema defaults (e.g., source defaults to 'agent'), but the core semantics are provided.

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 'Store one durable fact, decision, or observation', which is a specific verb+resource statement. It clearly distinguishes the tool from siblings by explicitly pointing to 'memory_fact_set' as the canonical alternative for NOW facts, and by noting near-duplicate handling as a unique behavior.

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 explicitly states when to use the tool: 'Use proactively for anything worth keeping — one claim per call.' It also names an alternative: 'For canonical NOW use memory_fact_set.' This gives clear when/alternative guidance, satisfying the criterion fully.

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