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

Aside from the annotations (not readOnly, not destructive), the description provides no behavioral details such as whether adding an existing name errors, whether scope is required, how IDs are assigned, or what the response contains. The description adds little beyond the schema annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single compact sentence and is not padded. It loses a point only because 'exact scope' is vague and the sentence does not carry enough useful 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?

For a mutating creation tool with six parameters and no output schema, the description omits key context: whether the operation is idempotent, what uniqueness rules apply, how scope is determined, and what success/failure looks like. It is not complete enough for reliable autonomous use.

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?

With 0% schema description coverage and six parameters, the description only hints at aliases, attributes, and scope. It does not explain namespace, project nullability, uniqueness constraints, or default type behavior, so parameter semantics are mostly underspecified.

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 identifies the action ('Add') and resource ('entity'), and mentions aliases, attributes, and scope. It distinguishes from related tools like entity_get/entity_update, though 'exact scope' is somewhat vague.

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 about when to use entity_add versus sibling tools such as entity_update or memory_add. An agent must infer that entity_add is for creating new entities rather than modifying or searching existing ones.

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

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

The annotations already declare readOnly, idempotent, and non-destructive behavior, and the description's 'Get' wording is consistent with those. The description adds only that aliases are included in the result, but does not disclose anything else about behavior such as error cases or scope resolution.

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 a single sentence with no filler, and the primary action is front-loaded. It is concise but sacrifices enough parameter detail that it is not maximally useful.

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 four parameters, no schema descriptions, and many similar sibling tools, the description is too terse to give an agent enough context for correct invocation. It does not explain the meaning of 'selected scope', the optional parameters, or how this tool relates to entity_search and memory_get.

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 does not compensate by explaining the role of 'id', 'project', 'namespace', or 'include_deleted'. 'Selected scope' is the only vague nod to project/namespace parameters, but it does not map clearly to the actual 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?

The description names the action ('Get') and the resource ('entity and aliases') and references a 'selected scope', which makes the basic purpose clear. It is less explicit about whether this is a direct ID lookup versus a search, but the required 'id' parameter helps distinguish it from tools like entity_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?

The description does not say when to prefer entity_get over sibling tools such as entity_search, memory_get, or entity_link. It also does not explain what 'selected scope' means in terms of project/namespace usage.

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

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

The description discloses that the tool can link or unlink, which aligns with the readOnlyHint=false annotation. However, it does not explain side effects, idempotency, whether unlink is destructive, or any permissions/namespace implications. The annotations provide some transparency, but the description adds little beyond the basic 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?

The description is a single focused sentence that communicates the primary action and purpose without filler. It is concise and well-structured for a tool 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 tool has seven parameters, no output schema, and no parameter descriptions, yet the description only addresses the core linking action. It omits return behavior, parameter semantics, and edge cases such as unlink behavior or scope handling. The description is too sparse to fully support an agent in using the tool 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?

Only memory_id and entity_id are indirectly explained by the description; role, unlink, project, namespace, and confidence are not described at all. The schema names and types hint at meanings, but with 0% schema description coverage the description fails to clarify important parameters like role and confidence. This makes correct invocation harder than necessary.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Link/unlink') and the resources involved ('memory and entity'), which distinguishes it from entity-only or memory-only tools. The phrase 'for graph-assisted retrieval' adds context about why this link matters. It could be slightly more explicit about creating or removing a graph edge, but the core purpose is understandable.

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 no explicit guidance on when to use this tool versus alternatives like relation_add or memory_update. It mentions graph-assisted retrieval but does not explain when linking is preferable or what scenarios require it. The 'same scope' constraint is mentioned but not elaborated.

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 indicate read-only, non-destructive, and idempotent behavior. The description adds minimal behavioral context by mentioning 'exact scope' but does not explain side effects, return format, or pagination behavior, which would be valuable beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no redundant words. It efficiently conveys the core purpose without unnecessary elaboration.

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 7 parameters and no output schema, the description is severely incomplete. It does not explain what 'exact scope' means, how parameters interact, what results look like, or any edge cases. The agent would need to infer or test extensively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 7 parameters with 0% description coverage, and the description does not explain any of them. The meaning of 'query', 'limit', 'offset', 'include_deleted', 'type', 'project', and 'namespace' is entirely unspecified, leaving the agent without critical usage information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Search' and the resource 'entity names/aliases', making the primary purpose obvious. However, 'one exact scope' is vague and does not specify what scope means (e.g., namespace, project), slightly reducing clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like memory_search or relation_search. It does not mention specific conditions or exclusions, leaving the agent to infer context from the name alone.

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

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

