Shared Agent Memory

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

Annotations already declare the write/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's main remaining job is to disclose edge behavior — duplicate handling, what entityName must match, what happens on unknown entities. None of that appears. Worse, the one behavioral claim present ("Legacy deletion is logical and retained in history") describes deletion on a tool that adds observations, which misdirects rather than informs; it is consistent with destructiveHint=false but irrelevant here.

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 text is short but badly front-loaded: the leading sentence is about the storage backend rather than the operation. The final sentence concerns deletion, which does not belong in an add tool's description and consumes one-third of the available space with off-target 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?

For a mutation tool with a nested-object array parameter, no output schema, and no parameter descriptions, the description needs to carry substantial weight — and it does not. The only genuinely useful information (shared v2 SQLite store, prefer native tools) is swamped by an unexplained deletion clause that raises more questions than it answers.

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% and the description adds nothing about the single `observations` array parameter — not its shape, the entityName/contents pairing, the 100-item and 20000-char bounds, nor whether entities must pre-exist. The definition entirely abandons the agent to reading the raw schema, and the key ambiguity (does add_observations create the entity or fail if missing?) is left unanswered.

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 never states what the tool does — the name 'add_observations' is the only clue that observations are being added, and the text never confirms it. It spends its sentences on implementation provenance ("backed by the same v2 SQLite store") and deprecation framing instead of a verb+resource statement. An agent cannot tell from the text alone whether this reads, writes, or deletes.

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?

"New callers should prefer versioned native memory tools" is real steering away from this tool, which is more than most definitions offer. But it names no specific alternative among the many siblings (remember_memory, create_entities, etc.), and it gives no condition under which this legacy path IS the right call. The exclusion is implied rather than actionable.

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?

Adds substantive behavior beyond the annotations: corrections are revision-checked and stale writes are rejected (optimistic concurrency), and prior content is preserved in history. The history-retention note is consistent with destructiveHint=false and the verb is consistent with readOnlyHint=false and idempotentHint=false. Missing only what the rejection failure looks like to the caller.

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?

Three short sentences, front-loaded with the action, then outcome and side effect. No filler; the only thing not earning its place is the slightly redundant second clause about subsequent corrections.

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 the core correction semantics well, but for a 9-parameter mutation with no output schema and no parameter descriptions, the agent still cannot infer what attribution, occurred_at, request_key or source_* are for, or what a successful response contains.

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% across 9 parameters, so the description carries the full burden. It explains `id` and `expected_revision` only indirectly via "returned id and revision", and says nothing about content, reason, attribution, occurred_at, request_key, or the two source_* parameters.

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: replace an active memory with a new revision. It clearly reads as an update/correction operation rather than a create, which implicitly separates it from remember_memory, but it never names a sibling or scopes itself explicitly against forget_memory or memory_history.

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 real guidance on the correction workflow (reuse the returned id and revision, stale writers rejected), which tells the agent how to chain calls. It does not say when to choose this over remember_memory or forget_memory, nor what preconditions must hold beyond "active memory".

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?

Annotations already declare this is a non-idempotent write that is not destructive; the description adds useful context that the tool is legacy/compatibility and writes to the same v2 SQLite store, which tells an agent its data is not isolated. The sentence about logical, history-retained deletion is off-topic for a create tool and muddies rather than clarifies creation semantics (e.g. duplicate handling).

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?

Three short sentences with no padding, but they are front-loaded on deprecation status rather than the operation, and the deletion sentence does not earn its place in a create tool's 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?

For a write tool with a nested, undocumented parameter and no output schema, the description should explain what gets persisted and what happens on name collisions. It omits both, and its mention of deletion history is irrelevant to this operation.

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% and the single `entities` parameter is a nested array of objects with required name/entityType/observations. The description says nothing about these fields, their meaning, the 100-item caps, or whether observations are appended or replaced, so it fails to compensate for the coverage gap.

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 never states what the tool does. It talks about being a 'compatibility tool backed by the same v2 SQLite store' and about legacy deletion, but never says it creates entities, observations, or anything at all. An agent must infer the operation from the name alone.

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?

'New callers should prefer versioned native memory tools' is a genuine when-not-to-use signal that steers agents toward alternatives. However, it never names the specific replacement among the many siblings (remember_memory, create_relations, etc.) and never says when this tool IS the right choice.

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?

Annotations already declare readOnly=false, idempotent=false, destructive=false, so the description need not restate the safety profile. What it adds instead is mostly non-actionable ('backed by the same v2 SQLite store') or off-topic — the sentence about logical deletion and retained history describes delete_relations behavior, not a create operation. Nothing is said about what happens on duplicate or conflicting relations, or about partial failure in a batch, which is the real behavioral risk here.

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?

