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

Annotations only state non-readonly, non-idempotent, non-destructive; the description adds the meaningful edge case that an oversized summary results in nodes:{status:'queued'} in the response, and that the caller owns all LLM processing. It does not contradict the annotations and provides useful behavioral context beyond them.

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 core operation is front-loaded, the caller-responsibility constraint is stated clearly, and the edge-case behavior is given in a single efficient sentence.

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 8 fully-documented parameters and no output schema, the description covers the essential operation, caller obligations, and a notable response anomaly. It relies on 'as on store' for one behavior, which is acceptable but slightly indirect; otherwise an agent has enough context 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 description coverage is 100%, so the baseline is 3. The description's first sentence restates the 'pre-computed' nature of summary, keywords, and resolved status, but adds no parameter-level meaning beyond what the schema already documents.

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 ('Archive'), a specific resource ('conversation episode'), and the key payload elements ('pre-computed summary, keywords, and resolved status'). It further distinguishes from siblings by stating 'All LLM processing is performed by the caller,' which clarifies that this tool is not the one that generates summaries or embeddings.

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 condition for using this tool is implied: the caller must already have a pre-computed summary, keywords, and resolved status. However, it never explicitly names an alternative or says 'use store instead if you need LLM processing.' The reference to 'as on store' hints at sibling behavior but does not provide concrete when-to-use vs. when-not-to-use guidance.

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

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

Annotations only say the operation is not read-only, not idempotent, and not destructive. The description adds meaningful behavioral detail: it samples memory pairs, places the threshold above the null mean, uses no labels, and adapts to model and corpus. It stops short of explicitly stating whether the calibration result is persisted or how it affects future recalls, but the added algorithm-level transparency is strong.

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 dense but well-structured: purpose first, then method details. Every sentence adds meaningful information, though the method explanations are slightly verbose and overlap with the schema descriptions.

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

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

The description covers the algorithm and method choices well, but it does not state what the calibration changes in persisted state, whether there are prerequisites (e.g., existing memories), or what the return value is. Given the absence of an output schema and the mutating nature of the tool, these gaps leave the description slightly incomplete.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the statistical rationale for each method, including when percentile is robust (anisotropic models like bge-m3) and how separation falls back to nearest-neighbour. This helps an agent choose sensible parameter values.

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 ('Auto-calibrate') on a specific resource ('the vector search threshold'), grounded in a concrete statistical basis (the null cosine distribution). It also distinguishes the different calibration methods, making the tool's intent unambiguous.

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

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

The description explains how the tool works and the method options, but it does not say when to use this tool versus alternatives like set_recall_precision or get_recall_precision. It gives no explicit usage conditions, prerequisites, or exclusion criteria.

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 only readOnlyHint=false in annotations, the description carries the full load, and it delivers extensively: irreversible lossy repairs with caps, per-run bounds, unknown check names rejected via ok=false, status semantics, removed healthy boolean, no embedding-backend contact unless fix=true, and the null_embedding repair caveat. Nothing contradicts the non-read-only annotation.

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 long but dense, with almost no filler; the first sentence front-loads the purpose and every subsequent sentence adds a concrete caveat or behavior. It could be better organized into paragraphs or bullet-like sections, but each 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 the tool's complexity, the absence of an output schema, and the many edge cases around fixes and status interpretation, the description is remarkably complete. It explains return semantics (`status`, `remaining`, `checks_run`, `issues`, `severity_summary`), dangerous repair behavior, and what absence of findings does and does not mean.

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, but the description adds real value beyond the schema: fix=true triggers auto-repair with specific behavioral caveats, the checks parameter has rejection/echo semantics and scoping implications, and the relationship between fixes and convergence is explained. It doesn't add extra meaning to agent_id or session_key, but those are already well described in the schema.

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

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

The description opens with a specific verb and resource ('Check memory database health') and enumerates the exact classes of issues detected, making the tool's function unmistakable. It does not explicitly differentiate this tool from the sibling deep_check, so it stops short of a 5.

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

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

The description gives rich behavioral guidance: when to use fix=true, how to stay agent-scoped by excluding dedup_msg_id_index, when re-runs are required until `remaining` stops decreasing, and the fact that report-only runs cannot produce liveness findings. It does not explicitly contrast check_health with sibling alternatives such as deep_check, so it lacks an explicit when-not/alternative statement.

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

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

The description extensively discloses behavior beyond the minimal readOnlyHint:false annotation: the once-per-process background check, 24h cache, no network/disk on bare calls, exact state meanings, restart requirement, no automatic updates, install-method constraints, and independence from pause_persistence. This is exemplary transparency for a tool with side-effecting capabilities.

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 content is dense and every major point is relevant, but it is delivered as one long monolithic paragraph with no bullets or headings, making it harder to parse. It is somewhat longer than necessary, with minor repetitions around 'never automatic' and 'only if you ask'.

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 fully covers the return contract: state values, reason, install command, exit_code, and output truncation. It also addresses edge cases such as detached HEAD, uvx cache behavior, and the CPERSONA_UPDATE_CHECK disable path, so an agent has everything needed 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%, but the description adds substantial meaning: refresh has a 3s budget and failure yields state=unknown; apply returns exit_code and last 40 lines, never uses a shell, and is restricted to pip/checkout installs. The description enriches both boolean parameters well beyond their schema definitions.

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 precise verb and resource: 'Report whether a newer release of this server exists' and explicitly scopes the install capability as opt-in. It clearly separates check, refresh, and apply behaviors, making the tool's purpose unambiguous even among many 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 description gives clear context for when a bare call, refresh=true, and apply=true are appropriate, and explicitly states when apply is refused (checkout at tag, uvx). It does not explicitly name alternative sibling tools, but the usage boundaries are otherwise detailed enough for an agent to decide correctly.

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 normalization rules, alias conflict resolution, dropped-item handling, pause_persistence behavior, retract semantics, and the exact response shape. It provides rich behavioral detail without contradicting the readOnlyHint, idempotentHint, or destructiveHint 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 dense and front-loaded with the core purpose, but the long single-paragraph format makes it harder to scan. It is appropriately detailed for a complex tool with nested parameters and no output schema, though it could benefit from structured breaks or bullet points.

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

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