The description reveals the soft-delete/restore behavior via the deleted flag, adding context beyond the annotations. However, it does not disclose whether updates are merged or replaced, or mention side effects like validation or permissions.

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 a single, concise sentence that directly conveys the tool's purpose without unnecessary 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?

Given the tool's simplicity, the description covers the core update behavior but lacks information about return values, partial vs. full updates, and the meaning of project/namespace in context. These gaps could lead to ambiguity for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description partially explains the 'updates' parameter by mentioning fields, aliases, and deleted, but does not clarify the roles of 'id', 'project', or 'namespace'. Schema coverage is low, but the description adds meaning to the most important update fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool updates entity fields, aliases, or the deleted flag for soft-delete/restore, distinguishing it from sibling tools like entity_add or entity_get.

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 explicit guidance on when to use this tool versus alternatives such as entity_add or entity_update (though entity_update is unique). It does not mention prerequisites or scenarios where this should be preferred.

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

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

The description mentions reporting truncation, which is a concrete behavioral detail. Combined with annotations (readOnlyHint, idempotentHint, destructiveHint), it provides good transparency about side effects and outcome reporting. However, it does not explain edge cases like empty results or error 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?

The description is a single, compact sentence with no superfluous words. It front-loads the core behavior (bounded BFS) and then specifies constraints and reporting, making it optimally concise yet informative.

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 graph traversal tool, the description covers key aspects: traversal type, depth bound, limits, temporal filtering, and truncation reporting. It does not specify the exact output format (e.g., whether nodes, edges, or both are returned), but given the simplicity and common patterns, this is a minor gap.

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 does not clarify parameter meanings. While names like entity_id, max_depth, and max_nodes are self-explanatory, others like project, namespace, and at are ambiguous without elaboration. The tool description fails to compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool performs a bounded BFS up to depth 3 with node/edge limits and temporal filters, and reports truncation. This unambiguously conveys its primary function of traversing graph neighbors, distinguishing it from sibling tools like graph_path which focus on pathfinding.

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 does not explicitly state when to use this tool versus alternatives (e.g., graph_path or memory_search). While the name and behavior imply use for neighbor exploration with constraints, there is no direct guidance on selection criteria, leaving some inference required.

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 indicate read-only, non-destructive, and idempotent behavior. The description adds no further behavioral details such as side effects, authentication, or rate limits, so it does not go beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence with no redundancy or filler. It conveys the core functionality efficiently without unnecessary 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?

The description provides high-level purpose but omits critical context such as parameter interpretations, expected output format, and edge cases (e.g., what happens when no path exists or when max_nodes is reached). Given the complexity of 8 parameters, this level of detail is insufficient for confident use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema lists 8 parameters but none are described in the tool description. With 0% schema description coverage, the description provides no guidance on the meaning or usage of parameters like 'at', 'project', 'namespace', or 'max_depth', leaving users to infer from names alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: finding a path between two entities within a bounded scope and temporal snapshot. It distinguishes itself from sibling tools like graph_neighbors and memory_search by focusing on pathfinding with directional and depth constraints.

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 for path queries but does not explicitly mention when to prefer this over alternatives like graph_neighbors or memory_search. It lacks explicit guidance on conditions or exclusions, so usage context is only inferred.

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

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

The description adds behavioral context beyond the annotations by mentioning 'durable' and the normalized duplicate handling. It does not contradict the annotations (idempotentHint=true, readOnlyHint=false). The added details are useful but not extensive.

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 extremely concise, consisting of two short sentences. It avoids unnecessary detail and gets straight to the point. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the tool is simple, the description omits critical context such as what the return value is for new entries (only mentions duplicates), what 'scope' refers to, and whether any side effects occur (e.g., persistence guarantees). Given the complexity of the schema, more context is needed.

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?

