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 indicate readOnlyHint=false and destructiveHint=false, so no contradiction. The description adds that it saves specific categories of data, but doesn't disclose side effects like overwriting existing snapshots or persistence behavior beyond what schema parameters imply.

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 deliver the core purpose and usage timing without any filler. The structure is front-loaded with the action, then the when-to-use guidance.

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

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

The tool has 9 optional parameters, a full output schema, and schema descriptions cover all parameters. The description explains what the snapshot contains and when to invoke it, which is adequate. It could mention the restore counterpart, but that's not essential.

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?

All 9 parameters have comprehensive descriptions in the schema, covering scope, bucket, state_key, session_id, TTL, etc. The tool description adds no additional parameter semantics, so 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 clearly states 'Save active state, recent events, TODOs, and pending decisions for restart' with a specific verb and resource. It distinguishes itself from sibling tools like restore_restart_snapshot by focusing on the creation aspect.

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 'Call this before handoff or when context may be lost,' providing clear timing guidance. It doesn't mention exclusions or alternatives, but the context is sufficient for most use cases.

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?

The description adds significant behavioral context beyond the annotations: it explains that the default is a recoverable soft delete reversible by restore_memory, while mode='hard' is permanent and unrecoverable, requiring explicit user confirmation. This goes well beyond the destructiveHint annotation by detailing nuances and recovery options.

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

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

The description is concise and well-structured: it opens with the core action and resource, then details targeting and deletion modes, and closes with a cautionary instruction. Every sentence adds value, and it is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (7 parameters, an output schema, and supportive annotations), the description covers the essential aspects: what is deleted, how to target, the deletion modes, and the prerequisite to resolve ambiguity. It leverages the schema and annotations to avoid redundancy, leaving no major gaps for selection and invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description enriches the schema by clarifying that targets can be 'current/latest', an exact memory reference, a TODO ID from list_memory_todos, or a transaction ID from list_ledger_transactions, which is more specific than the schema's target description. However, it does not explain the vague query_hint parameter, leaving a minor gap.

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

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

The description clearly states the tool's action ('Delete one memory, TODO, or Ledger transaction') with specific targeting options, distinguishing it from sibling tools like restore_memory and list_memory_todos. It uses a specific verb with resource and scope, making the purpose immediately clear.

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

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

The description provides explicit guidance on when to use the tool (to delete a memory, TODO, or ledger transaction) and how to specify targets (exact memory reference, TODO ID from list_memory_todos, transaction ID from list_ledger_transactions). It also warns to resolve ambiguous targets and restricts hard delete to after explicit user confirmation, effectively saying when not to use it without confirmation.

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 provide readOnlyHint: true, idempotentHint: true, and destructiveHint: false, covering the safety profile. The description adds minimal behavioral context beyond 'conflicting/inconsistent', such as the default focus on unresolved conflicts. It does not contradict annotations, but adds limited additional transparency about response behavior or side effects.

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

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

The description is two sentences and front-loads the primary purpose. Every sentence earns its place: the first states what the tool does, and the second gives the usage trigger. No wasted words.

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

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

For a simple read-only list tool, the description is sufficiently complete. The output schema exists, annotations cover safety, and all parameters are documented in the schema. The description adds the necessary context for when to use the tool, making it fully functional for an agent to select and invoke it.

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

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

Schema description coverage is 100%, with each parameter (limit, output_json, unresolved_only) having clear descriptions. The description's phrase 'review unresolved conflicts' aligns with the unresolved_only parameter but does not add meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'List conflicting/inconsistent memories.' The verb 'List' and the specific resource 'conflicting/inconsistent memories' make the purpose unambiguous, and it distinguishes itself from sibling tools like 'resolve_memory_conflict' which handles resolution rather than listing.

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

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

The description gives explicit guidance: 'Call this when the user/admin asks to review unresolved conflicts.' This clearly indicates when to use the tool, though it does not explicitly name alternative tools or exclusions. It offers strong contextual direction for a common use case.

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 and destructiveHint=false. The description adds the specific action 'Show version history,' which is consistent and provides behavioral context beyond annotations.

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

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

Single sentence with no extraneous words. Front-loaded with purpose and usage, making it efficient for an AI agent to parse.

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

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

Given the simple tool with two parameters and an output schema, the description covers the essential purpose and usage. It lacks a mention of the output format, but the output schema handles that.

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

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

Schema description coverage is 100% with clear descriptions for both parameters. The description does not add any additional meaning beyond what the schema already provides, meeting the baseline.

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

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

