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

With no annotations, the description carries the full burden. It discloses the clustering mechanism and optional derived creation, but does not state whether original memories are modified, whether the operation is reversible, what side effects occur (e.g., deleting clusters), or any permission requirements. The lack of such context leaves the agent guessing about the tool's impact.

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 with no redundancy. The core purpose is front-loaded, and the usage hint is appended. Every word earns its place.

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

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

The tool performs clustering and optional derived memory creation, but the description lacks details on return values (no output schema), impact on existing memories, threshold behavior, and what 'consolidation' entails. An agent would need more context to call this correctly and understand its effects.

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 all six parameters are already documented in the schema. The description adds a small amount of context about 'derived_from' linking but does not clarify parameter interactions or defaults beyond what the schema provides. 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 states a specific action (cluster similar memories via embedding similarity) and a resource (memories), with an optional derived-memory creation linked via 'derived_from'. This clearly distinguishes it from sibling memory tools like merge_memory or link_memory by focusing on clustering and derived creation.

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 a timing hint ('Use during periodic consolidation') but does not specify when to avoid this tool or how it compares to alternatives like merge_memory or link_memory. The guidance is minimal and lacks exclusions.

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

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

With no annotations provided, the description carries the burden of exposing behavior. It discloses an important safety constraint ('Only writes inside that directory') and states what the tool returns (file path, size, JSON preview). It does not mention overwrite behavior or permissions, but it covers the most material side effect for an export tool.

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

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

The description is two sentences with no filler. The first sentence front-loads the core action and target location; the second adds the safety guard and return-value summary. Every sentence earns its place.

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

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

Given there is no output schema, the description compensates by naming return values (file path, size, JSON preview). Combined with full parameter documentation in the schema and the directory-restriction detail, the agent has enough context to call 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 description coverage is 100%, so the input schema already documents both filename and includeInteractions. The description adds only the phrase 'optionally raw interactions,' which restates the includeInteractions parameter rather than adding new meaning. 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 identifies a specific action ('Export'), a concrete resource (preferences, lessons, profile, optionally raw interactions), and a target destination (JSON file under data/exports/). This clearly distinguishes it from sibling tools like import_memory or recall, making its purpose unmistakable.

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 — you would call this when you want a JSON export of memory data — but it does not explicitly state when to prefer this tool over alternatives like import_memory or get_recent_interactions. It gives clear context but no exclusions or alternative routing.

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

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

With no annotations at all, the description carries the full burden and does it well: it explicitly discloses deterministic behavior, no LLM involvement, dry-run default, and the mutation path when apply=true. This gives an agent a reliable model of side effects before calling.

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 focused sentences front-load the core purpose and then give the key behavioral switch. Every clause earns its place; no filler or redundant restating of the 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?

The definition is sufficient for correct invocation: purpose, defaults, mutation flag, and provenance are all covered, and the schema documents parameters. It would be slightly stronger if it described the shape of the returned memory candidates, since there is no output schema, but this is a minor gap for a proposal tool.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description mainly restates the apply default and adds source=captured context, which is useful but does not add substantive meaning beyond the schema's own descriptions.

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 a specific verb and resource: 'Scan recent captured interactions ... propose memory candidates'. It also differentiates from memory-write/recall siblings by emphasizing this is a deterministic scanning/proposal step, not direct storage or 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 clearly signals the intended workflow: run in dry-run to propose candidates, pass apply=true to persist with source=captured. It does not name sibling alternatives or exclusion conditions, but the use case is clear from the context.

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

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

With no annotations, the description must carry the full behavioral burden. It usefully discloses that the operation destroys a row and has a side effect ('sync the search index'), but says nothing about irreversibility, required permissions, or behavior when the id does not exist.

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

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

Two tightly written sentences with zero filler, and the core delete semantics and side effect are front-loaded before the optional-parameter advice.

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 delete tool with no output schema, the description covers purpose, the key side effect, and parameter sourcing. It could add error/not-found behavior, but nothing essential for correct invocation 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 coverage is 100% and already explains why type matters across tables, but the description adds genuinely new mapping information: 'ids from remember are preference ids, from save_lesson are lesson ids'. That source-to-type mapping is not derivable from the schema.

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

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

States a specific verb and resource ('Delete one memory row ... by id') and names the entity types it can target, which clearly separates it from read-side siblings like recall and update_memory. It stops short of naming which sibling to use when the goal is modification instead of deletion, so it does not reach full sibling routing.

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

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

Gives conditional guidance for the optional parameter ('Pass type when you know it') and explains where the ids come from. It never states when to prefer forget over update_memory or merge_memory, so the when-to-use-this-tool question is only implied.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the use of hybrid retrieval, optional graph expansion, and token budgeting, but does not clarify read-only behavior, return format, or what happens when the token budget is exceeded.

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 dense sentences with no filler: the core mechanism is front-loaded, followed by a usage cue. Every sentence earns its place.

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

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

