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

The description goes well beyond the sparse annotations by disclosing deduplication with an 85% threshold, background indexing, side effects, and the possibility of skipping a duplicate. However, 'Returns immediately' is stated unconditionally even though the schema allows async=false to block until completion, so the description slightly oversimplifies 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 front-loaded and compact, with the core action and key behaviors in the first sentences. It loses a point for slight redundancy: the immediate-return and background-processing idea appears twice, once in prose and once in the side-effect list.

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?

Despite having seven parameters and no output schema, the description covers the use case, duplicate-check behavior, async return behavior, expected return value ('confirmation text'), and side effects. Combined with a fully documented schema, this is complete enough for an agent to invoke 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?

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by giving the default duplicate-detection threshold (85%) and by noting return behavior and side effects, which helps contextualize skip_duplicate_check and async. It does not deeply annotate each parameter, but the schema already does that.

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

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

The description opens with a specific verb and resource: 'Store a new memory with automatic deduplication and indexing.' It also names the exact use cases (facts, preferences, conversation context) and explicitly distinguishes itself from update_memory, so an agent can tell at a glance which operation this is.

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 states when to use the tool ('Use for persisting facts, preferences, or conversation context') and gives a direct sibling-route instruction: 'Prefer over update_memory for new content.' This is explicit enough for an agent to choose between the two most similar memory 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 declare readOnlyHint and idempotentHint, so the description correctly reinforces 'Read-only' and 'No side effects.' It adds value by specifying the return format: 'summary text with cached memory count,' which helps the agent set expectations. No contradiction with 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?

Two concise sentences that state purpose, usage, and result. Every sentence earns its place, and the key scoping info ('monitoring and debugging') is front-loaded. No wasted words.

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 zero-parameter read-only tool with annotations covering safety, the description fully covers what an agent needs: what it does, when to use it, and what it returns. Nothing critical is missing.

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?

Tool takes zero parameters, so the baseline is 4. The description does not need to explain parameters; it correctly omits them, and the schema confirms 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?

Clearly states the verb 'View' on the resource 'cache performance metrics and health status.' Distinguishes from siblings like optimize_cache (which modifies cache) and get_all_memories (which lists memories) by focusing on metrics and health. The purpose 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?

Explicitly states 'Use for monitoring and debugging,' giving clear context for when to invoke. Does not name alternatives or explicit exclusions, but the read-only nature and health-check scope make it obvious it's for diagnostics rather than operations.

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 flag destructiveHint=true, and the description adds valuable behavior: it deletes duplicates, invalidates cache, uses Jaccard similarity, groups with primary oldest, and supports a safe dry-run mode. No contradiction with 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?

Every sentence earns its place: purpose, safety instruction, method, grouping behavior, return value, and side effects. Front-loaded with the core action and preview guidance; no filler or redundancy.

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

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

Despite no output schema, the description states what is returned ('summary with duplicate groups'). The pairwise algorithm, grouping strategy, dry-run behavior, and side effects are all covered. Sufficient for an agent to invoke it correctly, especially with the destructive flag properly contextualized.

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

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

Schema coverage is 100%, so each parameter already has a rich description. The tool description adds no parameter-level detail beyond the schema, which is acceptable; the baseline of 3 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?

States a specific verb ('Detect and optionally remove') and resource ('duplicate memories'), with a precise method (content similarity, Jaccard, pairwise). Clearly differentiates itself from siblings like delete_memory by focusing on deduplication rather than single-record 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?

Explicitly instructs to run with dry_run=true first for safe preview, and warns that dry_run=false is destructive. While it doesn't name sibling alternatives or provide when-not-to-use guidance, the operational workflow is clear and 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?

Annotations already indicate destructive/read-only traits, and the description adds meaningful specifics: the operation is irreversible, removes from storage/cache/search index, invalidates cache, and returns a confirmation text. No contradiction exists with idempotentHint or destructiveHint.

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

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

The description is front-loaded with the primary action and includes useful return and side-effect details. It loses a point for redundancy: 'Irreversible operation' repeats 'Permanently remove', and the side-effects fragment duplicates 'removes from storage, cache, and search index'.

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 single-parameter destructive tool with no output schema, the description covers the return value, side effects, and a relevant alternative workflow. The only notable behavioral detail not repeated in the description ('succeeds if ID not found') is already present in the input schema, so nothing essential is missing.

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 100%, so the memory_id parameter is fully documented in the schema, including the 'succeeds even if ID not found' behavior. The description adds minimal parameter meaning beyond the word 'by ID', which is acceptable given the complete schema.

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

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