Description clearly states 'Show version history for a memory' with a specific verb and resource. It distinguishes from sibling tools by focusing on historical versions rather than current content.

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

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

Explicitly says when to call: 'when the user asks for previous content or changes over time.' Does not mention when not to use or provide alternatives, but the usage context is 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by clarifying that this is an aggregate/view operation over all saved memories, and it names the aggregation dimensions plus optional time-range filtering. It does not mention the heuristic fallback when since is omitted, but that nuance is captured in the parameter descriptions.

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 that front-loads the primary outcome ('Shows aggregate statistics') and then packs the trigger condition and key dimensions into a compact subordinate clause. There is no filler, repetition of the schema, or unnecessary detail.

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

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

For a read-only statistics tool with 8 optional parameters, complete schema descriptions, a rich output schema, and safety annotations, the description covers the selection-level context and usage trigger. The remaining operational details are supplied by the schema, so nothing an agent needs to choose or invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, and the since/until parameters include exceptionally detailed trigger and model-responsibility guidance. The tool description itself only restates high-level grouping dimensions (type, source, location, time range) without adding parameter-level semantics, which matches the baseline score 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 opens with a specific verb and resource: 'Shows aggregate statistics for all saved XMemo memories,' and lists concrete aggregation dimensions (type, source, location, time range). This makes it clearly distinguishable from sibling memory retrieval tools like recall_context or read_memory, which return actual memories rather than counts or breakdowns.

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 the tool fits: 'when the user asks for counts, breakdowns, or distributions.' It does not name sibling alternatives or provide a when-not-to-use rule, so it stops short of fully explicit exclusion guidance, but the trigger condition is 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 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: source-specific capabilities, permission scoping ('admin' for consolidation), and the fact that this is a merged replacement for two legacy tools.

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

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

Two dense sentences with no filler. The key disambiguation between source modes is front-loaded, and the legacy-tool consolidation note is valuable context rather than 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?

The tool is complex with 9 optional parameters, two distinct modes, and an output schema, and the description does a good job of explaining the two source modes and their intended users. The since/until semantics fall to the schema, which is rich enough, so nothing critical is missing. Slightly more detail on what the returned audit records contain could push this to 5, but the output schema likely covers that.

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 meaning to the 'source' parameter that the schema alone does not provide ('Optional source filter for system statistics' is vague by comparison). The description clarifies what values events and consolidation actually represent, which materially helps parameter selection.

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 ('query') and resource ('audit'), then precisely breaks out the two source modes ('source='events'' and 'source='consolidation''). It also names the legacy tools it consolidates, so an agent can distinguish this from other memory/query tools 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?

Usage guidance is explicit: normal users should prefer memory_activity for event queries, while consolidation audit records are flagged as admin-scoped. The description also clarifies scope by naming the legacy query_audit_events/query_consolidation_audit tools it replaces, giving clear routing context.

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

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

Annotations already signal readOnly/idempotent/non-destructive behavior, so the description adds strong extra value: snapshot pinning, torn-read prevention, bare ID resolving to head, has_more pagination behavior, and the fact that embeddings are never returned. This goes well beyond annotation-derived knowledge.

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?

Purpose is front-loaded and the technical paragraphs are largely necessary for correct pagination. It is dense but not bloated; the snapshot/tearing explanation could be slightly more compact without losing essential 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?

Given the output schema exists, the description covers all behavior an agent needs: exact-ID reads, authorized access, pagination state, snapshot semantics, head behavior, and embedding exclusion. Nothing critical is missing 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 covers all parameters, but the description adds meaning: memory_id can be a bare ID or revision, offset/limit are character-based paging controls, and continuation relies on returned revision/next_offset. Minor flaw: next_offset is not an actual input-schema property, so the agent must infer it should be passed as offset.

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 'Read one exact authorized XMemo memory in character windows' — a specific verb, resource, and mode. It clearly differentiates from siblings like recall/search by requiring an exact memory ID rather than performing search or fuzzy retrieval.

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

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

Provides explicit guidance for the initial read (bare memory ID, offset 0) and continuation reads (revision as memory_id, has_more/next_offset), including why revision must be used. It does not explicitly name excluded sibling tools, but the context strongly implies this is for exact-ID reads after recall/search.

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 tool read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: results are relevance-ranked and the lookup is best-effort, implying the result set may not be exhaustive. This is meaningful without contradicting 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 compact sentences with no filler. The core behavior and scope are front-loaded, and the alternative-tool guidance is included efficiently. Every sentence earns its place.

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

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

