XMemo

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

Annotations already establish that this is a mutating, non-destructive, non-idempotent operation, and the description does not contradict them. It adds the semantic that the TODO is 'marked completed' and points to list_memory_todos for the ID, but it does not disclose side effects such as whether completed TODOs vanish from active lists, whether repeated completion errors, or whether the action is reversible. The added context is useful but not rich.

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

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

The description is a single well-structured sentence that packs the operation, trigger, and cross-reference without wasted words. It is front-loaded with the verb and resource, making it immediately scannable.

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

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

For a simple two-parameter mutation with an output schema and reasonable annotations, the description covers the core purpose, trigger, and ID sourcing. It lacks explicit mention of post-completion state or alternatives, but those gaps are minor and the overall package is sufficient for an agent to select and 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?

The input schema already provides 100% coverage for both parameters (todo_id and note), so the baseline is 3. The description adds value by explaining that the todo_id is the exact memory reference shown by list_memory_todos, which helps the agent correctly obtain the ID before calling the tool.

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 ('Marks'), identifies the exact resource ('a TODO/action item'), and includes the user trigger ('when the user says a saved task is done, resolved, or no longer needed'). It clearly distinguishes this from sibling tools like create_memory_todo and list_memory_todos by focusing on the completion action.

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

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

The description explicitly states when to use the tool ('when the user says a saved task is done, resolved, or no longer needed') and references list_memory_todos as the source for the exact memory reference, implying a look-then-complete workflow. It does not explicitly exclude alternatives like update_project_todo, but the narrow purpose makes the intended usage clear.

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 readOnlyHint=false, so the write nature is covered. The description adds that it creates a todo with optional due time, but doesn't disclose other behavioral traits like return format, idempotency, or side effects. With annotations present, the added value is modest.

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

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

The description is a single sentence, front-loaded with the core action ('Creates a TODO/action item'), and includes the key trigger context. No filler or redundancy.

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

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

With an output schema present, return values need no explanation. The description, annotations, and full parameter schema cover the essential use case. Could be more complete with explicit notes on when not to use, but for a simple create tool it is 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?

Schema coverage is 100%, and every parameter has a description. The tool description does not add additional meaning beyond the schema, so the baseline of 3 is appropriate. It mentions 'optional due time' which maps to due_at, but no further enrichment.

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 it creates a TODO/action item in XMemo, with optional due time, and specifies the trigger context (user asks to save a task, follow-up, action item, or reminder). This distinguishes it from sibling tools like complete_memory_todo or list_memory_todos.

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 clear context: 'when the user asks to save a task, follow-up, action item, or reminder-style item to revisit at a later time.' This gives a clear usage trigger, though it doesn't explicitly mention alternatives or exclusion cases, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered; the description usefully adds what content is captured. It does not say whether a second call supersedes or appends to an existing snapshot, how long the snapshot lives, or that state_key lets you target a particular working-state entry — the kind of context 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?

Two sentences, zero waste, with the capture contents front-loaded ahead of the trigger condition. Nothing is repeated from the name or title.

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?

Annotation coverage plus an output schema means the description need not restate safety or return shape; all parameters are optional with defaults, so the tool is callable with no arguments.

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 per-parameter descriptions and defaults for all 9 optional parameters, so the schema does the heavy lifting. The description's mention of TODOs, pending decisions and recent events implicitly maps to reminder_limit, decision_limit and timeline_limit, but says nothing about scope, bucket, session_id, ttl_seconds or metadata_json beyond the schema text.

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

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

States a specific verb (save) and enumerates the resource contents it captures: active state, recent events, TODOs, pending decisions. This tells an agent it is a composite snapshot rather than a single-key write like update_state or remember, but it never names those siblings or restore_restart_snapshot to sharpen the boundary.

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?

'Relevant before handoff or when context may be lost' gives a concrete trigger condition for use. It stops short of when-not guidance or naming restore_restart_snapshot as the counterpart that reads the snapshot back, so the agent must infer the save/restore pairing from names alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, providing safety information. The description adds the two explanation modes (existence vs. retrieval match) but does not disclose additional behavioral traits such as how explanations are generated or any limitations. This is adequate but not rich.

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

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

The description is a single, focused sentence that front-loads the core action and scope. No wasted words or redundant information.

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

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

For a relatively simple, read-only tool with complete schema coverage, an output schema, and clear annotations, the description is largely sufficient. It could be slightly more complete by mentioning that it is complementary to recall/search tools, but the current text covers the essential use case.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters clearly. The description adds no extra parameter-level meaning, so the 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's function: explaining why a memory exists or matched a query. This is a specific verb+resource definition that distinguishes it from sibling tools like recall (retrieval) and update_memory (modification).

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 provides explicit context for when to use the tool ('whenever the user asks why something was saved there or why it was retrieved'). However, it does not mention any when-not scenarios or alternative tools by name, so it falls short of full guideline coverage.

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 declare destructiveHint=true and idempotentHint=false; the description adds the crucial default (soft, recoverable), the undo path (restore_memory), and the confirmation requirement for hard deletes. It does not say what happens to linked relationships or whether hard delete is available for all target types, which limits it below a 5.

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

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

Three tight sentences, front-loaded with the actionable delete targets before the mode/recoverability rules. The first sentence is dense but every clause carries routing information; no filler.

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

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

An output schema exists so return values need not be described, and the description covers the high-risk pieces: recoverability, permanence, confirmation, and ambiguity handling. Remaining gaps are secondary behaviors such as effects on memory links or which target types support hard deletion.

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

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