Given 8 parameters, no annotations, and no output schema, the description gives a good high-level purpose but omits important operational details: what the assembled context looks like, how scoping params (userId/projectId/sessionId) interact, and how it differs from recall/search_history. The schema covers param semantics but not these behaviors.

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 88%, so the schema already documents most parameters. The description adds little beyond alluding to query via 'hybrid retrieval' and maxTokens via 'token budgeting'; it does not explain parameter interactions or the effect of includeGraph/includeHistory.

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 (assemble), resource (relevant memories), and method (hybrid retrieval with optional memory-graph expansion and token budgeting). It clearly identifies the tool's purpose beyond the title, though it does not explicitly distinguish it from sibling retrieval tools like recall or search_history.

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

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

The description provides an explicit usage cue: 'Use to load memory into context before a task.' This gives clear when-to-use guidance. However, it does not mention alternatives or state when not to use this tool, leaving some sibling 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?

With no annotations, the description carries the behavioral transparency burden. It usefully discloses output composition and limits (max 15 preferences, 5 most recent lessons) and frames the result as 'distilled', indicating it is not the full raw profile. It does not explicitly state side-effect freedom, but 'Get' and the summary-style output strongly imply a read 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, well-structured sentence that leads with the verb and resource, then packs the distinguishing output details efficiently. There is no filler or unnecessary 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?

Given zero parameters and no output schema, the description adequately covers the tool's input and expected return shape. Terms like 'profile sections' and 'lessons' could be slightly more explicit, but the core information an agent needs to call and understand the result is present.

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 the baseline of 4 applies. There is no parameter meaning for the description to add beyond what an empty schema already communicates.

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: 'Get the distilled user profile'. It goes beyond a generic getter by enumerating the exact components returned (profile sections, top preferences by confidence capped at 15, and the 5 most recent lessons), which helps distinguish it from 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?

No guidance is given about when to choose get_profile over related siblings like get_context, get_recent_interactions, or memory_stats. The intended use is only implied by the name and output description, with no exclusions or alternatives mentioned.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: newest-first ordering, raw interaction scope, and the line format [id] ts [kind] content. It does not mention edge cases like empty results or pagination, but these are minor for a read-only list tool.

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

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

Two sentences with no redundancy. The action, output format, filtering option, and use case are each covered efficiently, and the most important scoping information is front-loaded.

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

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

For a lightweight read-only tool with optional params and no output schema, the description adequately explains the return format, ordering, and purpose. The limit parameter is fully covered by the schema, leaving no critical gap, though the description could briefly note that results are capped.

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 provides 100% coverage for both parameters, including enums, defaults, and limits. The description adds only the notion of optional kind filtering, which is already present in the schema, so no significant extra meaning is provided.

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 states the specific verb 'List', the resource 'recently captured raw interactions', ordering ('newest first'), and the exact output line format. This distinguishes it clearly from memory-management siblings like remember, recall, and consolidate.

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 phrase 'Use for auditing history or before distilling memory' gives clear context for when the tool is appropriate. It does not name alternative tools or state explicit exclusions, so it falls short of a 5.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses several important behaviors: validation, deduplication, refusal to blindly overwrite active memory, and dry-run-by-default safety. It does not describe return format or failure modes, but the core safety-relevant traits are clearly conveyed.

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 sentences with no filler. The most important scoping information (source format) appears first, followed by safety guarantees and the activation flag. Every sentence earns its place.

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

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

For a tool with no annotations and no output schema, the description covers source, validation, dedupe, overwrite policy, and dry-run default. It omits specifics about the returned report and error handling, but the essential context for safe invocation is present.

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 baseline is 3. The description adds little beyond the schema: it restates the file-location constraint and the dry-run/apply behavior already present in the parameter descriptions. It does not add new semantic detail for userId or JSON structure beyond what the schema gives.

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: 'Import memories from a JSON array or a .json file inside data/exports/.' It clearly distinguishes the tool from siblings like export_memory and merge_memory by framing it as the import path for external memory data.

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 operational guidance ('Dry-run by default; pass apply=true to insert') but does not explicitly say when to choose this tool over alternatives such as merge_memory or update_memory. Context implies import is for bulk ingestion, but no exclusions or alternative routing are stated.

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

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

With no annotations provided, the description bears the full burden of disclosure, but it only says 'create a typed relationship.' It does not reveal side effects, whether existing links are overwritten, directionality of source/target, validation behavior, or whether memories must already exist.

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

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

