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 safety is covered. The description adds behavioral context by clarifying that it returns aggregate counts, not raw memories, and supports time-range filtering. This aligns with annotations and adds value beyond the structured fields.

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 primary action and resource. It wastes no words and includes the key trigger condition. This is exemplary conciseness.

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

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

Given the tool's moderate complexity, 8 optional parameters, full schema coverage, output schema presence, and comprehensive annotations, the description is complete. It conveys the purpose, the kind of output (aggregate stats), and the invocation context. No critical information is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds high-level meaning by mentioning groupings (type, source, location) and optional time range, which reinforces the semantics of the group_by and since/until parameters. It does not introduce new details but synthesizes the parameter intent.

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: 'Shows aggregate statistics for all saved XMemo memories — counts by type, source, location'. It specifies the resource (XMemo memories) and the action (show aggregate statistics), and the mention of optional time ranges and groupings distinguishes it from sibling tools like recall_context or get_timeline.

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

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

The description provides a clear use case: 'when the user asks for counts, breakdowns, or distributions'. This tells the agent when to invoke the tool. It does not explicitly name alternative tools for different scenarios, but the context is sufficient for selection among siblings.

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

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

Annotations 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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds valuable context beyond annotations by explaining the meaning of the two source modes and that consolidation source is admin-only. It also mentions the consolidation of legacy tools, which implies a broader behavior scope. This is meaningful additional context that helps the agent understand the tool's behavior.

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

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

The description is two sentences, front-loaded with 'Advanced audit query', and every clause earns its place. The first sentence packs the core purpose and both modes, while the second sentence notes the consolidation of legacy tools. There is zero 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?

The tool has 9 parameters but all are fully described in the schema, and an output schema exists, so return value details are not needed. The description covers the two usage modes, the admin requirement for consolidation, and the preferred alternative for normal users. This is complete for a complex query tool with rich structured metadata.

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

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

The input schema has 100% parameter description coverage, so the baseline is 3. The description adds semantic value by explicitly explaining the 'source' parameter's allowed values ('events' and 'consolidation') and their meanings, which the schema does not (schema merely says 'Optional source filter for system statistics'). This goes beyond what the schema provides, making the description more helpful for correctly selecting source.

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 is an advanced audit query with two distinct source modes: 'events' for action/time/target audit events and 'consolidation' for lifecycle/reflection records. It differentiates itself from the sibling memory tools and even references a preferred alternative (memory_activity). The verb is precise ('queries', 'inspects') and the resource scope is explicit.

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 tells users when to use this tool: for audit events when source='events' and for consolidation/lifecycle audit records (admin-only). It also provides a clear exclusion: 'for normal users prefer memory_activity'. Additionally, it notes that this tool consolidates legacy query_audit_events/query_consolidation_audit tools, informing users migrating from those. This is explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context by explaining pagination with next_offset, the fact that it reads exactly one memory, and that embeddings are never returned. This enriches the agent's understanding of what to expect and what not to request.

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: the first states the core purpose and scope, the second provides usage guidance and a behavioral limitation. There is zero filler.

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

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

With output schema present and all parameters well-documented, the description covers the essential aspects: what the tool does, when to use it, how pagination works, and a key limitation. Sibling tools like recall are implicitly differentiated by the explicit prerequisite of an ID from recall or search.

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

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

The schema already documents all three parameters with descriptions (100% coverage). The description adds workflow context: memory_id must come from recall or search, offset is used to continue pagination via next_offset, and limit controls page size. This clarifies the relationship between 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 ('read') and identifies the resource ('XMemo memory'), specifies the scope ('exact authorized'), and describes the pagination approach ('character windows'). It clearly distinguishes from sibling tools like recall (which searches) by requiring a memory ID from recall or search.

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 prerequisite guidance: use a memory ID returned by recall or search. It also explains how to handle long content via next_offset. While it doesn't explicitly name alternative tools for exclusion, the workflow is clear and actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond these annotations: results are 'relevance-ranked,' and the tool supports 'path/type controls and optional working-memory preference.' It also implies a best-effort retrieval strategy. This is meaningful, though it doesn't detail output structure or edge cases.

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

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