Schema coverage is 100%, so baseline is 3. The description goes further by explaining how target values are obtained ('current/latest', exact memory reference, exact IDs from list_memory_todos / list_ledger_transactions) and by naming mode='hard' explicitly, but it says nothing about query_hint, replacement_content, or metadata_json.

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

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

States a specific verb (delete) and enumerates the exact resource types (memory, TODO, Ledger transaction) plus how each target is addressed. It names the sibling tools that produce the required references (list_memory_todos, list_ledger_transactions), so it is distinguishable from restore_memory and update_memory without opening a 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?

Gives clear routing context: default soft delete is recoverable via restore_memory, mode='hard' is permanent and needs explicit user confirmation, and ambiguous targets are disambiguated before deletion. It does not contrast against other mutating siblings like update_memory or remove_memory_relationship, so the exclusion guidance is incomplete.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying what the tool actually returns (connection status, connected account/agent), which the annotations do not cover.

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

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

A single, front-loaded sentence that states the core purpose, trigger condition, and output. Every phrase earns its place with no redundancy or filler.

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

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

Given the tool's simplicity (0 params, output schema present, annotations covering safety), the description fully captures what the agent needs to know: what it does and when to invoke it. No additional context is necessary.

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

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

The tool has zero parameters, so the description cannot add parameter-specific meaning. Baseline of 4 applies for no-parameter tools; the description correctly avoids inventing parameter details.

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 specific verb 'Checks' and resource 'XMemo connection status and the currently connected account/agent'. It also includes the user trigger context, distinguishing this from all sibling memory/ledger/todo 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 explicitly says 'when the user asks whether XMemo is connected', providing a clear usage context. It does not mention alternatives, but no sibling tool serves this connection-check purpose, so explicit exclusion is unnecessary.

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 (readOnlyHint, idempotentHint, destructiveHint), the description adds meaningful context: requires memory:read permission, does not mutate project memories, access is audit-logged. It also clarifies the effect of parameters on the returned pack, enhancing transparency of 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?

Three sentences, front-loaded with the primary purpose, followed by permission/behavior notes and parameter guidance. Every sentence carries essential information with no fluff.

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

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

For an 11-parameter tool with an output schema, the description covers purpose, auth requirements, behavioral guarantees, parameter relationships, and points to the sibling alternative. With an output schema present, return values don't need description. Comprehensive for the tool's 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?

While the schema documents all parameters (100% coverage), the description adds cross-parameter semantics: max_items/max_tokens bound the whole pack, recent_hours affects only timeline, durable_query requires include_durable_context. This adds value beyond individual 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 clearly states the tool reads a bounded context pack for one project, listing its contents (state, TODOs, decisions, timeline, recent memories, optional durable recall). It distinguishes itself from sibling tools by specifying exact project_id for a whole-project snapshot and recommending recall_context otherwise.

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 usage guidance: use with exact project_id for whole-project snapshot, otherwise use recall_context. Also explains parameter scoping (max_items/max_tokens bound whole pack, recent_hours affects only timeline, durable_query requires include_durable_context), which clarifies when to adjust each parameter.

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

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

The description adds behavioral details beyond annotations: requires memory:read permission, makes no memory changes, clamps limit to 1-500, and exact filters for session_id and event_type. The readOnlyHint and idempotentHint annotations are consistent, so no contradiction.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds meaningful value (purpose, permissions, alternatives, parameter behavior). No wasted words.

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

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

Given the readOnly annotations, output schema, and the sibling tool context, the description fully covers the key aspects: purpose, ordering, permissions, parameter constraints, and use cases. Nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% and parameter descriptions already explain limit clamping and exact filters. The description repeats these constraints without adding new semantic information, so it meets but does not exceed the baseline for 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 reads timeline events newest first, distinguishing it from siblings like recall_context. The verb 'Read' and resource 'timeline events' are specific and unambiguous.

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

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

Explicitly says when to use this tool ('recent history or session resumption') and when to use the alternative ('recall_context for semantic multi-memory context'). This provides direct usage guidance and differentiates from sibling tools.

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

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

Annotations already disclose this is a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description usefully adds the same-store/space and visibility preconditions, but says nothing about behavior on duplicate links (relevant given idempotentHint=false) or whether 'explicit' differs from implicitly inferred links.

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?

One sentence, front-loaded with the verb and resource, with no filler. The capitalized 'Free' is ambiguous and slightly muddies an otherwise clean line, and the preconditions are packed in without losing clarity.

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

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

For a write operation with no output schema, the definition covers the core action and its preconditions but omits what the call returns, whether duplicate links error or are created, and how edge_kind choices behave. Adequate to call, incomplete to call confidently.

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

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

Schema coverage is nominally 100%, but the per-parameter text is boilerplate ('Input value for the Link Memories tool'), so the schema adds little real meaning. The description indirectly maps to the two memory-id params via 'between two visible personal Memories' but never explains edge_kind or its default value of 'references', leaving it opaque.

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

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

States a specific verb (Create) and resource (an explicit link between two Memories) with clear scope constraints (same owning store/space, visible, personal). Siblings like remove_memory_relationship and update_memory_relationship imply a relationship family, but the description never names them, so the agent gets no direct sibling contrast.

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 usage context is only implied by preconditions ('two visible personal Memories in the same owning store/space') rather than stated as when-to-use. There is no guidance on when to link versus update_memory_relationship / memory_relationships, nor what to do when a link already exists.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds nothing beyond that beyond the notion of 'unresolved conflicts', which the schema default on unresolved_only already implies. Adequate but not additive.

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 compact sentences, purpose front-loaded, no filler. Every phrase 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?

