Moltline Recall

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

Even though annotations already declare readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral context: how relations with since/until are filtered, how half-life decay works exponentially, the specific return fields (dropped, decayed), and the error-handling contract (never raises protocol error, returns a structured error object). This goes well beyond the annotations.

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-structured and appropriately sized for the tool's complexity. It starts with a one-sentence summary, then details the filtering/decay mechanics, provides an example, gives usage vs. alternative guidance, and covers error handling. Every sentence contributes unique value without redundancy or filler.

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?

The description covers the tool's core behavior, parameters, return structure, error handling, use cases, and relationship to siblings. Given the complexity of the tool (nested objects, optional decay, error responses) and the available annotations/schema, this description leaves no significant gaps for an agent to misuse the tool.

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?

The schema already provides 100% coverage for all three parameters, so the baseline is 3. The description enhances this by giving a typical input/output example that ties the parameters together, explaining the effect of half_life_days on confidence (exponential decay), and showing how as_of interacts with the graph. This adds semantic meaning beyond the schema definitions.

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 clear statement: 'See the memory as it stood on a given day, optionally faded by age.' This specifies the resource (memory graph), the temporal scope (as of a date), and the optional age-fading behavior. It also distinguishes itself from graph_diff explicitly, clarifying its unique purpose among sibling tools.

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: 'Use when the answer depends on when you ask. Not for what changed between two points - that is graph_diff, which does not need dates at all.' This tells the agent exactly when to choose this tool over alternatives, including a named alternative and the condition for exclusion.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds substantial behavioral context: the ranking criteria ('degree, then observation count, then name'), the response shape with kept/dropped counts, that it never raises protocol errors but returns an error object, and that retries are safe after input correction. This is rich, non-redundant 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 dense but remarkably efficient: a one-sentence purpose, a concrete example, usage boundaries, and error behavior. Every sentence adds information; there is no filler or repetition of the schema, and the most important points are front-loaded.

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 rich annotations, full schema coverage, and output schema, the description still manages to fill all important gaps: return format, ranking algorithm, error semantics, idempotence reassurance, and a realistic usage example. There is no missing context an agent would need 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?

The input schema already documents all three parameters (graph, max_entities, keep) with descriptions, defaults, and constraints, so the baseline is high. The description adds meaningful usage semantics by showing a typical input/output example and explaining what 'keep' means behaviorally ('keeps anything you name outright') and how ranking works, which goes beyond the schema's mechanical definitions.

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 defines the tool as 'Shrink a memory to the part that still earns its place' and details exactly what happens: ranking entities, keeping named ones, and dropping the rest with their relations. It explicitly distinguishes this from sibling tools like graph_lint, which is for finding wrong facts.

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 explicit when-to-use guidance ('Use when a graph has outgrown the context you can spend on it') and when-not-to-use guidance ('Not for removing wrong facts - graph_lint finds those'). It also names the alternative tool, making the usage boundary crisp.

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

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

While annotations already declare read-only and idempotent, the description adds error-handling behavior: 'never raises a protocol error — it returns an error object.' It also hints at retry safety: 'it is always safe to retry,' which goes beyond the structured annotations.

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-structured and front-loaded with a clear purpose statement. It's a bit long but each sentence provides value, such as usage, error semantics, and idempotency. Slightly verbose but justified.

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?

Covers purpose, use cases, non-use cases, error behavior, retry guidance, and includes an output example. With annotations and output schema already present, this description is comprehensive and 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 coverage is 100% with clear descriptions for 'before' and 'after'. The description adds a concrete JSON example showing expected structure, but this is more illustrative than adding new semantic meaning. Meets the baseline without adding significant parameter-specific insights.

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 'Say exactly what changed between two versions of a memory,' a specific verb+resource that clearly defines the tool's purpose. It differentiates from siblings by stating 'Not for merging the two' and pointing to graph_upsert, making the distinction explicit.

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?