With 0% schema description coverage, the description fails to explain any of the 10 parameters. It only vaguely references 'same scope' without mapping to actual fields like namespace or project. This does not compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's primary action: adding durable memory. It also highlights the unique duplicate-handling behavior, which distinguishes it from other memory-related tools. However, it does not explicitly differentiate it from similar operations like memory_import or memory_restore.

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 an idempotent behavior (duplicate returns existing ID) but does not provide explicit guidance on when to choose this tool over alternatives such as memory_import or memory_update. No direct comparison or conditional usage is 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that the tool preserves superseded history, implying it returns historical versions of facts, and filters by a timestamp. This goes beyond the annotations but does not detail default inclusion of stale/deleted/inactive records 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 a single, focused sentence that immediately conveys the core action and key behavior. It is concise, front-loaded, and free of unnecessary details or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description provides the essential purpose but omits critical contextual details like the default return set (e.g., whether stale or deleted facts are included by default) and the exact output format. Given the tool's complexity (12 parameters, temporal filtering), a bit more context would help an agent use it correctly, though the core behavior is clear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 12 parameters with zero description coverage, and the tool description does not explain any of them. While parameter names like 'limit', 'offset', and 'at' are somewhat self-explanatory, ambiguous flags such as 'include_stale', 'include_deleted', and 'include_inactive' receive no clarification, leaving the agent to guess their meaning or defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool queries graph facts valid at a specific ISO timestamp and preserves superseded history, which distinguishes it from other memory query tools that return current facts. The verb 'query' and the specific temporal filtering make the purpose 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?

The description does not explicitly state when to use this tool versus alternatives like memory_search or memory_get. It implies temporal usage via 'specific ISO timestamp' and 'preserves superseded history,' but lacks direct guidance on scenarios or trade-offs (e.g., performance, current vs. historical queries).

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

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

While annotations indicate idempotent and non-destructive, the description clarifies it is a soft-delete and mentions that restore is available via maintenance CLI, adding useful behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Short, single-sentence description with no unnecessary fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description fails to provide enough context for correct usage, such as what 'selected scope' means, which parameters are needed, and what happens to linked data. The restore note helps but doesn't compensate for missing parameter explanations.

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 description does not explain any of the four parameters (id, project, namespace, include_deleted). 'Selected scope' is vague and doesn't map to 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?

Clearly states it soft-deletes a memory, with a specific verb and resource. Also mentions restore via maintenance CLI, providing useful context.

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 explicit guidance on when to use this tool over alternatives like memory_update or memory_remove. The mention of restore is about recovery, not about usage scenarios.

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 (readOnlyHint=false, destructiveHint=false) indicate it is not read-only but not destructive. The description only discloses behavior for the apply action (materializes without overwriting). It does not explain side effects of run, get, or enqueue, leaving the agent unsure whether these mutate state. With no annotation detail beyond false flags, the description carries the burden and fails to cover the action variants.

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 filler, and the most important behavioral detail (apply without overwriting) is placed second. It is appropriately concise, though the first sentence is somewhat dense with four verbs packed together.

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 tool has 4 parameters, no output schema, and no parameter descriptions. The description does not explain what each action does, what the id targets, or how 'validated LLM suggestions' are produced or used. It also fails to distinguish from memory_add/memory_update. Given the complexity and lack of structured metadata, the description is insufficient 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 explain parameters. It only adds meaning for the action enum (specifically apply), but does not clarify what id refers to, or the purpose of project/namespace. The main phrase 'run/get/enqueue optional validated LLM suggestions' gives context but not parameter-level semantics. It fails to compensate for the schema 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 states the tool operates on optional validated LLM suggestions, with verbs run/get/enqueue/apply. It clarifies that apply materializes graph facts without overwriting, which distinguishes it from direct memory tools like memory_add or memory_update. However, it doesn't explicitly contrast with siblings or define the overall 'enrich' concept beyond suggestion handling.

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 use this tool versus alternatives. It never mentions siblings like memory_update or memory_add, nor does it provide conditions for choosing this over direct memory operations. The only hint is that apply materializes suggestions without overwriting, but there is no explicit when-to-use/when-not-to-use 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?

Annotations already declare read-only and idempotent behavior. The description adds a useful note that it does not write arbitrary files, reinforcing non-destructive behavior, but does not cover other potential side-effects or limitations.

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 with no redundant wording. Information is efficiently presented.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks critical context: it does not explain the meaning of the many optional filters, the structure of the returned data beyond format, or the relationship to the memory system. Given the large parameter set and no output schema, this is insufficient for correct use.

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 description gives no explanation of any of the 13 parameters. It only generically says 'Apply filters', which does not help map to specific fields like tag, source, or created_after. With zero schema coverage and no parameter descriptions, the agent has virtually no guidance.

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 ('Return') and a resource (JSON or Markdown data), distinguishing it as an export tool. However, the phrase 'in data' is vague and the description does not explicitly name the underlying memory store, though it is clear from context.

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?