Given the tool's complexity, nested schema, and absence of an output schema, the description is remarkably complete. It covers response fields, failure handling, retraction, persistence-pause behavior, edge cases around project_id resolution, and interaction with reconstruct. 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?

Although the schema already covers 100% of parameters, the description adds substantial meaning: anchor_ref semantics, relation endpoint rules, alias deduplication, project_id '@auto' resolution caveats, session_key partitioning, and retract scope. This is far beyond the baseline expected for fully documented schemas.

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: 'Declare associative memory after the fact' and immediately defines entities with aliases and subject–predicate–object relations. It also distinguishes itself from sibling tools by stating that the server 'extracts nothing and infers nothing' and that coverage is exactly what was declared, making its role clear.

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 clear context: declarations are evidenced by an anchor_ref, stored verbatim, and later walked by reconstruct, while retract is the only way to remove them. It does not explicitly name alternative tools or exclusion conditions, but the intended usage is evident from the behavior described.

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 only readOnlyHint=false in annotations, the description carries the burden of disclosure. It clearly states that fix=true mutates data for two check types, that fix is accepted but ignored for other checks, and that the default is dry-run preview. This is honest and useful, though it does not detail exactly what the repairs do.

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 information-dense with no filler. Each sentence earns its place: opening purpose, list of detected issues, fix/report behavior, and routing to relevant tools. The critical behavioral caveat about fix being ignored for report-only checks is clearly stated.

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 covers the tool's purpose, fix behavior, check selection, and follow-up actions, which is substantial for a four-parameter tool with no output schema. It does not describe the report/return format, but given the detailed check enumeration and routing instructions, the agent has enough context to call and interpret results reasonably.

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 real meaning by explaining that fix=true means 'apply repairs' versus dry-run, that certain checks ignore the fix flag, and that checks is an array where empty means all. This goes beyond the raw parameter 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 specific verb and resource: 'Deep heuristic analysis of memory data quality.' It enumerates the exact issues it detects (anonymous sources, short/trivial content, stale profiles, etc.) and links follow-up actions to sibling tools, making its scope clear and distinguishable from related tools like check_health.

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 clear usage semantics: fix=true applies repairs only for anonymous_source and short_content, while other checks are report-only and route to merge_memories/delete_memory/calibrate_threshold/update_profile. It also explains the checks parameter for selecting specific checks. It does not explicitly contrast with check_health, but it gives enough operational guidance to choose and act on this tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds meaningful context beyond these flags by specifying exactly what data domains get destroyed (memories, profiles, episodes) and that it is scoped to a single agent, clarifying the blast radius.

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 action and scope are front-loaded, and the usage context is given in the second sentence. 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?

Given the simple two-parameter schema and annotations that already cover destructive/idempotent behavior, the description sufficiently explains the tool's purpose and scope. Minor omissions like return values or preconditions are not critical for this kind of cleanup operation. The note about being used by the kernel adds adequate context.

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

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

Both parameters (agent_id and session_key) have detailed descriptions in the input schema, including the nuanced behavior of session_key as a partition hint rather than a data filter. The tool description itself adds no param information beyond what the schema provides, so a baseline of 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 the specific verb 'Delete' and names the exact resource: ALL data (memories, profiles, episodes) for a specific agent. It clearly distinguishes this from sibling memory-manipulation tools by emphasizing it purges everything for one agent during deletion.

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: 'Used by kernel during agent deletion.' It does not provide explicit alternatives or when-not-to-use guidance, but the context of a cleanup/teardown operation is unambiguous enough for an agent to decide.

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 and non-read-only behavior, and idempotentHint=true is present. The description adds value beyond the annotations by revealing that ownership is enforced when agent_id is provided, which is key behavioral context for callers. It does not contradict the annotations.

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

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

Two short sentences, no filler, and the core action is front-loaded. Every word earns its place by clarifying scope or the ownership condition.

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 single-ID deletion tool, the description covers the core operation and the ownership nuance. The destructive nature is already communicated by annotations, and no output schema exists, so return-value details are not required. It could mention the alternative of archiving, but that is not necessary for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents episode_id, agent_id, and session_key. The description largely restates what the schema says: delete by ID and ownership enforcement for agent_id. It does not add meaningful parameter-level detail 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: 'Delete a single episode by ID.' It clearly scopes the operation to one episode, distinguishing it from broader deletion tools like delete_agent_data or archiving tools like archive_episode. The ownership enforcement sentence adds further precision about the operation's conditions.

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 a clear usage context: use when you need to delete exactly one episode by its ID. It also notes an important condition around agent_id and ownership verification, but it does not explicitly name alternatives or explain when not to use this tool versus archive_episode or delete_agent_data.

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 establish destructive and read-only behavior, so the description adds value by explaining ownership enforcement when agent_id is provided. It does not contradict the annotations.

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

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

Two concise, front-loaded sentences with no filler. The core action is stated first and the ownership caveat follows.

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 single-item deletion tool, the description plus annotations and full schema coverage are largely sufficient. It could additionally clarify not_found behavior or relationship to bulk deletion tools, but these are minor gaps.

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 parameters are already fully documented. The description does not add meaningful parameter details beyond what the schema provides.

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 (Delete), a specific resource (memory), and a precise scope (single memory by ID). This clearly distinguishes it from sibling tools such as delete_episode and delete_agent_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 use case is implied: use this when deleting one memory by its ID. However, it does not explicitly mention when_not_to use it or name alternatives like delete_agent_data for broader deletion, leaving some routing to the agent's inference.

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 describes an export operation, which is typically non-destructive. However, annotations set destructiveHint to true, implying the tool may have destructive side effects (e.g., file overwrite). The description does not disclose this, contradicting the annotations.

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

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