The description states a specific verb ('remove'), resource ('memory'), and key ('by ID'), making the tool's core purpose unmistakable. It also distinguishes this from sibling deduplicate_memories by framing that tool as the bulk-deletion preview alternative.

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 tells the agent to use deduplicate_memories with dry_run first for bulk deletions, providing a concrete alternative. It does not exhaustively specify every condition for choosing delete_memory over other siblings, but for a single-object delete operation the guidance is sufficient.

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 and destructiveHint=false, so the safety profile is covered. The description adds beyond that: it discloses the 'enhanced intelligence mode' requirement, states the tool is stateless, and explicitly lists the returned fields (people, organizations, technologies, projects, relationships, keywords). This is valuable context an agent needs but would not know from annotations alone.

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 moderately detailed but every sentence carries meaning: purpose, entity types, relationship types, requirements, safety (repeats annotation), and return shape. It is front-loaded with the purpose and specifics. The only minor redundancy is 'Read-only, stateless' which partly duplicates annotations, but it is brief and not harmful. Overall, it is appropriately concise for a tool with no output schema.

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 single-parameter NLP tool with no output schema, the description is very complete: it defines input type and expectations, lists all output categories, states the mode requirement, and clarifies it is stateless. Siblings are unrelated, so no additional disambiguation is needed. An agent is fully equipped to call this tool correctly without external guidance.

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 documents the 'text' parameter at 100% coverage, so the baseline is 3. The description adds extra semantics not in the schema: 'Longer text yields more entities' and 'Supports natural language, code comments, or structured text.' These hints help an agent decide how much text to provide and what formats are acceptable, thereby exceeding the schema's basic type and description.

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

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

The description explicitly states the verb 'Extract' and the resource 'named entities and relationships from text using NLP', and enumerates the entity types (people, organizations, technologies, projects) and relationship types (WORKS_FOR, USES). It is clearly distinct from sibling memory-management tools, which focus on storage/retrieval rather than extraction, so an agent would have no trouble selecting it.

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 name a specific alternative or exclusion, but the sibling tools are all memory-related and have no overlap, so the intended usage context is obvious. It does include a critical usage condition: 'Requires enhanced intelligence mode', which tells the agent when it can be invoked. It also notes the tool is read-only and stateless, implying it is for analysis, not modification.

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 provide readOnly, idempotent, and non-destructive hints. The description adds meaningful behavior: BFS traversal, the enhanced-mode requirement, and the return payload structure. This exceeds what the annotations alone convey.

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 appropriately sized and front-loaded with the core purpose. The sentence on return format is useful, but 'Read-only' is redundant with annotations and some phrasing is slightly repetitive.

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 3-parameter tool with no output schema, the description covers the key behavioral detail, the return shape, the required mode, and the primary use case. No critical information needed to invoke or interpret the tool appears to be missing.

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?

Input schema coverage is 100%, and each parameter already has a descriptive definition. The tool description does not add material parameter meaning beyond the schema, so the baseline of 3 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?

The description states a specific verb and resource ('Discover relationship paths between entities in the knowledge graph') and clarifies the goal with a concrete use case ('how is X related to Y?'). It clearly differentiates from siblings like get_knowledge_graph by focusing on paths rather than the whole graph.

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

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

It gives a clear context for use ('answering how is X related to Y') and a prerequisite ('Requires enhanced mode'). It does not explicitly name alternatives or state when not to use this tool, but the purpose is specific enough to guide selection.

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 meaningful behavioral context beyond the annotations: cache-first default and automatic truncation of large result sets. It does not contradict the annotations, but could have expanded slightly on cache 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 three succinct sentences with no wasted words. It front-loads the core action, then gives usage guidance, behavioral notes, and return shape, all in a logical and efficient structure.

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 includes the essential return shape ({total, limit, offset, returned, hasMore, source, memories[]}), which compensates for the absence of an output schema. Combined with complete parameter documentation and explicit sibling routing, an agent has everything needed to invoke this 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?

Schema description coverage is 100%, and each parameter is already clearly documented with ranges, defaults, and usage semantics. The description mentions pagination generally but adds no parameter-level meaning beyond what the schema provides, matching the baseline expected score.

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 specific verb 'List' and resource 'all memories for a user with pagination,' clearly defining the tool's scope. It also distinguishes the tool from its sibling search_memory, so an agent can differentiate them immediately.

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

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