Mentions applying filters to limit size but provides no guidance on when to use this tool versus alternatives like memory_list or memory_search. No explicit conditions 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?

The description reinforces the read-only and non-destructive nature by stating 'Never modifies memories,' which complements the annotations. It does not mention rate limits or permission requirements, but the annotations already cover idempotency and lack of 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 a single, concise sentence that directly states the action and its constraints. It is front-loaded with the primary purpose and avoids unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks information about return values and parameter usage. Given that there is no output schema, an agent cannot predict the response format, and parameter semantics are undocumented, making the tool incomplete for complex use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema defines seven parameters (id, mode, limit, project, namespace, threshold, max_candidates) but the description provides no explanations for any of them. Since schema coverage is 0%, the description fails to compensate, leaving parameter meanings ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: suggesting duplicates using text or embedding similarity within a scope. It also explicitly notes that it never modifies memories, which disambiguates its side-effect-free nature.

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 when to use this tool—when you need to find duplicate memories—but it does not explicitly contrast it with alternatives like memory_search or memory_list. However, the unique purpose of duplicate detection is clear enough for an agent to infer usage.

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

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

The description adds behavioral details beyond the annotations, such as returning expired state and the requirement for include_deleted to access deleted records. This complements the readOnly and idempotent hints.

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 compact and to the point, with two sentences that deliver key information without redundancy or unnecessary 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?

Given the absence of an output schema, the description sufficiently covers the essential context: what is retrieved, the scope behavior, and the special case of deleted records. It does not address error handling or return format, but these are not critical for a straightforward get 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?

The description only implicitly covers 'id' (as the identifier) and 'include_deleted' (as the flag for deleted records). It does not explain 'project' or 'namespace' parameters, leaving their role vague ('selected scope'). Schema coverage is 0%, so the description carries limited parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get', the resource 'memory by ID', and the scope 'selected scope'. It also distinguishes itself from list/search operations by focusing on a single memory retrieval.

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 specifies the 'selected scope' and the behavior for deleted records ('deleted records require include_deleted:true'), giving clear conditions for use. While it doesn't explicitly name alternatives, the singular retrieval intent is evident from the phrasing.

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

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

The description transparently discloses the preview/commit workflow and conflict resolution options, which aligns with the destructiveHint annotation. It adds useful context beyond the schema about default dry-run behavior and potential overwrites via 'update' conflicts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured in two sentences, covering the core action, input modes, default behavior, and conflict handling without redundant text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity and no output schema, the description covers the main behavioral aspects needed to invoke it correctly. It could mention side effects more explicitly, but the dry_run and conflict details provide sufficient operational context.

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 description explains key parameters like path, data, dry_run, conflict, and format, but leaves namespace, project, and backup undefined. Since the schema provides no descriptions and these parameters are relevant for scoping and safety, the coverage is incomplete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool imports memory data in specific formats (JSON, Markdown, Claude Code) from a path or inline, and explains the commit/preview behavior. It also distinguishes the action from siblings like memory_export and memory_add by focusing on importing external/versioned 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?

The description explains how to use the tool (path vs inline, dry_run, conflict modes) but does not explicitly state when to prefer this over alternatives such as memory_add or memory_restore. It gives operational guidance but lacks direct comparison to sibling tools.

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 behavior. The description adds useful filter-matching semantics, but discloses no additional side-effect information beyond what annotations provide.

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 concise sentences with no fluff. The purpose is front-loaded and the additional tag-matching detail is placed efficiently.

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 15 optional parameters and no output schema, the description lacks output information and detailed parameter semantics. It is not fully complete for confident invocation without additional context.

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 description gives a high-level sense of filters, pagination, sort, and tag AND behavior, but schema description coverage is 0%. With 15 parameters and no individual descriptions, the description only partially compensates for the missing parameter-level guidance.

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?

Description uses a specific verb ('browse'), names the resource ('memories'), and mentions exact filters, pagination, and sort. It does not explicitly differentiate from sibling search/list tools beyond implying exact matching.

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?

Provides implicit usage context by describing browsing with filters and sorting, and clarifies multi-tag AND semantics. However, it does not explicitly state when to use this tool versus alternatives like memory_search or memory_get.

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

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