The description is a single, straightforward sentence with no wasted words. It is front-loaded with the action and purpose.

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

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

The description mentions the data types exported (memories, episodes, profiles) and the format (JSONL), but does not address potential side effects like file overwriting despite the destructiveHint annotation. Given no output schema, more detail on the return value or behavior would improve completeness.

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 three parameters (agent_id, output_path, include_embeddings) with descriptions. The tool description does not add additional meaning beyond what the schema provides, so baseline score of 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 clearly states the tool exports memories, episodes, and profiles to a JSONL file for backup or portability. It uses a specific verb and resource, and distinguishes from siblings like import_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?

The description provides context for when to use the tool (backup or portability) but does not explicitly state when not to use it or mention alternatives. Sibling list makes the purpose clear enough.

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?

Although readOnlyHint=true is annotated, the description goes far beyond that, detailing the bounded nature (20 refs, 40k char budget), handling of over-budget refs via 'deferred', behavior for rows larger than budget, range serving with clamping, range failure modes ('unresolved' reasons), and budget accounting. This is rich behavioral context that annotations cannot 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 long but every sentence contributes new information. It is front-loaded with the core purpose and usage, then details bounds, range behavior, and failure modes. It is dense but efficient, with no filler or repetition. Given the complexity, this length is justified.

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

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

The tool has no output schema, so the description must explain return values, which it does thoroughly: 'deferred', 'budget_chars', 'content', 'range' with {span, content_len, node}, and 'unresolved' with reasons. It covers edge cases and provides example range objects. For a complex tool with two parameters and no output schema, this is 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?

Schema coverage is 100% and the schema already provides descriptions for both parameters, so baseline is 3. However, the description adds significant semantic depth: explains the meaning of 'mem:' and 'ep:' prefixes, how range objects work, the exact structure of node and span, inclusive ranges, offsets in stored text, and the 'deferred' and 'unresolved' fields, which the schema doesn't mention. This is beyond 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 clearly states the tool fetches full, untrimmed content for recall preview refs, distinguishing it from the recall tools that provide previews. It specifies the verb, resource, and the exact use case, and is unique among siblings (e.g., 'reconstruct', 'recall') as the only path to full row text.

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

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

Provides explicit context: 'Use after a preview-tier recall to expand only the rows that matter instead of opting the whole recall out with full_content=true.' It also clearly states the alternative (recall with full_content=true) and when not to use the tool, giving an agent clear decision criteria.

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 not only aligns with the readOnlyHint annotation but adds significant context: the context is edited on the filesystem (~/.cpersona/operating-context.toml), never via MCP. This discloses the source of truth and mutation path, which annotations alone do not provide.

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

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

Three concise sentences, front-loaded with the core purpose, followed by mode details and behavioral note. No wasted words. Structure is logical: what, how, important note.

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 one optional parameter, no output schema, and full annotations, the description covers all necessary aspects: return types (preview tier components, full section body), usage modes, and behavioral constraints (read-only, filesystem editing). It is sufficient for an AI agent to correctly invoke this 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% with a description for the 'section' parameter. The description adds value by explaining the default behavior (preview tier) and that the section is from 'doctrine_sections'. It clarifies the parameter's effect beyond the schema's own 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 clearly states the tool reads the 'server-served operating context' with a specific version (v2.5.1). It identifies the resource and its nature as 'operator-owned doctrine'. This is specific and distinct from sibling tools like 'get_profile' or 'get_contents'.

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 the two modes: without arguments returns the preview tier, and with a 'section' argument returns the full body. It mentions read-only and that editing is done via filesystem, not MCP. While it doesn't contrast with siblings, it provides clear usage 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?

Description aligns with readOnlyHint by stating 'Get', but adds no further behavioral details such as error handling for missing agents, return format, or scope of the profile.

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

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

Single sentence, concise and front-loaded. Could include more detail without being overly long, but the brevity aids readability.

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?

Adequate for a simple 1-parameter tool with no output schema. However, lack of return value description may leave the agent uncertain about the output format.

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% with a clear description for 'agent_id'. The tool description does not add any additional meaning beyond the schema, so baseline score 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 'Get the current profile for an agent' clearly states the action (get) and resource (profile) with specifier 'for an agent'. It distinguishes from sibling 'update_profile' but is slightly redundant with the tool name.

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

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

No guidance on when to use this tool vs alternatives, no prerequisites or limitations mentioned. The only implicit guidance is from the readOnlyHint annotation.

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, so the description's addition of 'pending tasks, retry config' provides some context. However, it could be more transparent about the return format or any other behavioral traits.

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, front-loaded sentence of 13 words. Every word is purposeful and concise.

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, parameterless tool with readOnlyHint annotation, the description is fairly complete. It could benefit from specifying the output structure, but given no output schema, it's adequate.

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 has zero parameters, so baseline is 4. The description does not add parameter details, which is acceptable since there are none.

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

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

The description clearly states a specific verb 'Get' and resource 'background task queue status', and mentions what is included (pending tasks, retry config). This distinguishes it from sibling tools like check_health or list_episodes.

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

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

The description implies usage for checking queue status but provides no explicit guidance on when to use it versus alternatives, nor when not to use it. No sibling comparisons 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?

Annotations already declare readOnlyHint=true. The description goes further by stating it never recalibrates or persists, and details the returned fields (beta, precision level, override flags). This adds behavioral context beyond the annotation, though it doesn't cover all edge cases.

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 paragraph that front-loads the main purpose and then provides additional details. It is reasonably concise, though some sentences could be tightened. Every sentence adds value.

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

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

Given the simple input (1 param, no output schema), the description thoroughly explains the return value and its relationship to the global default and override behavior. It is complete for a read-only tool of this complexity.

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

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

The schema covers the single required parameter (agent_id) with a description. The tool description does not add meaning beyond that, but since schema coverage is 100%, a baseline of 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 clearly states the tool reads an agent's effective recall precision, identifies it as the read-back companion to set_recall_precision, and specifies it is read-only. This distinguishes it from its sibling and provides a specific verb-resource combination.

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

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