A read-only list tool with rich annotations, a full output schema, and 100% parameter coverage needs little prose to be callable correctly. The only gap is not routing the agent between this and resolve_memory_conflict, which is a usage rather than completeness issue.

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% for all three parameters (limit, output_json, unresolved_only), so the schema carries the semantics. The description's mention of 'unresolved conflicts' mildly reinforces unresolved_only but adds no format, pagination, or default guidance 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?

States a specific verb and resource: 'List conflicting/inconsistent memories.' That is unambiguous about what the tool returns. It does not distinguish itself from the sibling resolve_memory_conflict, which an agent could easily confuse with a listing tool, so it falls 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?

'Relevant when the user/admin asks to review unresolved conflicts' gives a clear trigger condition. It does not say when to prefer resolve_memory_conflict over this listing, nor does it note what to do after finding conflicts, so the exclusions/alternatives side is missing.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds useful behavioral context by stating the output is a 'concise text answer' and that it covers 'open or completed' item statuses. It does not go deep into pagination or response details, but with annotations covering safety, this is sufficient.

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, highly informative sentence that front-loads the main action and includes a conditional usage note. Every clause earns its place, with no wasted words.

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

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

Given the tool's simplicity, the presence of a full output schema, and annotations guaranteeing safety, the description is mostly complete. It covers the core use case and exclusions, but does not explicitly mention how to set filters like due_before or item_status, which are left to the schema. Still, this is adequate for a list 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 description coverage is 100%, and the parameter descriptions in the schema fully document each parameter. The tool description adds no additional parameter semantics, so the 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 lists open or completed TODO/action items as a concise text answer, with a specific verb and resource. It also distinguishes itself from the visual TODO workspace, making its scope 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 explicitly says when to use the tool ('when the user asks how many tasks, follow-ups, or saved action items are currently pending or completed') and explicitly states what not to use it for ('do not use it to open, browse, filter, or manage the visual TODO workspace'). However, it does not name alternative tools, leaving a slight gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds no behavioral detail beyond purpose — nothing about ordering, how many versions are returned, or whether the current version is included. With annotations carrying the load, this is adequate but thin.

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, purpose front-loaded, zero filler or restatement of the title. Every clause contributes either what the tool does or when to reach for it.

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

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

An output schema exists, so return-value explanation is unnecessary, and both parameters are fully described in-schema. What remains unstated is minor but real: ordering of versions and whether the latest/current revision is part of the list, which an agent may need to 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% and both parameters (memory_id, output_json) are documented in-schema, including that memory_id is the "Exact XMemo memory reference shown by search or recall." The description adds no further parameter meaning, so the baseline 3 applies.

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

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

States a specific verb+resource: "Show version history for a memory." An agent can immediately tell this is a read of historical revisions rather than the current record. It does not explicitly contrast with siblings like read_memory or restore_memory, which keeps it from 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?

Gives a clear triggering condition: "Relevant when the user asks for previous content or changes over time." This maps intent to tool selection well. It stops short of naming when not to use it (e.g., use read_memory for current content), so no exclusions or explicit alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered elsewhere. The description adds that results are limited to explicit links on a visibility-scoped memory, which is genuinely useful context, but it says nothing about pagination behavior, ordering, or what happens when no links exist.

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

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

A single tight sentence with the scope constraint front-loaded and no filler. It is arguably over-compressed for a tool with pagination, but no sentence is wasted.

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

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

For a simple read-only tool with full schema coverage and annotations that carry the safety profile, the description covers the essential scoping. Since there is no output schema, a brief word on what a returned relationship looks like would have closed the remaining gap.

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

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

Schema description coverage is 100%, so memory_id, limit, and cursor are already documented in the schema; the baseline is therefore 3. The description reinforces that the lookup targets a single visible Memory, but adds no format, cursor, or limit semantics 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?

States a specific verb ("Read") and resource ("explicit personal links for one visible Memory"), which distinguishes it from write-side siblings such as link_memories and remove_memory_relationship. It does not, however, name those siblings or otherwise explicitly route the agent, so it falls 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?

The clause "no automated analysis" implies this tool returns only human/agent-authored links rather than inferred ones, which is a useful usage boundary. But there is no explicit when-to-use, when-not-to-use, or named alternative, so usage is only 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only the scope of aggregation ('all saved memories') and the optional time range, without disclosing behaviors such as top_n truncation of groups or what an unbounded window defaults to. Adequate but thin against an already-rich annotation set.

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?

One sentence, front-loaded with the core capability, with zero redundant text. The tail clause blends purpose and usage guidance, but nothing is wasted and nothing important is buried.

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 an output schema present, rich annotations, and 100% schema coverage across 8 optional params, the description only needs to establish purpose and trigger, which it does. A note on group truncation via top_n or default time-window behavior would make it fully self-sufficient.

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

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

Schema description coverage is 100% and the parameter docs are unusually detailed (RFC 3339 formats, half-open interval semantics, heuristic fallback for since/until). The description's mention of grouping by type, source, location and time range loosely maps to group_by/memory_type/since/until but adds no syntax or behavior beyond the schema. Baseline 3 is appropriate.

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

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

The description names a specific verb ('Shows') and resource ('aggregate statistics for all saved XMemo memories') and enumerates the aggregate dimensions (type, source, location, time range), which clearly separates it from retrieval siblings like read_memory or recall. It stops short of naming an alternative tool explicitly, so it lands just under the top tier.

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

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