The description goes beyond the destructiveHint annotation by clarifying that expire/orphans perform soft-delete and that physical purge is not available here. It also discloses the dry-run default, making the tool's safety profile transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with no filler. Key facts are front-loaded: bounded maintenance, dry-run default, soft-delete, whole-DB effects, and CLI-only physical purge. Each sentence adds value.

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?

While the description covers the main maintenance actions and safety constraints, it omits details about other parameters, output behavior, or specific use cases for each action. Given the tool's complexity (7 params, 9 enum values), the description provides a good starting point but is not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains the meaning of some enum values (expire/orphans soft-delete, FTS rebuild/vacuum whole DB) and the dry_run default, but does not cover parameters like id, limit, project, after_id, or namespace. Schema coverage is 0%, so the description partially compensates but leaves many parameters unexplained.

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 indicates a maintenance tool with specific actions (expire, orphans, FTS rebuild, vacuum, etc.) and notes it is bounded and defaults to dry-run. While 'explicit bounded maintenance' is somewhat abstract, the action list and scope statement make the purpose understandable.

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 mentions that expire/orphans soft-delete and that FTS rebuild/vacuum affect the whole DB, and that physical purge is CLI-only, which gives some guidance on when to use this tool vs. alternatives. However, it does not explicitly state scenarios for choosing this over other memory operations or detail 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?

The description clearly discloses the destructive nature (soft-deletion of sources) and the retention of snapshots and provenance, aligning with the destructiveHint=true annotation. It also highlights the dry_run safety mechanism.

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 a single, concise sentence that flows logically from preview to apply. It avoids unnecessary detail and effectively conveys the core action.

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?

While the two-step process is clear, the description does not specify what the preview returns, how to handle errors or conflicts, or the role of the remaining parameters. This leaves gaps for an agent to invoke the tool effectively, especially without an output 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 schema lists 8 parameters but the description only clarifies dry_run and proposal_token in the context of the workflow. It leaves target_id/source_ids inferred as the merge targets/sources, and omits any explanation for title, content, project, and namespace. With 0% schema description coverage, parameter semantics are largely undefined.

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 explicitly states the tool merges memory records, with a preview step and an apply step using a proposal token. It is distinct from sibling tools like add, update, delete, and 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?

It describes a two-step workflow: preview with dry_run, then apply with proposal_token. It also warns that source records are soft-deleted and originals retained, guiding safe usage. However, it does not compare to alternatives or specify when merge is preferred.

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

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

The description explains meaningful side effects beyond annotations: it explicitly embeds memories, can operate on a bounded batch, and reuses unchanged indexes unless force is true. This adds useful behavioral context, though it omits error conditions, rate limits, or cost implications.

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 a single, compact sentence that packs the core purpose and key behavior without unnecessary words. It is well-structured and easy to parse.

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 six parameters and no output schema, the description does not provide enough context to understand how parameters relate (e.g., after_id vs. limit pagination, namespace vs. project scoping). An agent would likely need external documentation to call this 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%, and the description only vaguely hints at 'Optional IDs or bounded batch'. The roles of limit, after_id, project, namespace, and force are not clearly explained, leaving substantial ambiguity for callers.

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 identifies the tool's action ('Explicitly embed active memories') and resource ('active memories using the configured provider'). It also distinguishes reindexing from plain add/update/search operations by mentioning index reuse and force behavior, though it does not directly name sibling 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 gives some usage hints ('Optional IDs or bounded batch', 'unchanged indexes are reused unless force:true') but does not explicitly state when to prefer this tool over memory_add, memory_update, or other sibling tools. The intended invocation scenarios remain largely inferential.

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?

Describes the action as restore, implying a state change, consistent with readOnlyHint=false and destructiveHint=false. Does not detail side effects but no contradiction.

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?

Single, clear sentence with no unnecessary words, well-structured for a tool 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?

Lacks necessary parameter descriptions and output information, making it incomplete for an agent to use correctly without additional context.

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?

Description provides no explanation for any of the four parameters (id, project, namespace, include_deleted), leaving their meaning and usage completely unclear.

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?

Clearly states the specific action (restore) and resource (soft-deleted memory), distinguishing it from other memory operations in the sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Lacks explicit guidance on when to use this over alternatives, though the purpose is evident. No mention of prerequisites or conditions for restoration.

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

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