The description is exactly two sentences and is highly efficient. The first sentence conveys the core action and key features; the second provides usage differentiation. No filler or redundancy, and the most important information is front-loaded.

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

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

For a read-only retrieval tool with a well-covered schema and declared output schema, the description is sufficient. It explains what the tool does, when to use it, and how it differs from the closest sibling. The presence of an output schema means return values need not be described. Minor gaps such as not explaining the 'explain' parameter are covered by the schema.

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

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

The input schema provides descriptions for all 8 parameters (100% coverage), so the baseline is 3. The description's mention of 'path/type controls' and 'working-memory preference' maps to path_filter, memory_type, and prefer_working, but adds no new semantic detail beyond the schema. Each parameter already has a clear description, so the description adds no extra value here.

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: 'Recall a few relevance-ranked memories before answering,' specifying the resource (memories) and the action (recall). It also distinguishes itself from the sibling tool recall_context by contrasting quick best-effort lookup with a bounded multi-memory context pack. This goes beyond a simple restatement of the title.

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 usage guidance is provided: 'Use it for a quick best-effort lookup; use recall_context when the answer needs a bounded multi-memory context pack.' This directly tells the agent when to prefer this tool over the most relevant alternative, satisfying the dimension fully.

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=true, idempotentHint=true, destructiveHint=false), the description discloses that memory items that do not fit the bounds are omitted and reported, and advises raising max_tokens or using recall if the records themselves are needed. This adds real behavioral context not present in the structured 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 two sentences, front-loads the core purpose, then weaves in usage guidance and a behavioral caveat. Every clause earns its place; 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 has 13 parameters and an output schema, the description covers the essential context: what the tool does, when to use it, how bounds behave, and how it differs from siblings. The output schema handles return format details, so the description doesn't need to describe them. It's complete for this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by explaining that max_items/max_tokens bound the output and that omitted items are reported, which ties these parameters to observable behavior. This goes slightly beyond the schema's field-level 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 uses a specific verb+resource: 'Build a read-only, bounded context pack from multiple relevant memories.' It clearly distinguishes from siblings by explicitly naming recall and get_project_context as alternatives with different purposes. This makes the tool's unique role immediately obvious.

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 states exactly when to use this tool: 'when an answer needs several memory items or scoped/path-filtered context.' It also provides exclusions and alternatives: 'use recall for a quick best-effort lookup or get_project_context for a whole-project snapshot.' This is explicit, actionable guidance.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description clearly states a specific verb ('updates') and the target resource ('a specific saved memory'), and distinguishes this tool from siblings like 'remember' (create), 'forget' (delete), and 'read_memory' by specifying it handles corrections, revisions, moves, or reclassifications. This unambiguously identifies the tool's unique role.

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

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

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

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

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

Annotations already communicate readOnlyHint=false, destructiveHint=false, and idempotentHit=false. The description adds meaningful behavioral context by detailing transition semantics and required parameters for each action. It does not disclose potential side effects or authorization requirements, but it does not contradict 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 three sentences, front-loaded with the core verb and resource, and each sentence adds essential information: purpose, action variations, required parameters, and consolidation note. There is 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?

The description covers the action-specific requirements well, and an output schema exists so return values need not be explained. However, it does not clarify the roles of the required decision_id and project_id, and it leaves unresolved the schema's misleading project_id description (marked optional but required). For a complex 8-parameter tool, this is a minor but notable 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?

The tool description provides critical conditional parameter semantics that are not present in the schema: it enumerates allowed action values and specifies which parameters are required for each action. This goes well beyond the generic schema descriptions (e.g., action is described as 'Usage action or audit-event action filter'), making the actual invocation logic clear.

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 'Transition a project decision' and immediately specifies the three allowed actions (resolve, supersede, reopen), clearly defining the tool's scope. The closing note about consolidating legacy tools distinguishes it from previous separate tools, so purpose is unambiguous.

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

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

The description explains when each action is appropriate via action-specific requirement notes ('resolution is required for action=resolve', 'new_context ... required for action=supersede'), and the consolidation note explicitly tells the agent this tool replaces the legacy resolve/supersede/reopen_project_decision tools. It does not compare with unrelated sibling tools, but the guidance 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 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.