Three short sentences with little padding, so it is not bloated. But it is poorly front-loaded: the leading sentence is provenance trivia rather than the operation, and the final sentence concerns a different tool family entirely. Structure wastes the position of highest attention.

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?

This is a mutating batch tool with no output schema, no annotation coverage of semantics, and a fully undocumented nested parameter. The definition should at minimum say what a relation is, whether endpoints must pre-exist, and what a successful response confirms; it says none of that. An agent could call it, but could not call it correctly with confidence.

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% and the single parameter is a nested array of objects with from/to/relationType, none of which is explained in the description. The description provides no meaning for these fields, no note that up to 100 relations can be submitted per call, and no guidance on valid relationType values. With zero coverage in the schema, the description had the full burden and did not carry it.

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 never states that this tool creates relations between entities; it only labels itself a 'compatibility tool backed by the same v2 SQLite store'. The actual verb+resource pairing exists only in the name, so an agent must infer the purpose rather than read it. It does hint at being a legacy analog of newer memory tools, but that is context, not a statement of what it does.

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?

'New callers should prefer versioned native memory tools' is a genuine when-not-to-use signal, which is more than most definitions offer. However, it never names the concrete alternative among the many siblings (create_entities, remember_memory, add_observations), so the agent cannot route deterministically. There is also no statement of prerequisites, such as whether the referenced entities must already exist.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description doesn't need to re-establish that it mutates. It does add real value beyond them: the deletion is logical rather than physical and remains in history, which materially changes how an agent reasons about recoverability.

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?

Three short sentences, no filler, with the compatibility status front-loaded so the agent learns the routing rule before the behavioral caveat. Slightly better ordering would put the soft-delete semantics first for anyone who has already decided to call it.

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 destructive, non-idempotent mutation with no output schema and zero parameter documentation, the description covers the two highest-value facts (soft delete, prefer alternatives) but is silent on return values, behavior for nonexistent names, and batch semantics. Adequate to avoid misuse, not complete to call confidently.

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 required parameter, so the description carries the full burden and provides nothing: no mention of entity names, the 100-item cap, or per-item length limits. The agent gets no guidance on what to pass or how failures on unknown names behave.

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 signals deletion and identifies the tool as a legacy compatibility shim over the v2 SQLite store, but it never states the resource being deleted (entities) or that the operation targets a list of names. An agent knows it's 'a deletion' but must infer what it deletes from the tool name alone.

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?

"New callers should prefer versioned native memory tools" is an explicit when-not-to-use signal with a named alternative direction. It stops short of naming a specific sibling (e.g. forget_memory), so the routing is clear but not fully concrete.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the description earns credit for adding that deletion is logical and retained in history — a crucial nuance for an otherwise destructive-looking operation. It does not add auth, limits, or output detail, but it meaningfully explains the destruction model.

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?

Three short sentences with no filler; the compatibility context, the preference rule, and the logical-deletion behavior are each stated once. Slightly better front-loading of what the tool does would help, but it is compact.

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 destructive legacy mutation tool with no output schema, the description covers deprecation status and deletion semantics but leaves the complex deletions payload entirely unexplained. An agent can decide whether to use it but not how to call it correctly without reading the schema.

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% and the single parameter is a nested array of entityName plus observations with per-item limits. The description says nothing about this structure, so an agent must open the schema to learn what to pass.

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 frames the tool as a legacy compatibility path for deletion but never states plainly that it deletes observations for an entity; the resource is only inferred from the tool name. It does distinguish itself from newer native memory tools, which helps, but the core verb+resource statement is left implicit.

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?

"New callers should prefer versioned native memory tools" is a clear routing rule that steers agents away from this tool toward siblings like forget_memory. What is missing is a positive statement of when legacy callers should still use it, but the alternative is named explicitly.

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?

Adds real context beyond the annotations: deletion is logical rather than physical, records are retained in history, and the store is shared with v2 tooling. That materially changes how an agent should reason about reversibility and auditability, which annotations (destructiveHint=true) alone would obscure. It still omits failure behavior and whether the batch is atomic.

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?

Three short sentences with no filler, and the migration warning is placed early so an agent reads it before deciding to call. The opening clause about the SQLite backend is slightly less useful than a statement of what the tool does, but overall it is tight.

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 destructive, non-idempotent batch mutation with no output schema and zero parameter documentation, the description is under-specified: no statement of the operation itself, no all-or-nothing semantics, no mention of how partial or missing relations are handled, and no indication of what the call returns.

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%, and the single `relations` parameter is a nested array of {from, to, relationType} triples capped at 100 items. The description says nothing about this structure, the batch limit, what happens to triples that don't exist, or whether the whole array is applied atomically.

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 never states the actual operation; the agent has to infer 'deletes relations' from the tool name plus the phrase 'legacy deletion.' It frames the tool as a compatibility shim rather than describing the verb+resource, and it does not distinguish it from siblings like forget_memory or delete_entities.

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?