The annotations already provide read-only, idempotent, and non-destructive hints. The description adds that deleted and expired memories are excluded by default, which is behavioral information not covered by annotations. This goes beyond the annotation baseline, demonstrating transparency about default 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 two concise sentences that convey the essential search mechanism and default exclusions. There is no verbosity or irrelevant information, and the structure is clear and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks information about the return format or output structure, as there is no output schema. It also does not explain the many filtering parameters or pagination controls. While the search behavior is described, the missing context about what the tool returns and how to utilize the parameters makes it incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 16 parameters with 0% coverage from the description. The description does not explain any parameter, such as query, tags, sort, or filters. Given the low coverage, the description fails to compensate by providing any parameter semantics, making it extremely difficult for an agent to use the parameters effectively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool searches using FTS5 with literal AND terms and BM25 ranking, which precisely defines its purpose. It also mentions small importance/recency boosts, providing a specific and unambiguous function. This is sufficient for an agent to understand what the tool 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?

The description implies usage through its search behavior but does not explicitly compare with alternatives like memory_search_hybrid. It mentions the default exclusion of deleted and expired memories, which gives some guidance on when to use it or adjust parameters, but it lacks a clear 'when to use this tool vs others' statement.

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

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

The description discloses the fallback mechanism and mentions that results indicate candidate limits and fallback status, offering useful behavioral context. Annotations already flag readOnly and idempotent, so the added detail about fallback is sufficient for this dimension.

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 brief and to the point, containing only three sentences. It conveys the essential behavior without verbosity, making it easy to parse and consume.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the 18-parameter schema and lack of output schema, the description is highly incomplete. It fails to clarify the meaning of key parameters, expected response structure, or the exact semantics of 'candidate limits' and 'fallback.' This leaves significant contextual gaps for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides no explanation of any of the 18 parameters. Schema coverage is 0%, and the description does not compensate by describing obvious or critical parameters such as query, mode, or filters. This leaves agents with minimal understanding of parameter meanings.

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 identifies this as a hybrid search tool (lexical, semantic, or RRF) with optional graph context, which distinguishes it from sibling search tools like memory_search or entity_search. The core purpose is evident.

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 fallback behavior when provider is unavailable or scope is unindexed, which gives some guidance on when the tool might be used. However, it does not explicitly compare to alternative search tools or state preconditions for choosing this hybrid variant over others.

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

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

The readOnlyHint, idempotentHint, and destructiveHint annotations already convey that this is a safe, non-mutating operation. The description adds no behavioral details beyond that, but it also does not contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that covers the main metric categories without extraneous words. It is easy to parse and front-loads the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description enumerates the kinds of metrics returned but does not specify the output shape or provider-state details, and there is no output schema. It is enough to attempt a call, especially with no required parameters, but the return format remains underspecified.

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 two optional parameters, project and namespace, are named clearly but the description does not explain how they affect results. With 0% schema description coverage, the text should have compensated by describing filtering or scoping behavior, which it does not.

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 lists the resource's output areas—scope counts, provider state, and aggregate latency/error/import metrics—so the tool's purpose is evident. It is distinct from sibling memory tools by focusing on statistics rather than individual entries or operations.

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 does not state when to call this tool instead of the many sibling tools, nor does it explain whether project/namespace arguments are needed for scoped versus database-wide stats. No alternative or selection guidance is provided.

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

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

The description adds useful context about moving projects via updates.project, but does not disclose whether the update is partial or full replacement, what happens to omitted fields, or the destructive overwrite potential hinted by annotations. It neither contradicts the destructiveHint annotation nor meaningfully elaborates on it.

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 very concise and front-loaded with the primary verb and object. Every sentence carries some information, though 'selected original scope' is slightly unclear and could be simplified. It avoids redundancy and unnecessary 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?

Given the complex nested updates object and lack of an output schema, the description is too thin. It does not explain partial update semantics, the relationship between top-level project and updates.project, namespace/project scoping, or the destructive nature of overwriting existing fields. The single helpful note about project moves is not enough for a tool of this complexity.

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?

With 0% schema description coverage, the description must compensate for parameter meaning, but it only explains updates.project. It leaves id, namespace, top-level project, and most fields inside updates (tags, type, title, source, content, metadata, expires_at, importance) to be inferred from names and schema constraints. This is insufficient for a nested update object.

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?