The description explicitly states when to use this tool ('for browsing or bulk operations') and directs the agent to an alternative when needed ('For content search, use search_memory instead'). This is precise routing guidance with no ambiguity.

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 mark the tool as read-only and non-destructive, and the description reinforces this with 'Read-only.' It adds valuable behavioral context beyond annotations by disclosing the enhanced-intelligence prerequisite and prior entity-extraction dependency, and by specifying the exact node/edge return shape.

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 efficiently organized: purpose first, then use case, prerequisite, read-only note, and return shape. Every sentence contributes meaningful information, though the 'Read-only' sentence is redundant with annotations and could be omitted.

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, the description covers the main invocation context: what it returns, when to use it, the required mode, and read-only behavior. The schema covers all parameter semantics. A minor gap is lack of guidance on alternative tools for similar graph/connection tasks, but overall the tool is well specified.

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

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

The input schema already provides 100% coverage with detailed descriptions for all four parameters, including ranges, defaults, filter semantics, and example values. The description adds no additional parameter-level meaning, so baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Build a knowledge graph from stored memories.' It clearly distinguishes itself from sibling memory retrieval tools by emphasizing entities-as-nodes/relationships-as-edges and the use case of visualizing connections between concepts.

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

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

The description explicitly states when to use the tool: 'Use for visualizing connections between concepts.' It also provides a critical prerequisite: 'Requires enhanced intelligence mode with prior entity extraction.' However, it does not explicitly mention alternatives or when-not-to-use scenarios relative to siblings like find_connections.

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, and non-destructive; the description adds the crucial 'Returns null if not found' behavior and the exact return shape (Memory object {id, content, user_id, metadata}). It repeats 'Read-only operation' but supplements annotation data with retrieval semantics rather than contradicting 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?

Three short sentences deliver purpose, usage, and return behavior with no filler. The most decision-relevant facts (ID-based retrieval, null return, search_memory alternative) are front-loaded.

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

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

For a simple get-by-primary-key operation, the description is self-sufficient: it specifies how to obtain the ID, what the read-only semantics are, what is returned, and the null case. The optional user_id parameter is fully covered by the schema, so no critical context is missing.

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

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

The input schema provides 100% coverage: both parameters, including the memory_id provenance and user_id default, are documented. The description adds no new parameter-level detail beyond what the schema already states, so it stays at the 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 opens with a specific verb-resource pair ('Retrieve a single memory by its unique ID') and immediately clarifies key behavior. It differentiates from search_memory by explicitly directing content-based lookups elsewhere, so an agent can select this tool over siblings without inspecting schemas.

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

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

It states exactly when to use the tool: when you have a specific memory_id from prior search/list results. It also gives an explicit alternative for other cases ('Prefer search_memory for content-based lookup') and notes the null result for missing IDs, making the decision boundary 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?

The description explicitly discloses side effects: 'creates multiple memory records, updates search index' and states the return summary with imported/skipped/failed counts. This goes well beyond annotations, which only mark readOnly=false and idempotent=false, and is consistent with the lack of readOnlyHint.

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?

Each sentence serves a distinct purpose: scope, supported sources, processing behavior, intended use, return value, and side effects. The description is front-loaded with the core purpose and contains 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?

For a tool with seven parameters and no output schema, the description covers the essential missing pieces: return summary and side effects, while the schema handles parameter semantics. It also directs to migration/backup use, and the sibling list provides enough separation for correct tool selection.

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 100%, and the schema already details enums, defaults, conditional requirements, and ranges. The description does not add new parameter-level meaning beyond restating batch/duplicate behavior, so the baseline 3 is appropriate.

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

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

The description opens with 'Bulk import memories from external sources', naming a specific verb, resource, and scope. It further specifies Mem0 API export or local JSON files and duplicate detection, which clearly differentiates it from siblings like add_memory and deduplicate_memories.

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?

Explicitly states 'Use for migration or backup restoration', giving clear context for when to invoke the tool. It does not explicitly rule out alternatives such as add_memory for single inserts or deduplicate_memories for deduping existing stores, so it stops short of full when-not 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?

The description goes well beyond the annotations by disclosing concrete side effects: 'modifies cache TTLs, may evict old entries' and the caveat 'May temporarily increase latency during optimization'. It also states the return value, which is useful given there is no output schema. These details add valuable context beyond readOnlyHint and idempotentHint.

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?