Given the tool's high parameter count, the description is brief but sufficient because the schema is fully documented and an output schema exists. It orients the agent to the tool's role and distinguishes it from the closest sibling, while the schema carries the detailed parameter semantics. A little more context about return-value shape or time-based behavior would be nice but is not 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?

Schema description coverage is 100%, and the schema already provides rich per-parameter semantics including triggers and consequences. The description mentions path/type controls and working-memory preference, which aligns with parameters, but it does not add meaning beyond what the schema already documents. 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 clearly identifies the action (recall a few relevance-ranked memories), the resource (XMemo memory), and the intended context (before answering). It also distinguishes itself from the sibling recall_context by naming it explicitly, so an agent can tell them apart.

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 usage guidance: use recall for a quick best-effort lookup, and use recall_context when a bounded multi-memory context pack is needed. This is a clear when-to-use / when-not-to-use distinction with a named alternative.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds genuinely non-obvious behavior on top: 'memories that do not fit are omitted and reported, so raise max_tokens or use recall when you need the records themselves.' This discloses a truncation-with-reporting trait that annotations cannot express.

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 zero waste: purpose first, usage routing second, behavioral caveat third. Every sentence earns its place and the most decision-relevant information (what it does, when to pick it) 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 21-parameter tool, the definition is complete for selection and invocation: output schema exists, so return values need no explanation, and the schema covers all parameter semantics at 100%. A small gap is that the description never mentions the structured-vs-rendered output option (output_json) or time-window capabilities, though these are well covered in the schema itself.

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 of 3 applies; the schema's parameter descriptions are unusually rich, with trigger conditions and model responsibilities for each field. The main description adds only marginal parameter context by tying max_items/max_tokens to the omission-and-report behavior. It correctly does not duplicate the schema's work.

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+resource pair ('Build a read-only, bounded context pack from multiple relevant memories') and immediately distinguishes itself from siblings: 'use recall for a quick best-effort lookup or get_project_context for a whole-project snapshot.' An agent can tell this tool apart from its nearest alternatives 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?

Explicit when-to-use criteria are given ('when an answer needs several memory items or scoped/path-filtered context') along with named alternatives and the conditions that route to them ('use recall for a quick best-effort lookup'). The guidance is actionable and leaves 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 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 already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive write operation. The description adds the 'only when user/admin explicitly chooses' constraint, which is useful behavioral context, but it doesn't detail what 'resolve' means in terms of memory data changes or that it may overwrite/merge memory entries beyond what the schema hints at.

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; the first states the purpose, the second adds a critical usage condition. No redundant or extraneous content, and the key information is front-loaded.

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

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

Given the extensive schema (100% parameter coverage) and annotations (destructiveHint=true), the description is sufficient for invocation. It could benefit from noting the destructive impact on memory, but the annotations already cover that, and the output schema likely explains return values, so the description itself is adequately complete.

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

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

Schema coverage is 100% with descriptions for all five parameters, including the meaning of resolution_strategy, winning_memory_id, and merge_content. The description adds no parameter-specific detail beyond the schema, so a 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 uses the specific verb 'resolve' with the resource 'memory conflict', clearly distinguishing it from sibling tools like list_memory_conflicts. It also qualifies that the conflict must be 'listed', indicating a prerequisite derived from the listing tool.

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 'Call this only when the user/admin explicitly chooses a resolution strategy', providing a clear condition for invocation and excluding automatic use. It doesn't name alternatives, but the condition itself guides selection and implies the agent should wait for explicit user/admin direction.

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 indicates the tool restores a previously deleted memory, which is a behavioral trait. Annotations already declare destructiveHint=false, and the description adds context about user intent. However, it does not detail what happens to the restored memory (e.g., ID reuse, content restoration) or any permissions needed.

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

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

The description is extremely concise: two sentences with no unnecessary words. It front-loads the purpose and usage condition.

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

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

Given the tool's complexity (3 parameters, annotations present, output schema exists), the description adequately covers the core purpose and usage context. The output schema handles return value details, so no further elaboration is needed.

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

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

All parameters have descriptions in the schema (100% coverage). The description adds the phrase 'shown by search or recall' for memory_id, which is helpful. For 'reason' and 'metadata_json', descriptions are generic, so the added value is marginal.

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 ('Restore') and the resource ('a previously deleted memory'). It distinguishes from sibling tools like 'forget' and 'remember' by specifying the restore operation.

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

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