The description explains when to use this tool (as a read-back companion to set_recall_precision, for UI loading before editing) and implies it should be used before writing. However, it does not explicitly mention alternatives or when not to use it, though the sibling set tool is clearly the counterpart.

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 far beyond the readOnlyHint annotation by disclosing the O(database) cost, the unfiltered registry, the check_crashed degradation behavior, the cap semantics, and the identity_shared case. It also explicitly states it is read-only and never repairs, matching the readOnlyHint annotation.

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

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

The text is long and dense, but each sentence carries meaningful caveats or field semantics and the purpose is front-loaded. It loses a point for being a single wall of text; light formatting or grouping would improve scannability without dropping 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?

There is no output schema, yet the description covers the shape of findings (kind, check, severity, health_severity), the special check_crashed finding, the caps/totals semantics, identity_shared, and _meta.server_version. An agent has everything it needs to invoke and interpret the result 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?

Although schema coverage is 100%, the description adds essential semantics: session_key is a partition hint rather than a filter, cap-related fields describe the returned set only, and include_summary=false can skip the prose. These details materially change how an agent would set and interpret the parameters.

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

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

The description opens with a specific action ('Pull the storage-integrity findings on demand') and explicitly contrasts it with check_health, calling out the same detector over the whole database. This clearly differentiates the tool from its closest sibling and leaves no ambiguity about the resource it operates on.

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 tells the agent when to use the tool ('instead of reading them off check_health'), when to prefer the sibling ('scope a repair with check_health(agent_id=...)'), and what to avoid ('NOT free', 'budget it by call frequency', 'deliberately no cheap subset'). The when/when-not guidance is explicit and 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 adds useful behavioral detail beyond annotations by specifying deduplication keys (msg_id/content for memories, summary for episodes). However, destructiveHint is true and the description does not disclose what destructive effect may occur, such as overwriting existing records, which leaves an important behavioral gap.

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 states the operation and scope, and the second adds essential idempotency and deduplication semantics. Information is front-loaded and 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 mutating tool with destructiveHint, the description is reasonably complete but missing return-value behavior and clarification of the destructive/overwrite effect. The schema and annotations cover parameters and high-level safety, but the description does not fully bridge those gaps.

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 no parameter-specific meaning beyond saying the source is a JSONL file; it does not elaborate on dry_run, session_key, or target_agent_id, though the schema already captures those.

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 (Import), the resource (a JSONL file), and the data kinds (memories, episodes, and profiles). This clearly differentiates it from siblings like export_memories, store, or merge_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?

The tool's intended use as a bulk importer from a JSONL file is implied, and the idempotency note suggests it is safe for repeated imports. However, it does not explicitly say when to use this instead of alternatives such as store or merge_memories, nor does it state exclusions or prerequisites.

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

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

Annotations provide only readOnlyHint=true, so the description carries the burden of rich behavioral disclosure. It goes far beyond that: explains the 200-row clamp, the 800,000-character budget, degradation semantics, presence of summary_truncated/summary_len and keywords_truncated/keywords_len, and budget_chars. It also describes how `ref` expands via get_contents and that full keywords require export_data. This gives an agent a precise mental model of response behavior and edge cases.

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 dense but highly relevant. It starts with the core purpose and then layers in bug-specific behavioral details, each earning its place by preventing misinterpretation. The structure with bug-385 and bug-255 is logical but could be slightly tightened; still, the level of detail is justified given the complexity and the absence of an 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?

With no output schema, the description must explain return behavior, and it does thoroughly. It covers truncation markers, character budgets, degraded rows, resolution echoes, and fallback semantics. It also references list_memories semantics for consistency. For a tool with this complexity, the description leaves no significant gap in what an agent needs to know to call it correctly and interpret results.

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%, which would set a baseline of 3, but the description adds substantial meaning, especially for project_id. It explains the gamma filter, '@auto' resolution, resolved_project_id, operating_context_warning, and the bug-186 sentinel fallback behavior. It also clarifies that limit is clamped to 200 rows, extending the schema's 'Max episodes to return.' These additions are critical for correct invocation and output interpretation.

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 begins with a clear, specific statement: 'List archived episodes for an agent (for dashboard display).' It names the verb (list), the resource (archived episodes), and the intended use (dashboard display), which cleanly distinguishes it from sibling tools like list_memories and archive_episode. The phrasing leaves no ambiguity about what the tool does.

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

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

The description gives explicit guidance on when to use alternatives: 'reach the rest through export_memories or a narrower filter, not a larger limit' when the clamp is hit, and 'a full keywords string is only available through export_data.' It also implies primary usage via 'for dashboard display.' However, it does not explicitly contrast with list_memories or state when not to use the tool beyond the truncation edge case, so some inference remains.

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 is exceptionally transparent about edge-case behaviors: clamps at 500 rows, content budget of 1,000,000 characters, degradation to prefixes with truncation indicators, and the interplay with preview cap, including the case where preview cap is 0. It discloses what happens when the clamp is hit (no marker) and how to access full content via get_contents with proper agent_id pairing. This far exceeds what annotations (readOnlyHint) provide and adds critical behavioral nuances that affect tool invocation and result interpretation.

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 dense and technically precise, with each sentence carrying essential details about limits, budgets, and degradation. It is not front-loaded with a summary line, but the structure is logical. While lengthy, it earns its length due to the complexity of edge cases; a shorter version would lose critical information. Minor deduction for lack of a high-level overview at the start.

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 output schema, the description comprehensively covers what an agent needs to know: return order, potential truncation, how to detect truncation (budget_chars), how to access full content via get_contents, and how to handle all-agents listings. It addresses edge cases like preview cap 0 and unmapped agents, ensuring the agent can correctly interpret results and avoid misreading truncated data as 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?