The description is one compact sentence with the action front-loaded and the relationship types listed inline. There is no fluff or redundant commentary.

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 three-parameter tool with a fully documented schema, the description is minimally viable, but it leaves gaps: no return behavior, no effect on existing links, and no semantics for the relation types. Given the lack of annotations and output schema, more context would be helpful.

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 baseline is 3. The description adds little beyond the schema: 'between two memories' reinforces the meaning of sourceId/targetId, and the relation list mirrors the enum exactly. No additional semantic detail is provided.

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 action – 'Create a typed relationship between two memories in the graph' – and enumerates the valid relationship types. This clearly distinguishes it from sibling tools like update_memory, merge_memory, or consolidate by focusing on inter-memory graph links.

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 link_memory versus alternatives such as consolidate, merge_memory, or update_memory. The description only states what it does, without exclusions, prerequisites, or an explicit 'when to use' cue.

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

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

No annotations are provided, so the description carries the transparency burden. The verb 'Summarize' clearly implies a non-mutating read-style operation, but the description does not explicitly state that it makes no changes, nor does it describe any other behavioral details like cost or freshness.

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 leads with the core action and then enumerates the exact delivered statistics. Every word adds useful information, with 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?

With no output schema, the description serves as the sole source of return-value expectations, and it enumerates counts, totals, file size, timestamps, and profile sections. Some terms like 'profile sections' remain somewhat vague, but for a simple zero-parameter stats tool this is reasonably 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 tool has zero parameters, so there is no parameter semantics to clarify. The schema coverage is trivially 100%, and the description reasonably focuses on the output content instead.

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

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

The description uses a specific verb ('Summarize') and identifies a clear resource (memory usage) with a detailed list of metrics included in the output. It is distinct from sibling tools in content, though it does not explicitly contrast with them.

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 this tool is for retrieving high-level memory statistics and summaries rather than detailed records or management actions. However, it provides no explicit when-to-use or when-not-to-use guidance, nor does it name 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?

There are no annotations, so the description carries the full burden. It clearly discloses the key side effect: the source becomes superseded and provenance is recorded in metadata.merged_from. It does not mention reversibility or permissions, but the most important behavioral outcome for an agent to know is explicitly stated.

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 well-formed sentence with no fluff. It front-loads the main action and then states the two important behavioral results (source supercoded, provenance recorded). Every word earns its place.

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

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

For a simple two-parameter merge tool with no annotations and no output schema, the description gives enough to call it correctly: what it does, which parameter plays which role, and the expected side effects. It could add nuances like whether the operation is reversible, but nothing essential is missing for a typical 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 100%, so the schema already documents both sourceId and targetId clearly. The description adds context about the canonical relationship but does not add detailed parameter-level semantics beyond what the schema provides. 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 uses a specific verb ('Merge'), a clear resource ('memory'), and a precise scope ('duplicate/near-duplicate memory into a canonical one'). It distinguishes itself from sibling tools like forget, update_memory, and consolidate by clarifying that this operation is about canonicalization of near-duplicates.

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 the tool: when a memory is a duplicate or near-duplicate of another canonical memory. It does not explicitly name alternatives or give when-not conditions, so it falls just short of a 5, but the trigger condition 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?

With no annotations provided, the description carries the behavioral disclosure burden. It does disclose that the tool searches a full-text index and returns recent matching interactions, but it does not state whether the operation is read-only, how results are ranked, or whether recent interactions are subject to the limit parameter. This is adequate for a search tool but leaves some behavioral details implicit.

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 sentences with no filler. The core search scope is front-loaded, and the usage guidance is immediately actionable. Every word earns its place.

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

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

For a two-parameter tool with no output schema, the description covers the key elements: what is searched, the retrieval scope, and when to use it. It does not describe the exact return structure, but it gives enough context for an agent to invoke recall correctly before starting a task.

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 schema already documents both 'topic' and 'limit'. The description adds minimal semantic value beyond the schema, only clarifying that the search targets preferences and lessons. Baseline 3 is appropriate given full schema coverage.

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 ('Search') and resource ('preferences + lessons via full-text index, plus recent matching interactions'), which clearly identifies what the tool does. It is specific enough to distinguish recall from siblings like search_history or get_recent_interactions, even without naming them.

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

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

The description gives explicit guidance on when to use the tool: 'Use before starting a new task.' It does not mention alternatives or exclusions, but the timing guidance is clear and actionable for an agent deciding whether to call it.

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

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

With no annotations provided, the description fully carries the behavioral burden. It discloses the upsert semantics, the confidence increment on re-saving the same key, the 1.0 cap, and the return value (row id) needed by forget(). This is unusually transparent for a write 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?