The description provides explicit guidance: 'Call this only when the user explicitly asks to restore or undo a deletion.' This clearly indicates when to use the tool, though it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the context of resuming after interruption but does not detail side effects like recorded restore events or state overwriting. It does not contradict the annotations, and with annotations present, the minimal behavioral disclosure is acceptable.

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-loaded with the core purpose, and contains no filler. Every word adds value: it states what the tool does and when to invoke 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?

Given the tool's complexity (9 parameters, output schema, destructive annotation), the description provides the essential purpose and usage trigger. The schema and output schema fill in the technical details, so the description is sufficient for an agent to decide when to call it, though it could have briefly mentioned the need for a snapshot ID or the related create_restart_snapshot 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%, so the input schema already fully documents all 9 parameters. The description adds no parameter-level semantics beyond the schema, which is acceptable because the schema is self-sufficient.

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 resumes previous work from a saved snapshot, with the verb 'Resume' and resource 'saved snapshot'. This distinguishes it from sibling tools like create_restart_snapshot, which creates snapshots, and restore_memory, which handles general memory restoration.

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

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

The description gives explicit guidance: 'Call this when the user asks to resume/restart or after context loss.' This is a clear trigger condition, though it does not mention when not to use it or name alternatives explicitly beyond the implied context.

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

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

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 are all false, providing no positive safety context, and the description does not disclose side effects, reversibility, permissions, or what actually happens to the decision on each transition. It describes the required actions and conditional fields but not the behavioral consequences of performing the transition. There is no contradiction with the annotations.

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

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

Three short sentences with no filler. The core verb and resource come first, followed by the necessary conditional logic and a useful legacy-tool consolidation note. Every sentence earns its place.

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

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

For an 8-parameter tool with conditional branching, the description covers the main resolve/supersede branches but omits what 'reopen' entails, why project_id is required, and any side effects or failure modes. The presence of an output schema reduces the need to document return values, but the misleading schema descriptions are not fully compensated.

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

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

The schema descriptions are often generic or misleading: action is described as a 'Usage action or audit-event action filter' and project_id as 'Optional' despite being required. The tool description compensates for the most important parameter by specifying the allowed action values and the conditional requirements for resolution and new_context, plus the optional fields for supersede. However, it still leaves project_id, impact_level, and resolution_note semantically underspecified.

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

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

The description opens with a specific verb and resource, 'Transition a project decision', and enumerates the three allowed actions (resolve, supersede, reopen), making the tool's function clear. It also mentions consolidating the legacy resolve/supersede/reopen_project_decision tools, which clarifies its role as the successor to those. It doesn't explicitly differentiate from current siblings like update_project_todo, but the resource is distinct enough.

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 that the tool consolidates the legacy resolve/supersede/reopen_project_decision tools, signaling when to use it instead of those older tools. It also explains action-specific requirements (resolution required for resolve, new_context required for supersede), helping the agent decide which parameters to supply. However, it doesn't contrast with current siblings or state when not to use the tool.

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

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

Annotations already indicate non-read-only, non-idempotent, non-destructive. The description adds action-specific constraints and explicitly says it is a consolidation of legacy tools, which clarifies its behavioral scope. It does not detail failure modes or side effects, but the status transition semantics are sufficiently clear.

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 cover the purpose, action list, per-action requirements, and legacy replacement. Every sentence is information-dense with no filler or redundancy.

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

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

Given the tool's complexity (multiple conditional actions), the description is thorough. An output schema exists, so return values need no explanation. It lacks explicit mention of error cases or idempotency, but annotations and the action rules provide a complete picture for an AI agent to invoke it correctly.

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

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

The description adds significant meaning beyond the schema. It defines the allowed action values (absent from schema enums), specifies conditional required parameters (assignee_agent_id for assign, reason for block), and clarifies the optional note for complete. The schema descriptions are generic or even misleading (reason mentions 'deletion'), so the description compensates fully.

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 'Transition a project TODO's status', using a specific verb and resource. It enumerates the exact action values (accept, assign, block, unblock, complete, cancel) and differentiates from the legacy tools it consolidates.

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 names the legacy tools it replaces ('Consolidates the legacy accept/assign/block/unblock/complete/cancel_project_todo tools'), telling the agent to use this tool instead. It also provides per-action requirements (e.g., assignee_agent_id for assign, reason for block, note for complete), defining when to use each action.

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.