Although the schema already covers 100% of parameters with descriptions (raising the baseline to 3), the description adds substantial value beyond the schema for the project_id parameter: it details the '@auto' sentinel behavior, error conditions, and resolved_project_id echoing. For limit, it adds the clamping behavior and budget context not mentioned in the schema. This extra context significantly enhances parameter understanding despite high 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 clearly states the tool lists recent memories for dashboard display, which is specific and actionable. However, it does not explicitly differentiate from sibling tools like recall or export_memories beyond mentioning export_memories as an alternative, so it's clear but not fully distinguishing.

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 explicit guidance on when to use this tool (for dashboard display) and when to use alternatives (export_memories for full data access). It mentions using narrower filters instead of larger limits, which guides behavior, but it doesn't explicitly say when NOT to use this tool beyond those points.

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

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

The description adds behavioral context beyond the annotations by explaining that locking prevents deletion and editing. It also clarifies the conditional ownership enforcement tied to agent_id, which is not captured in the readOnlyHint, idempotentHint, or destructiveHint flags. No contradiction with annotations exists.

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 short sentences with no filler. It front-loads the primary purpose and immediately follows with the key ownership condition, making it efficient and easy to parse.

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

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

For a simple locking tool with a single required parameter, the description covers the core behavior and the important ownership nuance. No output schema exists, but little is needed because the tool's effect is straightforwardly described.

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, and the description adds value by clarifying that ownership is only enforced when agent_id is provided. This is a meaningful semantic qualifier beyond the schema's generic 'Agent ID for ownership verification' phrasing.

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 ('Lock') and resource ('a memory') and clearly states the intended effect: preventing deletion and editing. It is distinguishable from sibling tools like unlock_memory and delete_memory, so there is no ambiguity about what this tool does.

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

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

The description implies the tool is used when a memory must be protected from deletion or editing, but it does not explicitly state when to choose this over alternatives or when not to use it. The ownership note ('Ownership enforced when agent_id provided') gives conditional usage context, but no direct comparison to siblings is provided.

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

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

Annotations already mark the tool as non-read-only, idempotent, and destructive. The description adds useful behavioral context beyond those flags: atomicity, lack of intermediate files, and the deduplication behavior for strategy 'skip' by msg_id and summary. It does not contradict the annotations.

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

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

Three focused sentences, each adding distinct value: the operation and scope, the atomic/one-shot nature, and the deduplication rule. No fluff 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?

Given the 6-parameter schema and destructive annotations, the description plus schema provide enough for an agent to select and invoke the tool correctly. It could go slightly further by describing what the call returns, especially since there is no output schema, but that is a minor gap for a mutating merge operation.

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

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

Schema description coverage is 100%, so the schema fully documents all six parameters. The description adds minor value by detailing how the 'skip' strategy deduplicates, but it does not need to compensate for missing parameter documentation.

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

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

The description names a specific operation ('Merge memories, episodes, and profiles from one agent into another') and the exact resource scope. The phrase 'Atomic one-shot equivalent of export→import without intermediate files' strongly distinguishes it from sibling tools like export_memories and import_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?

The description clearly implies when to use this tool: when a single atomic merge between agents is desired, avoiding the multi-step export→import flow. It does not explicitly give exclusion criteria or name alternatives, but the contrast with export/import is enough to guide selection among related siblings.

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 only provide readOnlyHint=false, which is minimal. The description compensates fully by disclosing that the operation is non-destructive (only the channel column changes), idempotent (re-running is a no-op), that dry_run avoids mutation, and that globalize_unrecoverable moves unmatched rows to the global channel. It also explains the unrecoverable bucket behavior. 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?

The description is dense and long, but every clause contributes necessary operational detail: the transformation rule, the session_id format, non-destructiveness, idempotency, dry_run behavior, and the globalize option. It is front-loaded with the core purpose. A more structured list might improve readability, but the content is warranted.

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 migration tool with no output schema, the description covers all essential context: what gets rewritten, the exact session_id format, default behavior, the unrecoverable case, and the optional globalize behavior. An agent can correctly decide whether to call this tool and how to set the parameters without additional information.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining what dry_run=true reports (recoverable count, channels, unrecoverable bucket) and what globalize_unrecoverable does to the unrecoverable bucket. This goes beyond the simple boolean descriptions in the schema.

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

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

The description states a specific action: 'Re-channel bridge-type memories to their concrete channel', naming the resource (bridge-type memories) and the transformation (rewriting channel from session_id). It clearly distinguishes this migration utility from the sibling memory tools, which operate on individual memories or recall rather than performing a schema migration.

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 clear operational guidance: dry_run=true is the default and reports without mutating, while globalize_unrecoverable=true is an opt-in escalation. It also clarifies idempotency and non-destructive behavior. It does not explicitly name alternative tools or exclusion conditions, but there is no obvious sibling alternative for this migration, and the flag semantics effectively tell the agent when to use which mode.

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?

Despite annotations already declaring idempotentHint=true, the description goes far beyond: it discloses the exact no-op response shape, the authoritative `persisted:false` signal, the special gating of migrate_channel_axis and check_health/deep_check, the recall side effect, and the full session_key partition semantics including the lack of verification and process-wide scope on streamable-HTTP. 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?

The description is long but densely packed and logically ordered: core effect, authoritative signal, special cases, session semantics, usage. Every sentence adds necessary context. It is front-loaded with the main purpose. The length is justified by the complexity, but it is slightly verbose and might benefit from tighter phrasing.

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 carries the full burden of explaining return values, and it does so comprehensively: the no-op response fields, the id blanking, the exceptions, the read-tool behavior, the session_key scope, and the TTL. For a tool of this complexity (many affected tools, deployment nuances), nothing an agent needs to call 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?