There is a genuine routing hint — 'new callers should prefer versioned native memory tools' — which tells the agent this is a fallback. However, it never names which sibling to prefer, nor states the condition under which this tool remains the right choice (legacy callers, existing relation triples).

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?

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false; the description usefully adds that content persists in SQLite and Markdown history, which is real context about what is and isn't destroyed. However, the significant behavioral risk of this tool — that a required expected_revision can cause the call to fail on a stale revision, and that request_key affects retry deduplication — is never mentioned.

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 clauses, front-loaded with the core action followed immediately by the crucial retention caveat. Every phrase earns its place and 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?

With no output schema and 0% parameter documentation, the description covers the semantics of the deletion well but leaves the agent without the concurrency/idempotency model needed to call it reliably. Adequate for understanding the effect, incomplete for executing the call.

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% across four parameters, so the description must carry the load, and it explains none of them. 'Active revision' loosely gestures at expected_revision, but reason, request_key (deduplication) and id are entirely unexplained, leaving the two non-obvious parameters opaque.

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 verb+scope: logically delete the active revision, which clearly separates 'forget' (soft delete) from physical deletion. It does not name the sibling tools it competes with (correct_memory, delete_entities, forget vs. history), so it stops 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?

There is no statement of when to choose this over correct_memory (fix a value) or memory_history (inspect) or delete_entities, which is exactly the ambiguity a 'forget' tool creates in this sibling set. The only guidance is an implied contrast with physical erasure, not a selection rule.

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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond them: a hard cap of 100 revisions and the fact that soft-deleted/superseded entries are still returned, which affects how an agent interprets results. It stops short of describing ordering or pagination.

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 no filler; the most decision-relevant detail (including deleted and superseded records) comes before the read completes.

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 only two parameters and no output schema, the definition is serviceable but leaves gaps: return ordering, whether deleted records are flagged in the response, and how the caller should interpret a truncated result at the 100 cap are all 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 carry the load. 'Up to 100 revisions' implicitly explains the limit parameter's maximum, but neither the purpose of 'id' (memory id vs. chain id) nor the meaning of limit as a narrowing control is spelled out.

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 ('Read ... revisions of a memory chain') plus the notable scope that deleted and superseded records are included. This clearly separates it from retrieval siblings like search_memories or memory_status, though it never names a sibling 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?

Usage is implied rather than stated: the mention of deleted and superseded records signals an audit/version-history use case. There is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as memory_status or read_graph for current state.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds useful value by clarifying that no memory content or filesystem paths are revealed, which is real behavioral context. However, it does not describe what 'status' comprises or whether counts are approximate or scoped.

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 compact sentence with the core purpose front-loaded. Every clause earns its place. Slightly penalized only because the brevity comes at the cost of any usage or return-value detail.

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 no output schema, the description must carry the burden of explaining what comes back, and 'status and counts' is vague. It is complete on safety scope and inputs but leaves the return shape underspecified for a tool whose only output is status information.

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 the baseline is 4. There is no parameter ambiguity to resolve, and the description correctly implies no input is required.

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: reading non-secret store status and counts, with an explicit scope exclusion ('does not expose memory content or paths'). This clearly distinguishes it from siblings like read_graph, search_memories, and memory_history. It stops short of 5 because 'store status and counts' remains slightly abstract about what is actually reported.

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 indication of when an agent should call this versus alternatives such as read_graph or memory_history. There are no prerequisites, triggers, or exclusions stated beyond the content-exposure caveat.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds a useful performance warning ("may be large") and storage backing, but does not disclose what happens to names that don't exist, whether results preserve input order, or any truncation behavior — relevant here since the schema caps names at 100 items.

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?

It is short (two sentences) but front-loads the vague "Compatibility tool" rather than the operation, and "backed by the same v2 SQLite store" consumes a clause without helping an agent decide to call it.

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 no output schema and no parameter descriptions, the description must explain what a call returns and what input shape is expected; it does neither, leaving an agent unable to predict results or name format beyond the raw array-of-strings schema.

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 sole parameter, "names", has 0% schema description coverage, so the description carries the full burden — yet it says nothing about what a name is (entity name, node ID, fully-qualified identifier) or how matching behaves. With one undocumented parameter and no compensating prose, this falls below 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 calls itself a "Compatibility tool" and alludes to "explicit graph reads," but never states plainly that it retrieves/fetches nodes by name, nor how it differs from search_nodes or read_graph. The word "open" in the name is never expanded on, so an agent must infer the primary verb+resource from structured fields alone.

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 discourages the tool for large explicit graph reads and names the alternative: "prefer search_memories for bounded project-aware retrieval." That is a concrete when-not condition plus the replacement, though it never states the positive case for using open_nodes itself.

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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that — a compatibility layer over the v2 SQLite store and a warning that results may be large — but it does not say what the payload looks like (full graph vs. summary), which matters for a no-parameter read with no output schema.

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 tight sentences with the compatibility caveat first and the redirect second; nothing is wasted. The phrase 'the same v2 SQLite store' leans on unstated context, but it is compact and 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?