It gives explicit use cases: 'Use after an upsert... or between two agents.' It also states what not to use it for and directs to an alternative: 'feed the differences back through graph_upsert for that.'

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description does not contradict these. It adds value by stating the tool never raises a protocol error on invalid input, instead returning an error object with corrective guidance. It also reiterates 'Every call is read-only and idempotent, so after correcting the input it is always safe to retry,' which reinforces the idempotentHint and provides extra context about retry safety.

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 concise and well-structured. It opens with a strong purpose statement, lists concrete issues, provides an example, gives usage timing, explicitly names exclusions, and describes error behavior. Every sentence adds useful information without redundancy. It earns its length.

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 complexity (checking multiple graph issues), the presence of annotations, and the output schema, the description provides complete context. It covers what the tool does, when to use it, what to expect as output, error behavior, and side-effect safety. The example output clarifies the return structure, making the tool easy to call correctly.

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?

The schema has 100% coverage for the single parameter, describing it as 'The graph document to check.' The description goes beyond this by showing the typical input format {"graph": {...}} and the expected output structure, giving the agent a realistic sense of what to pass and what to expect back. This adds meaning beyond the schema's minimal description.

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 states the tool's purpose: 'Find the breaks a memory graph accumulates as it grows.' It enumerates specific issues (dangling relations, orphan entities, near-duplicate names, contradictions) and provides a concrete input/output example. This distinguishes it from siblings like graph_diff and graph_compact.

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: 'Use before trusting a graph you did not build, or on a schedule as memory grows.' It also explicitly names alternatives and what the tool is NOT for: 'Not for comparing two graphs (graph_diff) and not for shrinking one (graph_compact).' This provides clear usage guidance and exclusions.

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

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

Beyond the annotations (read-only, idempotent), the description reveals scoring logic, neighbourhood inclusion, exact word matching, and error behavior (never raises protocol errors, returns error objects). It also states 'Every call is read-only and idempotent,' reinforcing the annotations, and explains the rationale behind neighbourhood pulls.

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 concise yet packed with information: a clear opening line, a concrete example, usage guidance, and error handling—all in about 150 words. Every sentence earns its place without redundancy, making it highly effective.

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 complexity and the presence of an output schema, the description covers essential aspects: purpose, scoring, hops semantics, error behavior, and safety guarantees. It addresses potential pitfalls (e.g., invalid input) and provides a complete mental model for correct usage.

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?

While the schema fully describes parameters, the description enriches query semantics with 'Matching is on whole lowercase words' and explains hops with '0 returns matches only.' The example ties graph, query, and hops together, providing practical meaning beyond mere schema definitions.

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 states the tool's purpose: 'Find what the graph knows about something, plus its neighbourhood.' It uses a specific verb ('Find') and resource ('the graph'), then elaborates with scoring and hop-based expansion. It also distinguishes from siblings by explicitly mentioning graph_upsert and graph_at_time, leaving no ambiguity about its role.

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?

Explicit usage guidance is provided: 'Use to read memory back before answering. Not for writing (graph_upsert) and not for narrowing by date, which graph_at_time does.' This directly tells when to use this tool versus alternatives, and the error-handling note adds when retries are safe.

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

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

It discloses idempotency, read-only behavior (which matches annotations), error handling (returns error object instead of raising), and output structure. It goes beyond annotations by detailing error responses.

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 lengthy and includes some redundant statements (e.g., 'Every call is read-only and idempotent' appears twice). However, it is structured with a clear opening and provides comprehensive details, though it could be streamlined.

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 complexity of the tool and the presence of an output schema, the description covers usage, error handling, idempotency, and differentiation from siblings, making it sufficiently complete for an agent.

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?

The schema already provides descriptions for each parameter, including details on appending observations and deduplication. The tool description adds the idempotency aspect which affects parameter behavior, but not much else.

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 states that it folds new facts into a memory graph and returns the whole graph, using the verb 'fold' as an upsert action. It also identifies it as the single write path for memory.

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?

It explicitly states when to use (single write path) and when not to use, directing to graph_search for reading and graph_diff for change detection. Also mentions idempotency for safe retries.

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