Schema coverage is 100%, so baseline is 3, but the description adds substantial meaning beyond the schema. It explains session_key is a partition hint, not a credential, and details the consequences of omission (shared bucket, process-wide silencing). It also clarifies TTL bounds and the default. The schema gives the facts; the description gives the operational implications.

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 precise verb ('Pause write operations') and resource (this MCP server), enumerates every affected tool, and contrasts with cscheduler's separate pause_persistence. It is unmistakable what this tool does and how it differs from siblings like resume_persistence and persistence_status.

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 gives use cases (benchmarking, AB testing, ephemeral exploration) and tells when to call the sibling (cscheduler's pause_persistence) for broader coverage. The session_key semantics include when to omit it and the deployment-specific blast radius, providing thorough guidance on selecting and invoking the tool.

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

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

Annotations already declare `readOnlyHint: true`, lowering the burden. The description still adds valuable behavioral nuance: the status is scoped to a bucket selected by `session_key`, not the whole server, and in streamable-HTTP deployments a keyless caller may see `paused: true` caused by another session. This meaningfully goes beyond the annotation.

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?

Although the description is longer than typical, every sentence earns its place: the main question is front-loaded, and the subsequent sentences clarify non-obvious scope semantics. No filler or redundant restatement of the tool name or schema exists.

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 present, the description supplies the needed outcome expectations: paused state, TTL remaining in seconds, and scope. It also covers the one optional parameter and the tricky multi-session semantics. Nothing needed to call and interpret this tool 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 already documents `session_key` as an opaque partition hint with 100% coverage, so baseline is 3. The description adds extra meaning by connecting the parameter to response scope, explaining that omitting it shares a bucket with other keyless callers, and clarifying that it is not authentication or a data filter.

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: 'Report whether persistence is currently paused and the TTL remaining (in seconds).' It clearly distinguishes itself from broader server-wide status by emphasizing the returned `scope` is tied to a session key, so it is not ambiguous against sibling status or mutating 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?

The description gives clear usage context: it explains what happens when `session_key` is provided vs omitted, and warns that `paused: false` does not mean no other session is paused. It stops short of explicitly naming alternative tools or saying 'use this when X, not when Y,' but the inclusion criteria are strongly 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?

The description richly discloses output behaviors beyond the readOnlyHint annotation: the preview tier, full_content budget and degradation, match_reason structure with signal branches, omission on unscored rows, and the gate_fallback fallback. This gives the agent a detailed model of what to expect in the response, exceeding the bare annotation.

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 dense paragraph but is front-loaded with the core purpose and each sentence adds necessary behavioral or alternative-action detail. It is longer than ideal and lacks bullet or section structure, yet it contains no fluff or repetition; every sentence covers a distinct facet of behavior.

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

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

With no output schema present, the description carries the full burden of explaining return behavior. It explains the preview tier, budget marker, match_reason fields, unscored row behavior, and gate_fallback semantics. It also references the operating context via project_id auto-resolution and excludes_contents edge cases. For a 10-parameter tool with complex behavior, this is a complete and thorough description.

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%, with each parameter already having a detailed description. The tool-level description adds extra context for full_content by specifying the 200k char budget (bug-211) and the degradation behavior, which is not present in the schema. For other parameters, the description does not repeat schema content, but the budget detail lifts it above 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 'Recall relevant memories using multi-strategy search (vector + FTS5 + keyword)', giving a specific verb and resource. It also references get_contents explicitly for expanding previews, distinguishing the tool's primary function from content expansion. The multi-strategy detail adds useful specificity that separates it from a plain 'list memories' utility.

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 offers clear guidance on content handling: use get_contents(refs) for full content or full_content=true to opt out of previews. It also explains the budget behavior and when gate_fallback and match_reason appear. However, it does not explicitly compare recall with sibling recall_with_context or list_memories, so exclusions are mostly implied rather than stated.

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

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

With readOnlyHint=true already provided, the description still adds substantial behavioral context: automatic deduplication and chronological sorting, preview-tiering by default, role-based filter/merge behavior, context_filter_only, context_field_issues, the CPERSONA_EXTERNAL_CONTEXT_MODE reject option, and gate_fallback semantics. This is far beyond what the annotation conveys.

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 long but dense, and every sentence earns its place given the tool's complexity. It front-loads the core purpose and key behaviors before diving into edge cases and response fields. It could be slightly tightened by moving some low-level bug references out, but nothing is redundant.

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 complex 10-parameter tool with no output schema, the description is remarkably complete. It explains the unified return list, preview-tiering and response budget, the context_filter_only container, the context_field_issues diagnostic, gate_fallback low-confidence results, and project_id '@auto' resolution. An agent has enough information to invoke it correctly and interpret unusual outcomes.

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 meaning beyond the schema, particularly for external_context entries: which roles are merged, how non-string fields are handled, how timestamps affect ordering, and how gate_fallback affects result confidence. It does not add new semantics for every parameter, but the added detail is genuinely useful.

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?

Opens with a specific verb-plus-resource statement: 'Recall memories and merge with external conversation context.' It also differentiates from the sibling recall by stating it 'Replaces separate recall + manual merge in the caller.' An agent can clearly tell this tool apart from recall without opening the schema.

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

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

The description gives clear context: use this when you have external conversation context that should filter and merge with recalled memories, since it replaces a manual two-step process. It references recall and get_contents as related alternatives, but does not explicitly state the when-not case (e.g., 'if you have no external_context, call recall directly').

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 is consistent with the readOnlyHint=true annotation — "Stored rows are never modified" — so there is no contradiction, and it goes far beyond the annotation. It discloses the non-obvious traits the annotation can't: count is a ceiling not a fill target, ``0 <= returned <= effective`` with explicit effective_count/returned_count reporting, the absence-is-not-a-verdict caveat, bounds.omitted versus bounds.reached semantics, and the guarantee that no relevance score is returned. This is exceptional disclosure of behavioral nuance the annotation alone cannot 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 extremely long — effectively a full API specification covering policy reporting, bounds semantics, quote sequencing, role direction, bundling keys, and declared associations. It is well organized into CAPITALIZED sections and front-loads the core purpose, but it is far beyond what an agent should hold in context; much of the response-contract detail (item shape, role vocabulary, bounds semantics) belongs in an output schema or separate docs. There is also redundancy with the schema (top_k as the knob to raise for missing evidence appears in both). Density means real conciseness cost.

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 13 parameters, no output schema, and a genuinely complex response contract (bounds, count/budget policies, shortfall_reason, item shape, role vocabulary, trace additions), the description carries the full burden of documenting returns — and it does so exhaustively. It specifies the item shape, the fixed role vocabulary (supports / supersedes / corrects / qualifies / contradicts / temporal_predecessor), what fields appear only under error or clamp conditions, and what trace=true adds. Nothing an agent needs to correctly call and interpret this tool 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%, placing the baseline at 3, and the description adds real meaning beyond the schema: it frames count as "a ceiling, not a fill target, not a search depth," clarifies that budget bounds characters where count bounds items ("breadth wins"), and names top_k as "the breadth knob... what to raise when items are missing evidence" — the same key the schema flags. The description enriches parameter intent beyond the schema's bare minimums, justifying a 4 rather than 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 opening sentence states a specific verb and resource: "Assemble recall ITEMS from the candidate rows a recall produces: units of memory, each traceable to the canonical rows that support it." The core distinction is nailed precisely with "select, order and assign roles -- never compose," separating it cleanly from recall (which produces candidate rows) and from summarization tools. The tool's identity is unambiguous and differentiated from siblings like recall_with_context and get_contents.

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

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

There is rich internal guidance — "READ FURTHER IN STEPS, SMALLEST FIRST" tells the agent to pass node quotes to get_contents before falling back to the bare ref, and the breadth-vs-depth discussion explains when to raise top_k versus count. However, explicit tool-selection routing among siblings is absent: the description never states when to choose reconstruct over recall or recall_with_context, and the contrast with get_contents is implied via the expand parameter rather than stated as a decision rule. The when-to-use-the-tool guidance is present but implicit in the behavioral detail.

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 the non-obvious shared-bucket side effect: without a session_key, resuming can 're-enable writes for every other keyless session too.' It also explains what `was_active` means and that only the selected bucket is cleared. This is exactly the kind of behavioral nuance annotations do not capture, and there is no contradiction with the readOnlyHint/idempotentHint/destructiveHint flags.

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

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

The description is compact and front-loaded: the first sentence states the action and return value, and the second sentence details the critical scope side effect. No sentence is wasted, and the bolded scope warning earns its place because incorrect usage could affect other sessions.

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 one-parameter tool with no output schema, the description covers the essential agent decision points: what operation occurs, which bucket is affected, what happens when session_key is omitted, and what return value to expect. The behavior is fully specified enough for correct invocation, especially with the schema's additional session_key clarification.

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 documents session_key well, including that it is a partition hint rather than authentication. The description adds value by explaining the real-world consequence of each choice: with a session_key, only your own pause is cleared; without one, the shared keyless bucket is affected. This goes beyond the schema's neutral wording and helps the agent choose correctly.

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: 'Re-enable persistence immediately, clearing this caller's active no-persist TTL.' It clearly identifies the resource (the caller's no-persist pause bucket) and distinguishes this tool from siblings like pause_persistence and persistence_status by its reversal semantics. It also names the return value, giving the agent a concrete outcome.

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 makes the usage context clear: this tool undoes a pause and works on either the session-specific bucket or the shared keyless bucket depending on session_key. It explains the behavioral difference between providing and omitting session_key, but it does not explicitly state 'use this instead of X' or list conditions when not to use it. This is clear context without formal 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?

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), it explains that the gate is recalibrated immediately, the change is persisted, it is live without restart, and how named levels, raw beta, and empty values resolve. No contradiction with 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?