Four sentences, each carrying essential information: purpose, mechanism, usage timing, side effects, and output. The most important purpose is front-loaded, and there is no filler or repetition of schema 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 two-parameter tool with fully documented schema and no output schema, the description covers all necessary call context: what it does, when to run it, side effects, latency risk, and what it returns. Nothing an agent needs to invoke it correctly is missing.

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 covers both parameters with thorough descriptions (ranges, defaults, behavior for force_refresh), so the description does not need to repeat them. The description adds no parameter-specific detail, but per the baseline for 100% schema coverage, a 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Reorganize cache for optimal hit rates', and then details the exact mechanism (promoting to L1 with 24h TTL, demoting to L2 with 7d TTL). This clearly distinguishes it from siblings like cache_stats (read-only reporting) or deduplicate_memories (removing duplicates), so an agent can tell them apart without inspecting schemas.

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

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

The description explicitly says 'Use periodically for large memory stores', giving a clear when-to-use condition. However, it does not mention when not to use it or name alternatives, so it falls just short of the highest bar.

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 and idempotent hints, so the description builds on that by adding caching behavior ('Cache-first by default'), search modes ('enhanced mode' vs 'basic mode'), and output specification (ranked results with relevance scores and the exact return type). These details go beyond what annotations provide and add meaningful context.

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

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

The description is four sentences with a logical flow: core purpose, positioning, mode and caching details, and return format. It is front-loaded with the main function and avoids redundancy. Every sentence contributes value, making it both concise and well-structured.

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 retrieval tool with no output schema, it adequately describes the return values and modes. It clarifies caching and ranking, but leaves ambiguity regarding how enhanced vs basic mode is selected (no parameter exists) and does not specify pagination beyond the limit parameter. These are minor gaps but do not prevent correct usage.

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

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

The input schema covers all parameters with 100% description coverage, so the baseline is 3. The description adds only indirect context (e.g., 'Cache-first by default' aligns with prefer_cache), but does not substantively enhance parameter understanding beyond what the schema already provides. It mentions output but not parameter-specific nuances.

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 'Find memories matching a natural language query' and positions it as the 'Primary retrieval tool for content-based lookup,' distinguishing it from siblings like get_memory (likely by ID) and get_all_memories (list all). The verb and resource are specific and immediately convey the core purpose.

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

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

The description explicitly labels this as the primary retrieval tool, giving strong contextual guidance on when to use it. It also notes cache-first behavior as a usage consideration. However, it does not explicitly state when to avoid it or name alternatives such as get_memory for ID-based lookup, though the 'primary' designation implies precedence.

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, and the description reinforces them with 'Read-only' and 'No side effects'. It adds useful context by explaining the tool reports pending operations from add_memory calls and describing the return values, which goes 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 economical and front-loaded: it opens with the core purpose, then adds the specific use case, safety characteristics, and return behavior in a few short sentences. Every sentence earns its place without 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?

For a zero-parameter read-only status tool, the description is complete: it explains what the tool does, when to use it, that it has no side effects, and what it returns. Since there is no output schema, the explicit return description fully covers the agent's need.

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 has zero parameters, so there is no schema burden to compensate for. The description adds relevant semantic context about what the tool reports and returns, making the no-parameter interface entirely self-explanatory.

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 checks the background job queue and sync status, and specifically ties it to pending async operations from add_memory calls. This distinguishes it from siblings like cache_stats and get_memory by focusing on write verification rather than data retrieval or cache management.

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

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

The description explicitly says 'Use to verify all writes completed', giving a clear context for when to call the tool. It does not name specific alternatives or exclusion conditions, but the intended use case is unambiguous enough for an agent to select it appropriately.

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 indicate readOnly=false and destructiveHint=false, but the description adds meaningful behavioral context: cache invalidation, mutation of the memory record, failure when the memory_id is missing, and the returned updated Memory object. This goes beyond the structured annotations and gives the agent a clearer picture of the 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 well-structured and front-loaded with the core purpose, but there is slight redundancy: 'Invalidates search cache' appears both as a standalone sentence and again in the side-effects sentence. This is minor and does not detract much from the overall clarity.

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 4-parameter schema, the presence of nested objects, and the absence of an output schema, the description covers everything essential: what it modifies, when to use it, failure behavior, side effects, and the return value. The tool can be invoked correctly with just this description plus 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 100%, with each parameter already well-documented in the schema (e.g., metadata merge semantics, user namespace default, failure on missing id). The description does not need to add much parameter detail, though it could have reinforced the merge/null semantics in prose.

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

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

The description clearly states a specific action ('Modify an existing memory's content or metadata') and identifies its resource. It also distinguishes itself from add_memory, which is a key sibling tool, by explicitly saying to prefer add_memory for new content.

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 concrete guidance on when to use this tool ('for corrections or adding context to existing memories') and when not to ('Prefer add_memory for new content'). It also warns that the operation fails if memory_id is not found, which helps the agent decide whether this is the right tool.

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