Clearly states the action (update), the resource (memory), and includes a useful note about moving projects via updates.project. The phrase 'selected original scope' is slightly awkward but does not obscure the core purpose. It is distinguishable from sibling tools like memory_add and memory_delete.

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?

Provides minimal guidance on how to supply changes and mentions project moves, but does not say when to use this tool versus alternatives such as memory_add, memory_merge, memory_enrich, or entity_update. There is no mention of when updating is appropriate or what preconditions should 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?

The description explains the conflict resolution behaviors: preserve marks overlapping alternatives as conflicts, parallel allows coexistence, and supersede requires an explicit old relation ID. This is useful side-effect disclosure beyond the schema, though it does not describe return values or what happens after a conflict is marked.

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 a single focused sentence with no redundant wording. It packs key behavioral information about conflict strategies into a compact form.

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 12-parameter tool with no output schema, the description is too sparse. It omits the temporal validity semantics, namespace/project scoping, confidence meaning, attribute usage, and the response/error behavior, leaving important context unspecified.

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?

With zero schema description coverage, the description must compensate for parameter meanings, but it only clarifies conflict_strategy and supersedes. Most parameters (valid_from, valid_to, namespace, project, attributes, confidence, source_memory_id) are left to inference from their names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Add') and the object ('a temporal fact'), and the tool name relation_add reinforces that this creates a relation. It does not explicitly mention 'relation' or contrast with entity_add/memory_add, but the intent is still 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?

The description gives no explicit guidance on when to use relation_add instead of relation_update or relation_search. It does explain the conflict_strategy behaviors, but it stops short of stating use cases or 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds useful behavior: the validity interval semantics ([valid_from,valid_to)) and the availability of stale/deleted/inactive filters. However, it does not clarify default filtering behavior (e.g., whether stale records are excluded by default) or pagination/return format. It adds some value beyond annotations but lacks depth.

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 two concise sentences with no fluff. It front-loads the primary purpose and immediately adds the key validity interval detail. Every word contributes to understanding the tool's scope and key 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?

Given the tool's complexity (13 parameters, no output schema, no schema descriptions), the description is incomplete. It does not explain parameter semantics, default filter behavior, pagination, or the response format. The mention of validity interval is helpful but not sufficient for an agent to call this tool correctly across all its options.

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 for explaining the 13 parameters. It mentions 'scope, intervals, stale/deleted/inactive filters', which loosely maps to parameters like source_entity_id, at, include_stale, etc., but does not explain the meaning of parameters such as 'project', 'namespace', 'predicate', or how 'at' and 'history' work together. The description provides only a high-level overview, insufficient for correct parameter usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: querying current facts or history, with filters for scope, intervals, and stale/deleted/inactive states. The verb 'Query' and the resource (facts/relations) are explicit, and it distinguishes from modifying siblings like relation_add/relation_update. However, the term 'facts' is somewhat vague without explicit mention of 'relations', though the tool name clarifies this.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives like entity_search or memory_search. It mentions specific filter capabilities, but does not state exclusions or alternatives. The context of relation searching is implied by the name, but no clear 'use this for X, not Y' guidance is 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?

The description conveys that this is a mutating operation and mentions soft deletion and the inability to reopen superseded intervals. It does not disclose side effects like whether partial updates are atomic, what happens if the id is missing, or any additional effects beyond the listed field updates.

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 brief and to the point, with two sentences that list affected fields and state a key constraint. No unnecessary words or redundant details.

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 nested update object and no output schema, the description is somewhat thin. It gives the core intent and a constraint but omits guidance on how to use the required id/updates combination, what namespace/project mean, and what happens on invalid input or after soft deletion.

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 description covers several nested update fields (confidence, attributes, status, valid_to as 'end time', deleted as 'soft deletion'), but it does not explain top-level parameters like id, project, namespace, or the nested source_memory_id. The schema provides names but no semantic descriptions, so the prose adds only partial clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the operation is an update on a fact/relation, enumerating the fields it affects (confidence, attributes, status, end time, soft deletion). This distinguishes it from add/search siblings, though it does not explicitly say 'relation' or 'fact' in a way that fully disambiguates from memory_update.

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 use when modifying an existing fact/relation rather than creating one, and the constraint 'Superseded intervals cannot be reopened' gives some context. However, it does not explicitly compare with relation_add or memory_update, nor state prerequisites like the fact must already exist.

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