Dense but organized: purpose first, then parameter semantics, then scope. It is longer than average, but every sentence carries behavioral information; minor jargon like 'knob 3' and 'separation curve' keeps it from being perfectly crisp.

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?

Complete for a mutation tool of this complexity: it covers when to use it, all parameter interactions, reset behavior, persistence, and live effect. No output schema exists, but a setter's return value is not needed 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?

The schema already covers all four parameters (100% coverage), so the baseline is 3. The description adds real value by defining the precision-to-beta mapping (strict/balanced/lenient -> 2.0/1.0/0.5), beta override precedence, and clearing behavior, which go 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 opens with a specific verb+resource ('Set an agent's recall precision ... and recalibrate its quality gate') and later adds the distinguishing scope ('per-agent setting, not a per-recall argument'). This separates it clearly from recall-scoped siblings and from get_recall_precision.

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 exclusion — this is for per-agent settings, not per-recall arguments — and explains when the empty+beta<=0 form clears the override and returns to default. It doesn't explicitly name sibling tools like calibrate_threshold or get_recall_precision, but the context is enough for typical 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?

The description goes far beyond the annotations: it discloses dedup behavior, the TOCTOU seam, paused-persistence semantics, the breaking change in ok/skipped, the non-stable nature of reason, embedding-mode conditionality, overflow-tree queueing, and project_id '@auto' resolution failure behavior. This is exceptionally transparent for a mutation 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 information-dense and front-loaded with the most important branch ('stored'), but it is a long, nesting-heavy prose block. The pre-2.5.2b1 compatibility note and bug-186 digression add real value but also increase parsing load. It is thorough rather than concise; the structure sacrifices scannability for completeness.

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 6 parameters, nested objects, dedup semantics, rejection conditions, pausing, and version-dependent behavior, this is a high-complexity tool. The description covers response shapes, edge cases, fallback behavior, and migration notes comprehensively. Since there is no output schema, the description had to explain return semantics, and it does so exhaustively.

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 already has 100% coverage, so the baseline is 3, but the description adds meaning beyond the schema: it explains how message.id participates in dedup, how content that sanitizes to empty is rejected, how project_id '@auto' behaves when the operating context is missing, how session_key only selects a pause bucket, and how associations are stored verbatim with no extraction. This is complementary, not redundant.

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 message in agent memory for future recall.' It clearly identifies this as the write-path tool among read-side siblings like recall, traverse, and reconstruct, and explicitly names the response discriminator ('stored' / 'skipped' / 'rejected') so the agent knows what to branch on.

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 rich guidance on when the write succeeds, when it is skipped, and when it is rejected, including exact conditions like dedup, empty content, pausing, and project_id refusal. It does not explicitly contrast with sibling tools such as declare_associations or update_memory, but the write-to-memory intent is clear enough that an agent will not confuse it with recall or traverse.

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 only include readOnlyHint. The description adds extensive behavioral detail: only declared associations are returned, nothing is inferred, no record text, deterministic ordering rules, limit semantics, access-controlled record listing, and the no_such_entity error case. No contradiction exists with 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?

The description is long, but the first sentence front-loads the core purpose and every later sentence adds operational specifics (ordering, response shape, access rules, retract linkage). The only mild redundancy is restating `limit` semantics already present in the schema; overall the length is justified by the tool's complexity.

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 fully specifies the response shape, including optional fields, omitted flags, bounds, and the no_such_entity reason. It also covers ordering, limit behavior, access filtering, and cross-references to get_contents and recall, leaving nothing critical missing for a correct call.

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

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

The schema documents all parameters (100% coverage), so the baseline is 3. The description adds meaningful nuance beyond the schema, especially for `entity` (normalized comparison; multiple start entities when the name maps to more than one readable entity) and clarifies that filters behave as in recall. It does not fully detail every filter's edge cases, but the added value justifies a 4.

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: it traverses the neighbourhood of a declared entity as a graph of entities, aliases, relations, and mentioning record refs. It distinguishes itself from siblings by pointing to get_contents for record text and by referencing recall for filter semantics.

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

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

Clear context is given about what the tool produces, and alternatives are referenced (get_contents for record text, recall for filter semantics). However, there is no explicit 'use this when ... and not when ...' statement, so exclusions and preference rules are left mostly implicit.

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=false, idempotentHint=true, and destructiveHint=false. The description adds one behavioral trait beyond them: ownership enforcement when agent_id is provided. It does not disclose failure behavior when ownership check fails, the locked→unlocked state transition semantics, or reversibility, which a mutation tool should surface.

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 totaling 13 words with the primary action and effect front-loaded. Both sentences earn their place: the first states the operation and outcome, the second adds the ownership condition. 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?

For a mutating tool with no output schema, the description is thin: it omits the state transition semantics (what exactly 'unlocked' means), failure behavior when ownership fails, reversibility, and how session_key interacts with unlock. The schema's odd session_key note ('Full text on recall') is not reconciled in the description, leaving an agent with open questions for a state-changing call.

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

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

Schema description coverage is effectively 100%, so all three parameters are already documented and the baseline is 3. The description's agent_id note is consistent with the schema's 'Agent ID for ownership verification' but adds no new meaning; memory_id and session_key are not elaborated in the 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 states a specific verb (unlock) and resource (memory) and explains the effect ('to allow deletion and editing'), which clearly differentiates it from the sibling lock_memory and from delete/update operations. It stops short of explicitly naming sibling contrast, so it misses the top score.

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 purpose clause 'to allow deletion and editing' implies when the tool should be called (before editing or deleting a locked memory), and the ownership condition qualifies agent_id usage. However, no alternatives are named and there is no explicit when-not-to-use guidance or 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?

Annotations only establish that the tool writes, is idempotent, and is non-destructive. The description greatly expands on this with concrete behavioral details: locked-memory rejection, conditional ownership enforcement, sanitizer pass-through, truncation signaling, refusal of annotation-only content, and queued embed status. This is exactly the kind of context an agent needs beyond annotations.

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

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

The description is dense but every sentence carries operational information—no filler. The second sentence is long and contains minor jargon/phrasing issue ('when the cap bit'), which slightly hurts readability and prevents a perfect score.

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 covers preconditions, sanitization, truncation, refusal behavior, and embedding queue side effects—all critical for correct invocation. There is no output schema, and while key response branches are mentioned, the normal success response and how to observe the updated content are not described, leaving a minor completeness gap.

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

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

Schema coverage is 100%, so the baseline is 3 even without description-level parameter help. The description adds real meaning by explaining that content is sanitizer-limited and can be refused, and that agent_id triggers ownership enforcement. This goes beyond the schema's generic 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 opens with a clear verb+resource: 'Update memory content by ID.' This immediately separates it from destructive siblings like delete_memory and creation siblings like store. It does not explicitly name the sibling alternatives it is not, so it stops just short of a 5.

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

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

There is no explicit guidance about when to use this tool versus store, delete_memory, lock_memory, or unlock_memory. Preconditions such as 'Rejects if memory is locked' and 'Ownership enforced when agent_id provided' are useful, but they do not tell an agent how to route among the many memory-related siblings.

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

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

The description goes beyond the annotations by disclosing the 2000-character cap, the truncated:true response flag, the sanitizer behavior shared with store, and that discarded content is not stored elsewhere. This gives the agent actionable information about side effects and output, though it does not describe auth needs or full response behavior.

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

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

The description is reasonably concise and front-loaded with the core purpose, then adds the critical truncation behavior. The phrasing 'when the cap bit — branch on it' is slightly awkward, but every sentence contributes meaningful information 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 simple save operation with no output schema, the description covers the main behavioral caveat the agent must handle: truncation and the truncated:true flag. It does not specify the success response shape or whether an existing profile is overwritten, which are minor gaps but not blocking for invoking 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 value beyond the schema by naming the constant CPERSONA_MAX_PROFILE_LENGTH, mentioning the shared sanitizer, and warning that the discarded remainder is not persisted. It does not add detail on session_key, but the schema already explains it 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 clearly says the tool saves a pre-computed agent profile to the database, with a specific verb, resource, and scope. It does not explicitly differentiate update_profile from its sibling store, though the 'pre-computed' qualifier and the reference to store's sanitizer imply a distinct role.

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 is implied: call this when you already have a pre-computed agent profile to save. However, it does not explicitly state when to prefer this over store or any other sibling, nor does it give exclusions or alternatives.

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