Three tight, front-loaded sentences with no filler. Every sentence adds distinct value: what the tool does, how repeat calls behave, and what the caller receives.

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 3-parameter tool with no output schema, the description covers the action, the uniqueness semantics, the confidence side effect, and the return contract. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics by explaining that category+key together form the identity for the upsert and that re-saving the same key affects confidence, which is not captured in the schema property descriptions.

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 clear action: 'Save or update a user preference' and specifies the uniqueness mechanism as 'category+key upsert'. This differentiates it from generic memory tools like update_memory and the recall/search siblings.

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 intended use case is implied: call this when you need to persist or update a user preference. However, it does not explicitly state when to prefer this over siblings like update_memory, save_lesson, or link_memory, nor does it describe exclusions.

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

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

With no annotations provided, the description carries the full burden, and it does supply useful behavioral context: the operation is a write ('Record') and carries a timing constraint (only after a correction). It does not disclose persistence semantics — whether the lesson is stored permanently, surfaced by recall or search_history, or deduplicated on repeated saves — which an agent would need to anticipate downstream 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?

Two sentences, both purposeful: the first defines what the record captures, the second states when to invoke the tool. No wasted words, and the most operationally important guidance ('immediately after the user corrects your work') is prominent.

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 three simple string params, full schema documentation, and no output schema, the description covers the essentials: what to record and when to call it. The only gap is explicit boundary-setting against the closely related write-siblings (remember, extract_memories, update_memory), which is implied by the correction-specific language but never stated.

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 schema already documents all three parameters, setting the baseline at 3. The prose ('what situation, what mistake, what is the correct way') merely restates the parameter meanings rather than adding format, examples, or edge-case nuance, so the description adds marginal value beyond the schema.

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

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

The description states a specific verb and resource ('Record a lesson learned from a correction') and enumerates the three captured elements ('what situation, what mistake, what is the correct way'), which map directly to the required schema parameters. This correction-specific framing clearly distinguishes it from generic memory siblings like remember and recall.

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?

'Call immediately after the user corrects your work' provides an explicit, unambiguous trigger for invocation. However, it does not name alternatives (e.g., extract_memories or remember) or state when not to use this tool, so it stops short of full routing guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the filtered scope (kind='promp'), that results are timestamped, and that snippets are truncated to 200 characters. This exceeds a bare 'Search history' statement, though it stops short of noting ordering, case sensitivity, or 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 entire description is two efficient clauses that each add value: the first states the action and scope, and the second clarifies the return format. It is front-loaded 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?

With only two parameters, full schema coverage, and no output schema, the description is complete enough for correct invocation. It explains what comes back (timestamped snippets truncated to 200 chars), and the schema covers input constraints. Missing details like ordering are minor for this simple search use case.

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 the notion of keyword search but does not elaborate on the limit parameter or its interaction with results; the schema already documents query and limit adequately.

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

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

The description uses a specific verb ('Search'), identifies the exact resource ('past user prompts'), and adds a distinguishing technical detail (kind='prompt'). It also describes the result shape (timestamped snippets truncated to 200 chars), making it easy to tell apart from broader memory-retrieval siblings like recall or get_recent_interactions.

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 scope is clear—use this to search past user prompts by keyword—but it is stated as a capability rather than explicit routing guidance. No when-not conditions or alternative tools are named, so an agent must infer when this should be chosen over sibling retrieval 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?

With no annotations, the description carries the full burden, and it does disclose the single most important non-obvious trait: changing content creates a superseding memory by default rather than mutating the row. It still omits permissions requirements, reversibility, and what happens to the prior memory (invalidation vs retention), so it is strong but not complete.

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 dense sentences with zero filler; the in-place scope comes first and the default-fork side effect second, so the most consequential behavior is front-loaded. Nothing repeats the title or wastes tokens.

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

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

For a 9-parameter mutation tool with no annotations and no output schema, the description covers field mutability and the supersede default but says nothing about the response (does the returned id change when a superseding memory is created?) or about failure modes such as an unknown id. Adequate, but gaps remain for an agent to call it confidently.

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

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

Schema description coverage is 78%, so most parameters are already documented in the schema, including the supersede flag and the content/supersede interaction. The description restates the field set (with snake_case names that differ from the schema's camelCase) and adds no format or constraint detail beyond the schema, so it sits 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?

States a specific verb (update) and resource (memory), and enumerates the mutable fields plus the in-place vs supersede distinction. This separates it from write siblings like remember and merge_memory, but it never names an alternative explicitly, so an agent must infer routing from the field list alone.

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

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

Usage is implied by 'Update mutable fields ... in place' and by the supersede=false escape hatch, which tells the agent how to force an edit rather than a fork. However, there is no explicit when-to-use vs remember/merge_memory/consolidate guidance and no stated preconditions (e.g. that the id must exist and be live).

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