Annotations cover safety and there are no parameters, but with no output schema the description should clarify what a 'graph read' actually returns and roughly how large it can get. The size warning gestures at this without resolving it.

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 and 100% schema coverage, so there is nothing for the description to disambiguate. Baseline applies.

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?

It labels itself a 'compatibility tool' and refers to 'explicit graph reads', implying it returns the full knowledge graph, but never states outright that it returns all entities and relations. An agent can infer the scope only from the absence of parameters plus the size warning, not from an explicit verb+resource statement.

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 routes the agent away: 'prefer search_memories for bounded project-aware retrieval', naming the sibling and the condition that selects it. It stops short of saying when read_graph itself is the right choice (i.e., when a complete dump is actually wanted).

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?

Annotations already declare non-read-only, non-destructive, closed-world, and idempotentHint=false, so the safety profile is largely carried by structured data. The description adds real value with dedup behavior ("same entity/content is deduplicated") and attribution preservation, but it does not say whether a duplicate returns the existing record or an error, nor what permissions or side effects apply.

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?

Three short clauses, no filler, with the retry-safety guarantee front-loaded after the core action. It is efficient, though the density borders on under-specification given the parameter surface.

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-parameter write tool with no output schema and zero schema description coverage, the definition is too thin: return shape, duplicate-handling semantics, and most parameter meanings are unstated. An agent can call it, but cannot confidently predict the outcome.

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% across 9 parameters, so the description must compensate and largely does not. Only request_key (retry safety) and attribution ("unknown sources stay unknown") get any treatment; entity_name, content, kind, project, occurred_at, source_agent, and source_session are left entirely to bare type constraints.

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 concrete verb and resource ("Save a confirmed useful memory with provenance") and adds distinguishing traits (retry safety, dedup) that separate it from correct_memory and forget_memory. "Confirmed useful" is a judgment call left unexplained, but the core action is unambiguous.

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?

Implies this is the path for durable facts and tells the agent to pass request_key for safe retries, but never says when to prefer it over correct_memory, add_observations, or create_entities in the sibling set. The agent must infer the routing decision.

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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description still adds real value: it discloses that results are bounded, that project scoping includes global plus the exact project, and crucially that project is a relevance filter rather than an authorization boundary — a behavioral/security trait not in the schema.

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?

Three short sentences, front-loaded with the retrieval mode followed by the scoping rule and the authorization clarification. No 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?

With 5 parameters, 0% schema coverage, and no output schema, the description should carry the load but omits include_history and character_budget entirely and says nothing about result ordering or return shape. It is complete for the project parameter only.

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% across 5 parameters, so the description must compensate and largely does not. It explains the semantics of project well but leaves query, limit, include_history, and character_budget undocumented; "bounded" only faintly gestures at the budget/limit parameters.

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?

"Bounded lexical/full-text recall" states the retrieval mechanism, which is more specific than a bare verb, but it never names the resource (memories) or distinguishes this from the sibling search_nodes. An agent must infer the target corpus from the tool name alone.

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 clearly explains the project-filter scoping rule, which is genuine usage guidance. However, it offers no when-to-use-vs-alternatives guidance against search_nodes, read_graph, or open_nodes, so the agent gets scope semantics but no routing signal.

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?

Annotations already cover read-only, idempotent, and non-destructive traits, and the description adds two traits not in structured data: it is a compatibility shim over the v2 SQLite store, and results may be large. It does not describe return shape or pagination, but for a read-only compat alias the added context is substantive.

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 sentences, no repetition, and the compatibility caveat precedes the routing advice. The phrase 'Explicit graph reads' has a slightly unclear referent, 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?

With no output schema and an undocumented lone parameter, the description should explain what a node match is and roughly what comes back. It only warns that results may be large, which does not let an agent predict or handle 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?

There is one parameter with 0% schema description coverage, so the description carries the full burden — yet it never mentions `query`, what it matches against, or whether it is a name, full-text, or fuzzy search. This is the biggest gap in an otherwise reasonable definition.

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 frames the tool as a 'Compatibility tool backed by the same v2 SQLite store' and hints at graph reads, but never states the actual operation (searching nodes) or what the query matches. An agent can infer it is a legacy alias for graph node retrieval, but the verb+resource pairing is never made 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?

'prefer search_memories for bounded project-aware retrieval' explicitly names the sibling and the condition that selects it, which is exactly the routing guidance an agent needs. It stops short of saying when this tool is the right choice (only for legacy compatibility?), leaving that implicit.

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