It states the triggering intent plainly: 'when the user asks for counts, breakdowns, or distributions.' That is a concrete when-to-use condition. It gives no when-not condition or named alternative (e.g. use recall for individual memories), which keeps it from a 5.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and not idempotent. The description adds the 'proposals bucket' context, suggesting a staged proposal workflow, but does not explain what 'propose' entails (e.g., whether approval is needed, whether it is directly applied, or what happens on success/failure). It provides some value beyond annotations but lacks depth.

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

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

The description is one concise, front-loaded sentence. It states the primary action and resource without unnecessary filler. 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 tool has 7 parameters, a proposal mechanism, and a complex conceptual model (proposals bucket, profile paths), the description is too sparse. It does not explain the proposal workflow, the relationship between 'field' and 'value', or how this interacts with memory. While an output schema exists, the description still leaves major operational gaps for an agent to invoke the tool correctly.

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

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

Despite 100% schema description coverage, the descriptions for the required parameters 'field' and 'value' are tautological ('Input value for the Propose Profile Mutation tool.'), adding no real meaning. The tool description hints at the path template but does not define allowed field names or value formats. The optional parameters have somewhat better descriptions (e.g., scope, team_id), but key semantics are missing.

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

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

The description clearly states the action ('Propose'), the resource ('profile mutation'), and adds a specific location ('proposals bucket at path profile.{field}'). This distinguishes it from sibling tools like propose_write and propose_todo_mutation, which target different resources.

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 on when to use this tool versus alternatives. The description implies it is for profile changes, but it does not explain when to choose this over propose_write, update_memory, or other siblings, nor mention any exclusions or necessary conditions.

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 this is not read-only (readOnlyHint=false), and the description adds the storage location ('proposals bucket' and 'todos/{action}'). However, it does not disclose what happens when a proposal is made, whether it is actually applied, or any side effects or approval flow.

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

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

A single sentence that front-loads the tool's purpose and path template. Every word contributes meaning, with no filler or repetition.

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

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

The description is minimal for a tool with 7 parameters, an output schema, and many siblings. It lacks context on the proposal lifecycle, what 'propose' means in practice, and how this differs from other proposal and todo tools. It is adequate but leaves important 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 schema already documents parameter meanings. The description only adds the 'todos/{action}' path template, which gives slight context for the 'action' parameter but does not compensate for the generic schema descriptions of 'content' or other 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 uses a specific verb ('propose') and resource ('todo mutation'), and further specifies the storage path 'todos/{action}'. This clearly distinguishes it from sibling tools like propose_write and propose_profile_mutation, which target other resource types.

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

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

The phrase 'under the proposals bucket' implies this is for proposing rather than applying mutations directly, but there is no explicit guidance on when to use this tool versus alternatives like create_memory_todo or update_project_todo. No exclusions or alternative tool names are 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?

The description adds behavioral context beyond the annotations by clarifying that this operation is a 'proposal' rather than a direct modification, and it identifies the tier-gating trigger. Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description supplements with the proposal semantics without contradicting the structured data.

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

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

The description is a single, well-structured sentence that immediately identifies the action and context. It is front-loaded with the verb 'Propose' and contains zero wasted words, making it highly concise and readable.

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 detailed input schema and the presence of an output schema, the description adequately covers purpose and usage. It explains when to use the tool and what it proposes, which is sufficient for a generic proposal tool. It does not describe the proposal lifecycle (e.g., approval or queuing), but this is likely captured by the output schema, so the description is reasonably complete.

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

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

The input schema provides 100% description coverage for all 8 parameters, so the schema already handles parameter semantics. The tool description adds little parameter-specific meaning beyond listing resource types (memory, todo, profile), which aligns with the baseline score of 3 for 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's function: 'Propose a write operation (memory, todo, profile etc.)' with a specific verb and resource types. It also provides a trigger condition ('when direct modifications are denied due to tier-gating'), which gives context. However, it does not explicitly distinguish itself from the sibling tools propose_todo_mutation and propose_profile_mutation, missing the highest bar for differentiation.

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

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

The description explicitly states when to use the tool: 'when direct modifications are denied due to tier-gating.' This is a clear usage context. It does not name alternative tools or state when not to use it, so it falls short of the 'explicit when/when-not/alternatives' criterion for a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description contributes the meaningful extra constraint that this does not grant cross-user or admin access. It says nothing about result volume, pagination semantics, or the 90-day span limit that lives only in the schema.

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

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

Three short sentences, front-loaded with purpose and scope, then the source semantics, then the access boundary. No filler and nothing buried.

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?

An output schema exists and nine parameters are fully documented, so the description needn't explain returns. It covers scope, source modes, and the access boundary, but leaves the agent to discover pagination (limit/offset defaults) and the since/until window rules from the schema alone.

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 would be 3, but the description adds real semantics for the source parameter that the schema obscures ('source' is described generically as a 'source filter for system statistics'). Clarifying that 'events' returns action/time/target events while 'consolidation' returns consolidation/lifecycle/reflection history is genuine value beyond the structured field.

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

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

