memory

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

With no annotations, the description carries the full load and does disclose non-obvious effects: content is joined with a timestamp separator and history is tracked, so an agent knows the appended text is not stored verbatim as a standalone blob. It omits failure behavior for an invalid memory_id and whether appends are atomic or idempotent.

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 core semantics in two sentences, then an Args block that repeats the parameters with added meaning. The Args section is somewhat redundant with the schema but earns its place because the schema has no descriptions.

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?

An output schema exists, so return values need not be explained, and the description covers what an annotion-free mutation tool most needs: the shape of the appended content, history tracking, and the source default. Only the error case (memory_id not found) is left unaddressed.

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 compensate, and it does: all three parameters are explained with meaning beyond their titles (content is timestamp-appended, source defaults to the connected client's name). Minor inconsistency: the schema shows source default as empty string while the description says the client name.

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?

States a specific verb and resource ("Append additional context to an existing memory") and adds the operative distinction "without replacing it", which separates it from save_memory/update_memory in spirit. It stops short of naming the sibling it replaces, so an agent must infer that update_memory is the replacement path.

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?

Clear situational context: use this when you want to add to an existing memory rather than overwrite it, and memory_id + content are required so the precondition (memory must exist) is implied. No explicit "when not to use" or named alternative tool, which keeps it below a 5.

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?

With no annotations, the description carries the full load: it correctly discloses that the tool mutates data when dry_run=false and that it is safe by default. It omits irreversibility of deletion, any permission requirements, and the scope/criteria for 'expired', which matter for a destructive operation.

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?

Two short sentences, front-loaded with the action and immediately followed by the safety-critical parameter rule. The 'Args:' docstring formatting is slightly mechanical but costs nothing.

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?

An output schema exists, so return-value explanation is unnecessary, but the definition of 'expired' and the consequences of deletion are left undefined for an unannotated destructive tool. The safety default is covered; the destructive semantics are not fully.

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 define the single parameter, and it does: both true and false behaviors are stated along with the default. It stops short of saying what happens to non-expired memories or whether a preview is required before deletion.

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?

States a specific verb pair ('find and optionally delete') and a specific resource ('expired memories'), which is far more informative than the sibling delete_memory's implied scope. It does not explicitly contrast itself with delete_memory or find_duplicates, so the distinction (bulk, expiry-based cleanup) must be inferred.

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 a clear usage rule for dry_run (default true = list only, false = delete), which implicitly tells the agent to preview first. However, it never says when to prefer this over delete_memory or find_duplicates, nor what qualifies a memory as 'expired'.

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?

No annotations are provided, so the description carries the full burden. It does disclose one important behavior beyond the name — that linked entities are also deleted (a cascade) — but it never says whether the deletion is irreversible, whether confirmation is required, or what happens if memory_id does not exist.

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 purpose sentence is front-loaded and earns its place, but the "Args:" block is docstring boilerplate that duplicates the input schema verbatim, consuming roughly half the text without adding information.

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 output schema covers return values, so that needn't be explained. But for an unannotated destructive operation, the description should address irreversibility/confirmation and post-delete state; the cascade note is a good start that stops short of what an agent needs to act safely.

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 0%, so the description must compensate; it only restates the parameter as "The ID of the memory to delete," adding no format, range, or sourcing hints beyond the integer type in the schema. This is adequate-but-minimal for a single required param.

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?

States a specific verb and resource ("Delete a memory") and adds real scope: "its linked entities." The destructive verb makes it trivially distinguishable from save/append/search/update siblings, though no sibling is named explicitly.

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?

No guidance on when to delete versus update_memory, cleanup_expired, or find_duplicates, which are the plausible adjacent choices in this sibling set. The agent is left to infer that this is a hard removal with cascading effects.

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?

With no annotations, the description discloses some behavioral details: entity_value uses substring matching, and limit has a default of 25 and maximum of 200. However, it omits other relevant traits such as whether the operation is read-only (implied but not stated), error handling, or pagination 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 reasonably concise, with a clear opening sentence and structured parameter list. The 'Args:' formatting is slightly verbose but necessary given the schema lacks descriptions, and the content is 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?

For a simple find tool with three optional parameters, no annotations, and an output schema, the description covers purpose, all parameters, and key behavioral details. A minor gap is not explicitly stating that entity_type and entity_value are optional (though the schema shows defaults).

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 fully compensates by explaining all three parameters with examples and constraints: entity_type with example values, entity_value with substring match and examples, and limit with default and maximum.

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 'Find all memories linked to a specific entity', specifying the verb (find) and resource (memories linked to an entity). It does not explicitly distinguish itself from sibling tools like search_memory or list_memories, which prevents a 5.

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?

No guidance is given on when to use this tool versus alternatives such as search_memory or list_entities. The description only explains parameters, leaving the agent to infer appropriate usage contexts.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that omitting topic triggers an all-memory scan and that grouping is based on shared significant words, but it does not mention read-only/safety characteristics, performance implications of scanning all memories, or what similarity means operationally. The provided behavior is adequate but incomplete for an unannotated 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 front-loaded with the core purpose and mode behavior, then provides compact parameter notes. The Args section partly repeats schema information, but it adds useful details such as the maximum limit and the empty-topic behavior.

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?

An output schema exists, so the description need not explain return values. Given the two optional parameters and dual-mode behavior, the description supplies enough to invoke the tool correctly. It would be stronger with a note on cost/performance when scanning all memories or on how duplicates are judged.

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 compensate, and it does document both parameters: topic is optional and empty means scan all, while limit defaults to 10 and caps at 100. It also clarifies that limit controls results in one mode or groups in the other. It could go further by explaining how topic similarity is matched, but the essentials are covered.

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 a specific verb and resource: finding potentially duplicate memories. It also explains the two operating modes, which differentiates it from a generic memory search. It does not explicitly name or contrast sibling tools such as search_memory or find_by_entity, so it falls short of full sibling differentiation.

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 explains the internal mode selection: provide a topic to find similar memories, or omit it to scan all memories for groups sharing significant words. However, it gives no guidance on when to choose this tool over search_memory, list_memories, or find_by_entity, nor does it state exclusions or prerequisites.

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?

With no annotations, the description must carry the behavioral burden. It does disclose two useful traits beyond structure: results are grouped by category and the date boundary is evaluated in the machine's local timezone, but it says nothing about read-only nature, result volume, ordering, or pagination limits.

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 behavior sentence is front-loaded and the Args block is minimal, with no filler. Slightly more structure than needed for a single optional parameter, but nothing is wasted.

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?

One optional parameter, fully explained, and an output schema exists so return values need no prose. The remaining gap is the ambiguity about ordering and whether "updated" includes deletions or moves, minor for a read-only digest 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?

Schema coverage is 0% — the schema only declares a string with an empty default — so the description has to compensate, and it does: YYYY-MM-DD format, local-timezone interpretation, and a today fallback. The only blemish is that the stated default ("today") doesn't match the schema's empty-string default.

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?

States a specific verb and resource ("Get memories") plus a precise scope ("created or updated on a specific local date") and a result shape ("new ones grouped by category"). It is clearly differentiable from search_memory or list_memories by the date-scoping, though no sibling is named explicitly.

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 "daily" framing plus the today-by-default behavior implies when this tool is the right pick, but it never states when to prefer it over list_memories, get_stats, or search_memory, and gives no exclusions. Usage is inferable rather than instructed.

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?

No annotations are provided, so the description carries the behavioral burden. "Get" implies a read operation, and it usefully discloses that the response includes linked entities and edit history, but it does not state permissions, error behavior, or side-effect guarantees.

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 purpose is front-loaded and the description is short. The separate Args line mostly restates the schema, but overall the text is efficient and not bloated.

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 simple one-parameter read tool with an output schema, the description is largely sufficient: it identifies the resource and describes the returned content composition. The main remaining gap is sibling routing, especially relative to get_memory_history and search_memory.

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?

There is one required parameter and schema description coverage is 0%, so the description must compensate. The Args line identifies memory_id as "The ID of the memory to retrieve", which is correct but only minimally expands on the 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 uses a specific verb and resource: "Get the full content of a specific memory", and adds scope details (linked entities and edit history). It does not explicitly differentiate itself from overlapping siblings such as get_memory_history or search_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 implies retrieval by memory_id but gives no explicit when-to-use guidance, exclusions, or alternative recommendations. This is notable because get_memory_history is a close sibling and the description even mentions edit history without explaining why one should choose get_memory over the history tool.

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?

With no annotations, the description carries the full burden. It does add real information beyond the name — that append and update operations are recorded and replaced content is retained — but says nothing about ordering, completeness, retention limits, or behavior when the memory_id does not exist. Read-only behavior is only implied by 'Get'.

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 opening sentence is well front-loaded and earns its place. The trailing 'Args:' block is redundant boilerplate that duplicates the schema without adding meaning, which weakens an otherwise tight description.

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 output schema covers return shape, so the description needn't explain history entries. For a single-required-parameter read tool, stating what the history contains and that it spans edits and appends is enough to call it 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?

Schema description coverage is 0% for the single parameter, so the description must compensate. Instead the Args block is a tautological restatement ('memory_id: The ID of the memory') with no ID format, source, or valid-value guidance beyond the integer type already in the 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?

States a specific verb+resource ('Get the full edit/append history of a memory') and adds a scope detail — it includes content replaced by update_memory — which implicitly distinguishes it from get_memory. It does not name get_memory explicitly, so the sibling differentiation is suggestive rather than 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?

Usage is implied: use this when you need prior versions/edits rather than the current memory state, and the mention of update_memory gestures at the relevant workflow. There is no explicit 'use X instead when' statement or prerequisite guidance.

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?

No annotations, so the description carries the burden. 'Get' implies a safe read and the enumerated outputs hint at an aggregate scan over the whole store, but it doesn't state scope (all memories?), cost, or that nothing is mutated. Adequate but not rich behavioral context.

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?

One front-loaded sentence with a compact, comma-separated inventory of the returned aggregates. No filler, no repetition of the tool name.

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?

With an output schema present and no parameters, the description only needed to signal scope and content, which it does. Minor gap: it doesn't say the stats cover the entire memory store versus a filtered subset, which would matter for interpretation.

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?

Zero parameters, which is the baseline-4 case; the description correctly implies no input is needed to scope the call. Nothing more is required on this dimension.

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?

States a specific verb (get) and resource (overview stats), then enumerates the exact aggregates returned: totals, category/importance breakdowns, top entities, threads, expired count. This clearly distinguishes it from CRUD siblings like list_memories or search_memory, though it never explicitly says 'read-only aggregate'.

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?

Usage is only implied — an agent can infer this is the dashboard/overview entry point rather than a filtered query. No explicit when-to-use versus alternatives (e.g., get_daily_summary, list_memories) or exclusions are given.

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?

With no annotations, the description carries the full burden; it does disclose the chronological ordering of results, which is real behavioral context the schema does not express. However, it says nothing about whether the call is read-only, what happens with an unknown/empty thread_id, whether results are capped or paginated, or any ordering ties — notable omissions for an unannotated 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?

One front-loaded sentence establishes the operation, scope, and ordering, followed by a compact args block whose only content beyond the schema is the useful example formats. Nothing is padded.

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 output schema is present, so return-value explanation is not required, and one parameter is well covered. Still missing for a retrieval tool in a 15-tool family: how to discover a thread_id, behavior on missing threads, and whether result sets are bounded — gaps an agent could hit immediately.

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 0%, so the description must compensate for the single parameter — and it does, both labelling thread_id and giving two concrete format examples ("incident-2026-03-24", "stock-analysis-march") that convey the naming convention. It stops short of saying whether the ID is case-sensitive or how to obtain one via list_threads.

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?

States a specific verb and resource — retrieve all memories belonging to a conversation thread — plus a distinguishing scope (whole thread, not a single memory) and ordering guarantee (chronological). It does not name a sibling such as get_memory or search_memory to sharpen the boundary, so it stops short of a 5.

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?

Usage is only implied: you call this when you already have a thread_id and want that thread's full contents. There is no explicit guidance contrasting it with list_threads (to discover thread IDs), search_memory (query-based retrieval), or get_memory (single record), and no stated 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?

No annotations are provided, so the description carries the burden. 'List' strongly implies a read-only, non-mutating operation and the output schema covers the return shape, but nothing is said about ordering, pagination, scope of 'unique' (global vs per-workspace), or whether an invalid entity_type errors or returns empty.

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?

Two front-loaded sentences plus a short Args block; nothing is padded. The args section slightly restates the prose but adds the example values, so it earns its place.

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?

A single-optional-parameter read tool with an output schema needs little more than what is here: a clear purpose, an optional filter explained with examples. Missing only edge-case behavior for the filter, which is minor given the output schema documents the response.

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 0% — the only parameter has just a title and an empty-string default — so the description must compensate, and it does: it marks entity_type optional and gives concrete example values ('person', 'service'). It stops short of saying what an empty or unrecognized type does, keeping it out of 5 territory.

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?

States a specific verb+resource ('List all unique entities') with the filtering scope called out, and adds a one-line rationale ('see what/who has been referenced'). It reads clearly against siblings like list_memories and find_by_entity, though it never explicitly contrasts itself with find_by_entity, which is the nearest neighbor.

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?

'Useful to see what/who has been referenced' implies the discovery use case, but there is no explicit when-to-use vs when-to-use-an-alternative guidance (e.g., versus find_by_entity or list_memories). Usage is inferable rather than stated.

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?

With no annotations, the description carries the full burden but only partially succeeds. It discloses that expired memories are excluded by default and that limit has a max of 200, which is useful behavioral context. However, it does not mention whether the operation is read-only (though implied), sorting behavior, or any other side effects.

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 front-loaded with the main purpose and then lists parameters in a structured, easy-to-scan format. Every sentence and argument description earns its place; there is no redundant or filler content.

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 has five optional parameters and an output schema (so return values need no explanation), the description is mostly complete. It covers purpose, filters, and defaults. Minor gaps include sorting behavior or whether the limit applies before or after filtering, but these are not critical 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 compensate. It provides clear explanations for all five parameters, including defaults for limit and include_expired. It could be more specific (e.g., format, case sensitivity), but it covers the essential meaning of each parameter.

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 a specific verb (list) and resource (memories) with optional filters. It is distinct from siblings like search_memory or get_memory, but it does not explicitly differentiate itself from those alternatives.

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 implies usage through optional filters and the default exclusion of expired memories, but it provides no explicit guidance on when to use this tool versus search_memory, get_memory, or find_by_entity. It is minimum viable but lacks clear alternatives.

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?

No annotations are provided, so the description carries the full burden. It does disclose the payload shape (memory counts, latest activity), but omits scope questions an agent would care about: whether threads span all users/workspaces, whether results are paginated, or whether any permission is required.

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?

A single front-loaded sentence with zero filler that conveys both the action and the returned fields. Nothing could be removed without losing information.

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?

With an output schema present and no parameters, the description need not detail return values or argument syntax. It is nearly complete for a simple read tool, with only the scope/pagination question left open.

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 tool takes zero parameters, so there is nothing for the description to explain and the baseline 4 applies. The description correctly signals that no arguments are needed by framing it as a list-all operation.

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?

States a specific verb and resource ('List all conversation threads') plus what it returns (memory counts and latest activity). It is clearly distinguishable from get_thread by being a bulk listing, but it never names that sibling to make 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?

'List all' implies this is the unfiltered, enumerate-everything tool, which hints that get_thread is for single-thread retrieval. However, there is no explicit when-to-use or when-not-to-use statement and no mention of alternatives anywhere in the description.

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?

With no annotations, the description carries the burden itself: it discloses that duplicates only produce a warning (not a rejection), that configured auto-tags are added, and that source defaults to the connected client name. It still leaves out things like retention/permission behavior and what happens if duplicates are confirmed, so it is strong but not exhaustive.

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 one-line summary and the append_memory pointer are front-loaded before the Args block. The Args list is long but every entry adds information the bare schema lacks; only the illustrative examples could be trimmed.

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 9-param write tool with no annotations, the description covers all parameters plus the two non-obvious behaviors (duplicate warning, auto-tagging). An output schema exists so return values need not be explained; the remaining gap is around overwrite/update semantics versus update_memory.

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 compensate — and it does, documenting all nine params with the allowed category and importance values, a comma-separated tags format, a default for source, the thread-linking convention, and a concrete entities JSON example.

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?

States a specific verb and resource ('Save a piece of context/memory for future conversations') and names the sibling it overlaps with ('consider append_memory instead'), so an agent can tell it apart from append_memory/update_memory without opening schemas.

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?

Gives one explicit routing rule — if the content likely duplicates an existing memory, use append_memory — which is exactly the decision an agent faces here. It does not say when to prefer update_memory or whether to search first, so it falls short of full when/when-not coverage.

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?

With no annotations at all, the description carries the full burden and does well: it discloses the ranking model (topic and tag matches rank highest), the substring fallback path, the default exclusion of expired memories, and that snippets rather than full text are returned. Missing are read-only framing, pagination/result-cap behavior beyond 'limit max: 100', and whether results are ordered deterministically.

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 mechanism and the sibling hand-off before the parameter block, and every line of the Args block corresponds to a real parameter. Slightly long, but nothing is padding; the structured Args list is easier to scan than prose would be.

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?

A six-parameter tool with an output schema, so return-value documentation is correctly omitted; the description still covers defaults, exclusion behavior, and fallback semantics. What's left unsaid is minor: ordering guarantees and whether the result cap interacts with the snippet size.

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 0% (only titles and defaults), so the description must compensate and it does for all six parameters: query accepts plain words, hyphenated names, IDs, or FTS5 syntax with a concrete example ('tags:aws', 'datadog OR sentry'); importance takes low/normal/high/critical; limit default 10 max 100; include_expired and full_content defaults stated. This adds real meaning the schema does not carry.

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?

States a specific verb and resource plus the retrieval mechanism: 'Search memories by relevance: full-text search with stemming ... falling back to substring matching.' It also explicitly distinguishes itself from get_memory ('use get_memory for the full text') and implicitly from list_memories by being relevance-ranked search.

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?

Gives an explicit alternative for the full-text case ('use get_memory for the full text') and states the default exclusion of expired memories with an override flag. It does not cover other plausible alternatives such as find_by_entity or list_memories/navigation, so the routing picture is clear but not exhaustive.

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?

With no annotations at all, the description carries the full burden and does well: it discloses partial-update semantics, that empty string means 'keep existing' (non-obvious given the schema defaults), and that replaced content is preserved in history retrievable via get_memory_history — which materially softens the destructive risk. It does not state permission requirements or what happens on invalid memory_id, so it is not exhaustive.

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 critical semantics (partial update, history retention, append alternative) are front-loaded in the first two sentences. The Args block is somewhat redundant with the schema property names, but each line adds the 'leave empty to keep existing' rule, so it earns most of its space.

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?

An output schema exists, so return values need no explanation. For an 8-parameter mutation tool with zero annotation coverage, the description supplies the behaviors that matter (partial update, history retention, sibling routing); the remaining gap is value formats for tags/importance/expires_at.

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 compensate, and it names all 8 parameters with meaningful semantics ('leave empty to keep existing'), which is essential because the schema gives them empty-string defaults but no descriptions. It stops short of format details — tags delimiter, importance scale, expires_at date format — which remain undocumented anywhere.

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 ('Update an existing memory') and immediately qualifies it as a partial update ('Only provided fields are updated'), then names the sibling append_memory as the contrasting behavior. An agent can tell update vs append apart without inspecting either 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?

It gives an explicit routing rule: use append_memory to add context without replacing. That is a real when-to-use/alternative statement. It does not cover other adjacent siblings (delete_memory, save_memory) or prerequisites such as whether the memory must already exist, so it falls short of a full 5.

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