States a specific verb and resource ('Query audit records') plus the scoping constraint ('within the caller's authorized memory scope'), and enumerates the two source modes. It doesn't differentiate from nearby siblings like get_timeline or explain_memory, so an agent must infer which one to reach for.

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 source='events' vs source='consolidation' split gives implied usage guidance for choosing a record class. However, there is no explicit statement of when to use this tool versus the audit-adjacent siblings (get_timeline, memory_stats, explain_memory), and no prerequisites are spelled out.

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 readOnly/idempotent annotations, the description discloses critical behavior: bare IDs resolve to latest head and are unpinned, revision-pinned continuation prevents torn reads, and version_changed forces restart. It also states that embeddings are never returned. This is exactly the kind of behavioral context the annotations cannot 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?

The description is dense but well front-loaded, starting with the core operation and then explaining continuation and pinning. Every paragraph carries necessary behavioral detail about revisions, offsets, anchors, and Documents. There is little wasted language for a tool with this much continuation semantics.

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 rich annotations, full schema description coverage, and output schema, the description covers the remaining gaps an agent needs: revision pinning, Document anchor behavior, version mismatch handling, and the no-embeddings guarantee. No essential call behavior is omitted for this complexity level.

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 cross-parameter meaning: memory_id can be a bare ID, revision, or document reference; anchor pairs with ordinal; version pins like a revision. The only ambiguity is that it refers to 'next_offset' while the schema parameter is named 'offset', which could cause a minor lookup mismatch.

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: reading one exact authorized XMemo memory or Document in character windows. It clearly distinguishes this precise-read tool from recall/search discovery tools by noting that IDs are returned by recall or search. An agent can identify the operation 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?

It gives clear usage context: use a bare memory ID for the initial read, then use the returned revision with next_offset to continue long content. It also explains Document anchor/ordinal starts and version pinning. It does not explicitly state exclusions against siblings such as recall, but the discovery-versus-exact-read split is 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low, and the description adds real behavior: results are relevance-ranked and few in number, default search spans all buckets, and an explicit bucket disables fallback widening. It does not discuss result volume limits or when ranking may be overridden by time ordering, but the output schema covers the return shape.

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

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

Three sentences, front-loaded with purpose, then default scoping, then sibling routing. Every sentence carries distinct information and none is padded.

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

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

For a 17-parameter retrieval tool with an output schema, the description covers purpose, default scope, the bucket override, and the sibling boundary — the decisions an agent must get right before calling. Time-window and query_mode behavior is left to the schema, which documents it well, so the remaining gap is minor.

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

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

Schema description coverage is 100%, so the schema already documents all 17 parameters thoroughly, including time semantics and query_mode. The description echoes the high-level knobs (path/type controls, working-memory preference) and the bucket fallback rule, which largely restates the schema rather than adding new meaning — the baseline 3 applies.

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

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

The description states a specific verb and resource ("recall a few relevance-ranked memories") plus the operating scope ("before answering", path/type controls, working-memory preference). It also names the sibling it is not — recall_context — so an agent can distinguish the two without opening either 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?

It gives an explicit selection rule: "Use it for a quick best-effort lookup; use recall_context when the answer needs a bounded multi-memory context pack." It also documents the bucket-scoping decision (unscoped by default; pass bucket to narrow, never widened by fallback), leaving nothing to 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?

Annotations already declare this as a safe, idempotent, non-destructive read with no open-world access. The description adds the tiered retrieval structure, which is useful behavioral context, but says nothing about failure behavior (e.g., missing skill/revision) or result shape. With annotations covering the safety profile, a 3 is appropriate.

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

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

Two tight sentences with no filler; the core purpose is front-loaded and the level taxonomy follows immediately. Every clause 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?

An output schema exists, so return values need not be described. However, the description rests on undefined jargon (Level 0/1/2, XMemo) and never clarifies which parameter drives which level, leaving the agent to guess the required inputs for root vs resource recall.

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 nominally 100%, but four of five parameter descriptions are boilerplate ('Input value for the Recall Cloud Skill tool'), so the schema adds little real meaning. The description partially compensates by tying query to Level 0 and revision_id to Level 2 pinning, but leaves slug, skill_id, and resource unexplained.

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

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

The description states a specific verb+resource ('Recall reusable Cloud Skills, instructions, or sub-resources saved in XMemo'), which is clear. It does not explicitly differentiate itself from close siblings like recall, recall_context, or read_memory, so an agent must infer the distinction.

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 outlines three retrieval modes (Level 0 discovery by query, Level 1 root recall, Level 2 resource recall with pinned revision_id), which implies when each invocation style applies. However, it names no alternative tool and gives no when-not guidance, so the routing logic is left to 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?

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: output is bounded, over-budget memories are omitted and reported, and the remedy is raising max_tokens or switching to recall. It does not mention other edge behaviors such as the activity_log fail-closed case, but those are handled by the schema.

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

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

Three sentences with no waste: purpose first, routing second, budget semantics third. Every sentence carries decision-relevant information for an agent.

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 21-parameter tool, the description covers the decision axes an agent needs: when to choose it, which siblings to prefer, and how output bounding works. The schema and the output schema carry the remaining parameter and return-value detail.

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 practical consequence of max_items/max_tokens: what gets dropped and how it is reported, which helps an agent set those two budgets 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 verb and resource ('Build a read-only, bounded context pack from multiple relevant memories') and explicitly contrasts it with sibling tools ('recall' for quick lookup, 'get_project_context' for a whole-project snapshot). An agent can pick this tool 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?

It names the when-to-use condition ('when an answer needs several memory items or scoped/path-filtered context') and names both alternatives with the conditions that favor them. It also gives an escalation path when results are truncated ('raise max_tokens or use recall').

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 it is a write operation (readOnlyHint=false) and non-destructive. Description adds no further behavioral context (e.g., side effects, permissions). Adequate but no extra value 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?

Two concise sentences, front-loaded with verb and purpose. No wasted words. Every sentence serves a distinct purpose (what it does, what it doesn't).

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 6 parameters (1 required), output schema exists, and many sibling tools, the description is sufficiently complete. It clarifies the tool's niche without needing longer explanation. Slightly lacking on what exactly 'record' means in terms of storage/retrieval, but acceptable.

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 parameters are fully documented. Description adds no additional meaning beyond the schema. 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?

Description clearly states verb 'Record' and specific resources: 'significant session event, milestone, decision, or handoff note'. Explicitly distinguishes from sibling 'remember' by noting it is not for durable facts/preferences.

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 when-not-to-use ('Not for durable facts/preferences') and suggests alternative ('use remember'). Also hints at context ('useful for reconstructing recent work').

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 (readOnlyHint=false, idempotentHint=false), the description discloses useful behavioral details: 'Existing Projects paths attach automatically' and that create_project 'may create a missing project only when explicitly enabled.' These are not present in the annotations and add meaningful context for the agent. However, it does not cover other behavioral aspects like deduplication or mutation details, but the bar is lowered given 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 four short sentences, purpose-first, with no filler. Every sentence adds value: the main purpose, a behavioral note, a compatibility caveat, and explicit alternative routing. It is concise and well-structured.

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

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

With 20 parameters and full schema coverage plus an output schema, the description does not need to enumerate parameters. It provides the essential context: durable vs. transient, auto-attachment behavior, and sibling tool alternatives. It could mention the default dedupe behavior or that it can also update existing memories, but the coverage is sufficient for a tool with a rich schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds a small amount of parameter behavior by explaining the create_project compatibility input's gating, but it mostly restates what the schema already says. No additional syntax or format details are given for required parameters like content or path 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 'Save durable information for future recall'—a specific verb and resource—and explicitly contrasts with transient chat. It also distinguishes from sibling tools by directing financial records to add_expense and actionable work to create_memory_todo, clarifying the tool's scope.

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 when-to-use guidance ('Save durable information for future recall') and when-not-to-use guidance ('skip transient chat', 'Use add_expense for financial records and create_memory_todo for actionable work'). It also notes the create_project compatibility input should only be enabled when explicitly requested, providing a clear usage boundary.

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 establish this is a non-destructive, non-idempotent write, and the description adds genuinely useful context beyond them: what is removed (the association only) and what survives (both Memories plus a retry receipt). This explains why destructiveHint is false for a 'remove' operation and touches on retry 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?

A single front-loaded sentence with no filler or repetition; the constraint 'only an explicit personal association' leads and the preservation guarantee follows. It is efficient, though very terse relative to the operation's concurrency semantics.

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

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

For a 3-parameter mutation tool with annotation coverage, the description states the key behavioral contract (association removed, memories preserved). It does not address permission requirements or what the retry receipt contains, but with no output schema and full schema coverage this is adequate rather than rich.

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 nothing about memory_id, relationship_id, or expected_version beyond what the schema already documents, and the schema itself covers the VERSION_CONFLICT behavior.

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 gives a specific verb ('Remove') and resource ('an explicit personal association'), and the qualifier 'only' plus 'preserving both Memories' clarifies this is not a memory deletion, which separates it from siblings like forget or restore_memory. It stops short of naming an alternative outright.

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 when-to-use or when-not-to-use guidance and no named alternative (e.g., update_memory_relationship or link_memories). The phrase 'only an explicit personal association' hints at a scope restriction but leaves the selection decision entirely to 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?

Annotations already declare destructiveHint=true, readOnlyHint=false and non-idempotent, so the danger is signposted structurally. The description adds the meaningful governance constraint that a human must pick the strategy, but it never says which memories are destroyed, whether resolution is reversible, or that the default strategy is mark_conflict.

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, both load-bearing: the first states the action, the second states the precondition. No filler and the action is front-loaded.

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

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

For a destructive, non-idempotent mutation with five parameters and no enum on resolution_strategy, the description says nothing about what consequences a resolution has on the conflicting memories or which strategies are lossy. Because an output schema exists, return values need not be described, but the destructive semantics are a substantial omission.

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

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

Schema description coverage is 100%, so all five parameters including strategy names are already documented in structured form. The description adds nothing beyond the word 'listed' pointing at conflict_id, so the baseline 3 applies.

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

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

Names a specific verb (resolve) and resource (memory conflict), and the qualifier 'listed' signals the conflict must already exist rather than be created here, which distinguishes it from list_memory_conflicts. It stops short of saying what 'resolving' actually does to the underlying 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?

'Intended only for when the user/admin explicitly chooses a resolution strategy' is a real precondition and an exclusion, not just a restatement. It does not name list_memory_conflicts as the required discovery step in the description (that only appears in the schema) or say what to do when no strategy is chosen.

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

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

The annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description does not need to restate them. It adds the useful explicit-request policy, but it says nothing about preconditions (what happens if the memory was never deleted), what is actually restored (versions, links, metadata), or the consequences of the non-idempotent flag.

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, zero filler, and the core action is front-loaded before the usage restriction. Nothing could be removed without losing meaning.

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?

An output schema and annotations are present, so return values and safety are covered elsewhere, and all three parameters are documented in the schema. The remaining gap is failure behavior and precondition detail for a non-idempotent restore, which is a moderate rather than critical omission.

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 memory_id, reason, and metadata_json. The description adds no further parameter semantics; at best it hints that a previously deleted memory_id is expected. Baseline 3 applies when the schema carries the load.

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 gives a specific verb and resource: 'Restore a previously deleted memory.' This implicitly distinguishes it from the inverse operation (forget/remove), but it never names that sibling, so the differentiation is inferred rather than stated.

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?

'Intended only for when the user explicitly asks to restore or undo a deletion' is an explicit gate: it states the exact condition that should select this tool and implicitly excludes speculative or proactive use. That is stronger guidance than most siblings offer.

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 declare destructiveHint=true and idempotentHint=false, meaning this operation overwrites current state; the description never mentions that restoring will replace existing working state, nor is it reversible, nor what happens to a session that already has state. With annotations carrying the safety flag, the bar is lower, but a destructive state-overwriting tool deserves at least a warning about what gets replaced.

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, front-loaded with the action and followed by the trigger context; no filler. It is arguably too terse for a nine-parameter destructive tool, but nothing is wasted.

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

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

An output schema exists and the input schema is fully described, but the description is silent on core behavior: which snapshot is picked when snapshot_id and source_session_id are both empty, what the restore_state/record_restore_event flags actually do in combination, and the destructive consequence of the restore. For a destructive tool with nine optional parameters, this leaves the agent under-informed.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters, including snapshot_id, restore_state, record_restore_event, and the source/target session IDs. The description adds no parameter meaning at all, which is acceptable at baseline 3 but a missed opportunity to explain precedence (e.g. snapshot_id vs source_session_id).

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?

Clear verb+resource: it resumes prior work by restoring a saved restart snapshot. It does not differentiate itself from close siblings like restore_memory or create_restart_snapshot, so the agent still has to infer which one to use.

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 trigger condition ('when the user asks to resume/restart or after context loss'), which is more than most tools offer. But it never says when NOT to use it, nor names restore_memory or create_restart_snapshot as alternatives, so routing between the closely-named siblings is left 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, openWorldHint=false, idempotentHint=false, destructiveHint=false, so the write/no-side-effect-on-third-parties profile is covered elsewhere. The description adds that skills persist in XMemo and are recallable across connected agents, which is useful visibility context. However, it is silent on the notable behaviors an agent would want to know: publish defaults to true (what does publishing do?), and whether re-saving the same slug/name overwrites an existing skill.

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?

Front-loaded statement of purpose followed by a compact two-item mode list — no padding. The 'API Evolution Note: additive parameter' framing is slightly awkward phrasing for a definition but carries real information about backward compatibility.

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?

An output schema exists, so return values need not be described, and the two creation modes are covered. Still, for a 7-parameter, non-idempotent write tool with all parameters optional and none required, the definition omits what happens with the publish flag, slug collisions/overwrite behavior, and the components_json structure — meaningful gaps 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 nominally 100%, but most schema descriptions are placeholders ('Input value for the Save Cloud Skill tool.'), so the description's detail on url (ClawHub slug/URL, GitHub repo/tree/raw, or direct HTTPS zip/markdown) genuinely compensates. Against that, slug, publish, description, and components_json get no semantic explanation anywhere, so the tool is only half-explained. Baseline 3 fits.

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?

Specific verb+resource: 'Save a reusable procedure, rule, or SOP as a Cloud Skill in XMemo', plus the persistence scope ('future recall across connected AI agents'). It is clear what the tool does, but it never names the obvious sibling counterpart recall_cloud_skill or contrasts against remember/propose_write, so sibling differentiation is left to inference.

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 enumerates two usage modes with the parameter conditions that select each ('Direct creation: Provide non-empty name and instructions'; 'Remote import: Provide url'), which is real routing guidance. It does not state when *not* to use this tool or when a sibling (e.g. remember) is the better choice.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it operates 'over published current revisions,' supports 'bounded pagination,' and requires the 'knowledge:read' permission. This addresses auth needs and scope, which annotations do not 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 a single, dense sentence that front-loads the primary purpose ('Search authorized personal Knowledge Base content') and then covers the secondary addressed-read mode and the auth requirement. Every phrase earns its place, with no filler or repetition of schema content.

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

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

The tool is complex with 9 parameters and two distinct modes, and an output schema is present. The description gives a reasonable overview but does not explicitly connect query to search mode or knowledge_item_id/knowledge_revision_id to addressed read mode. It is adequate for orientation but leaves the agent to infer mode-parameter relationships from the schema, so there is a clear 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 description coverage is 100%, so the baseline is 3. The description mentions 'bounded pagination' and 'exact item/revision,' which loosely maps to offset, limit_chars, knowledge_item_id, and knowledge_revision_id, but it does not add syntax or decision details beyond what the schema already provides. No parameter is left undocumented, but the description also does not enhance parameter understanding.

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 and resource: 'Search authorized personal Knowledge Base content' and 'read one exact item/revision.' It clearly identifies the tool as a Knowledge Base search/read operation, which distinguishes it from memory-focused siblings like recall and read_memory. However, it does not explicitly name or contrast sibling tools, so it stops just short of full differentiation.

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

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

The description implies usage by describing two modes: searching published current revisions and performing an addressed read with bounded pagination. This gives an agent a sense of when to call the tool, but it provides no explicit alternatives, exclusions, or guidance on choosing between search and addressed read modes. Sibling tools exist for related memory operations, but no comparison is made.

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 destructiveHint=true and readOnlyHint=false, so the agent knows this is a write/update operation. The description adds valuable behavioral context by specifying that updates can affect 'content, location, or type' and that an 'exact reference' (memory_id) is required to identify the record. This goes beyond raw annotations without contradicting 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?

The description is two sentences, front-loads the core action, and every phrase earns its place. It avoids fluff, restating the title, or repeating schema details. The structure is efficient and immediately informative.

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

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

For a mutation tool with a rich schema and output schema, the description is sufficiently complete to guide usage. It conveys the essential context (when to use, what it updates) and the need for an exact reference. It does not describe return values, but the presence of an output schema makes that unnecessary. A minor omission is explicit mention of potential side effects like conflict detection or supersession, but these are evident from the parameter names.

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

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

The input schema provides 100% coverage with descriptions for all 18 parameters. The description does not add parameter-specific details beyond what the schema already offers, but it does map 'content', 'location', and 'type' to likely parameters (content, path, memory_type). Since the schema is thorough, a baseline of 3 is appropriate; the description's mention adds only marginal value.

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 ('updates') and the target resource ('a specific saved memory'), and distinguishes this tool from siblings like 'remember' (create), 'forget' (delete), and 'read_memory' by specifying it handles corrections, revisions, moves, or reclassifications. This unambiguously identifies the tool's unique 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?

Explicitly states when to use the tool: 'when the user asks to correct, revise, move, or reclassify it.' This provides clear contextual triggers. However, it does not explicitly mention when not to use it or name alternatives (e.g., use 'remember' for entirely new memories), so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so safety profile is covered. The description adds the optimistic-concurrency behavior (a stale version conflicts), which is genuine extra context, but it does not say what the edit affects, whether it is reversible, or what a successful result looks like.

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

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

A single sentence with no filler, front-loading the action and appending the concurrency constraint. Every clause 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 non-idempotent mutation tool with no output schema, the description covers the concurrency contract but leaves gaps: the relationship between memory_id and relationship_id is unstated, valid edge_kind values are undocumented (no enums, and the schema text for edge_kind is a placeholder), and success behavior is not 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 description coverage is 100%, so the baseline is 3; expected_version is already fully documented in the schema as an optimistic-concurrency value with VERSION_CONFLICT. The description's 'link kind' and 'last read version' merely restate the schema and add no format or validity detail (e.g. allowed edge_kind 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?

States a specific verb (Edit) and a resource (an explicit personal link kind), which maps to the relationship/edge_kind model. It does not distinguish itself from siblings such as link_memories, remove_memory_relationship, or memory_relationships, and 'link kind' is looser phrasing than the tool's actual relationship concept.

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 clause 'using the last read version; stale edits conflict' implies the required pre-read workflow and the failure mode, which is useful usage context. However, no alternative tool is named and there is no explicit when-not guidance (e.g. use link_memories to create, remove_memory_relationship to delete).

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 the write/safety profile (readOnly=false, destructive=false, idempotent=false), so the description's added value is the state-machine disclosure: this tool transitions among three named states with different per-action requirements. It stops short of describing the side effects of supersede/reopen beyond the required inputs.

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, zero waste, front-loaded with the core verb and immediately followed by the valid action set. Every sentence carries information the agent needs.

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?

An output schema exists, so return values need no explanation, and annotations cover safety. The description completes the picture for the resolve/supersede paths, but leaves the reopen path's required inputs unstated relative to an 8-parameter tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value by mapping conditional dependencies (resolution -> resolve; new_context plus optional options_json/impact_level/resolution_note -> supersede) that the flat schema does not express. It does not clarify what action='reopen' consumes.

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

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

States a specific verb (transition) plus resource (project decision) and enumerates the exact actions: resolve, supersede, reopen. This is far more than a restatement of the title, though it never explicitly positions itself against siblings like update_project_todo or the proposal 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?

Provides genuine conditional guidance -- resolution is required for action='resolve' and new_context for action='supersede' -- which tells the agent how to invoke each mode. However it gives no when-to-use-this-vs-alternatives guidance and never mentions what 'reopen' requires or when each transition is appropriate.

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 the write/mutation profile (readOnlyHint=false, non-idempotent, non-destructive). The description usefully adds the closed action set and the conditional parameter requirements per action, but says nothing about irreversibility, permission requirements, or what happens to dependent state on cancel/block.

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

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

Two dense sentences, front-loaded with the core purpose followed by the action contract. No filler, though the per-action conditionals are packed into a single run-on sentence that could be enumerated more readably.

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 an output schema present, return values need not be described, and the action/parameter contract is fully specified. Gaps remain around state-transition legality (which actions are valid from which current status) and side effects on the project, but the definition is sufficient 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 several schema descriptions are misleading copy-paste artifacts (reason described as 'for the deletion', action described generically as a filter). The description corrects this by specifying which parameters are required for which action values, adding genuine semantics 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?

States a specific verb (Transition) and resource (project TODO's status), which distinguishes it from read-oriented siblings like list_memory_todos or get_project_context. It does not explicitly name which sibling to prefer (e.g. complete_memory_todo or propose_todo_mutation), so it stops short of full sibling differentiation.

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

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

The description enumerates the valid action values and the per-action prerequisites, which implies when each mode applies. However, it never states when to use this tool versus complete_memory_todo, propose_todo_mutation, or create_memory_todo, so the routing decision is left to 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 adds context beyond the annotations by noting the memory:write permission requirement, that it versions the state slot, refreshes expiry, and does not delete other memories. This complements the destructiveHint: true and readOnlyHint: false annotations without contradicting 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?

The description is four sentences long, each serving a distinct purpose: purpose, behavior, alternatives, and parameter guidance. It is front-loaded and contains no filler.

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

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

The description covers the tool's purpose, usage guidance, side effects, and permission requirements. It does not mention return values, but the presence of an output schema mitigates the need. It is sufficiently complete for a mutation tool with rich schema annotations.

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

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

With 100% schema description coverage, the schema already explains all parameters. The description adds minimal extra meaning by advising to 'Provide content or a structured state field,' which groups the parameters conceptually but does not go beyond the schema's detail.

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

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

The description explicitly states 'Create or replace one scoped working-state record' and gives the intended use (resuming a task, next action, blocker). It also names alternatives, clearly distinguishing it from sibling tools like remember and record_event.

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 when-to-use guidance: 'Use remember for durable facts or record_event for history.' This tells the agent exactly when to prefer this tool over its alternatives.

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