XMemo

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

Annotations already cover readOnly, idempotent, and non-destructive behavior, so the description is not required to repeat safety information. It adds the count-and-group semantics but does ot disclose any further behavioral nuances such as timezone fallback, visibility limits, or example-snippet behavior; those live in the schema instead.

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 states the action, scope, optional grouping, and the user trigger without waste. Every clause contributes either to selection or invocation.

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 counting/analytic tool, the description provides the essential selection and invocation context. The rich input schema, output schema, and annotations carry the remaining details, so nothing critical is missing at the decision level.

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

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

Schema description coverage is 100% and each parameter already has detailed definitions and triggers, so the description does not need to compensate. It adds a small amount by refreshing the grouping concepts (day, month, agent, location, type), but that is largely redundant with 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 clearly states the verb ('Counts') and resource ('XMemo memories'), so the core purpose is unmistakable. It also includes the user-intent trigger ('when the user asks how often...'), which helps separate it from nearby tools like search_memory or recoll, though it does not explicitly name or contrast sibling tools.

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

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

It starts a clear when-to-use condition: user asks how often a word or topic appears. This gives a solid usage signal and discourages using it for pure retrieval or listing. It does not explicitly mention when not to use it or name alternatives, so it stopes short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side effects. The description adds the behavioral context of explaining memory rationale, but does not disclose additional traits such as output format or limitations; the output schema covers return structure. This is adequate given the strong annotation coverage.

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

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

The description is a single, front-loaded sentence that clearly states the action and condition. There is no redundancy or filler, making it highly 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?

The tool is simple with robust annotations and an output schema. The description covers purpose and usage, the schema covers parameters, and the annotations cover safety. A minor gap is the lack of an explicit prerequisite that memory_id must come from a prior search/recall, but the schema property description already states that, so the overall context is complete.

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

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

Both parameters (memory_id and query) have descriptive schema entries providing full coverage at 100%. The tool description does not add extra parameter-level detail, 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's function with a specific verb ('Explains') and resource ('why a memory exists or matched a query'). It distinguishes itself from sibling search/recall tools by focusing on the reasoning behind memory behavior rather than listing or retrieving memories.

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

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

The description gives an explicit usage condition: 'whenever the user asks why something was saved there or why it was retrieved.' This clearly signals when to invoke, though it does not explicitly name alternative tools or exclusions, which would have made it 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses important behavioral details: it defaults to a recoverable soft delete, mentions restore_memory as a recovery path, and warns that hard delete is permanent and unrecoverable, requiring explicit user confirmation. This adds significant value and aligns with the destructiveHint.

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

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

The description is a single paragraph, dense but not bloated. Every sentence contributes value: the action, the target types, the default behavior, the hard-delete caution, and the usage rule. It could be slightly more scannable with a list, but it remains efficient for the complexity involved.

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 destructive nature and multiple targets/modes, the description covers all essential aspects: what it deletes, how targets are specified, the soft/hard mode distinction, recovery via restore_memory, and the prerequisite of explicit user confirmation for permanent deletion. Combined with the detailed schema and annotations, it is complete for an AI agent to select and invoke 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% description coverage for all 4 parameters. The description adds context by explaining valid target formats (exact memory ID, TODO ID from current listing, Ledger transaction ID) and clarifying the mode aliases (soft/soft_delete, hard/hard_delete). It enriches rather than merely repeats the schema, though the schema already does a good job.

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 purpose: 'Delete one memory, TODO, or Ledger transaction by natural target'. It specifies the verb (delete) and the resources (memory, TODO, Ledger transaction), and distinguishes itself from sibling tools like restore_memory and update_memory by focusing on deletion.

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

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

The description explicitly states when to use the tool: 'Call this only when the user explicitly asks to delete a specific memory, TODO, or expense/income record'. It also provides guidance for ambiguous targets ('list/search or check activity first') and warns against using hard delete without explicit confirmation. This is clear and 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the behavioral detail that the tool reports both connection status and the currently connected account/agent, which goes beyond the annotations and helps predict the tool's response. No contradictions exist.

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

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

The description is a single, well-structured sentence with no unnecessary words. It front-loads the core action ('Checks XMemo connection status') and then provides the usage trigger, making it easy to scan and understand.

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 (no parameters, output schema provided, annotations covering safety), the description adequately covers the purpose, trigger, and expected output. The output schema presumably details return values, so no further description is needed. The description is fully 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 tool has zero parameters, and schema description coverage is trivially 100%. Even without parameters to document, the description adds meaning by clarifying what the tool checks and what information it exposes, meeting the baseline for parameterless tools.

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 'Checks' to state the action on the XMemo connection, and clearly identifies the resource ('connection status') and the additional output ('currently connected account/agent'). This distinguishes it from all sibling tools, none of which handle connection checking, 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 usage context by stating 'when the user asks whether XMemo is connected.' This gives a clear trigger for invocation. It does not explicitly mention alternatives or when-not-to-use scenarios, but no sibling tool offers a similar connection check, so the absence of exclusions is acceptable.

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 behavior: it returns concise text, never a raw context pack or workspace resource, and when no exact project is established it says so and guides the user. This provides useful context 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?

Four sentences, each serving a distinct function: purpose, usage examples, exclusion/alternative, and fallback behavior. No redundancy, properly 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 summary tool with two optional parameters, the description covers purpose, usage, scope constraint, failure mode, and output type. Output schema and annotations handle the rest, making this 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 description coverage is 100%, with both parameters (focus and project_id) fully described. The description reinforces the single-project scope but adds no new parameter-level semantics, so the baseline 3 applies.

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

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

The description clearly states the tool's purpose: returning a bounded quick-answer summary for a single exact project as concise text. It distinguishes from siblings by explicitly naming the alternative for workspace management (open_project_workspace).

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 scenarios ('brief status, blockers, progress, or next-action questions') and explicitly says not to use it for opening/browsing/managing the workspace, naming the alternative. It also instructs how to handle ambiguous project references.

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

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

The annotations already carry destructiveHint true and readOnlyHint false, so the agent knows this can mutate data. The desciption adds action-specific context, but it does not disclose what destruction or mutation can look like, such as whether update_transaction overwrites records or whether expected_version is required. With annotations present, the bar is lower, but the description adds little behavioral depth beyond listing actions.

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 s- sentences, examples front-loaded, no wasted prose. The opening 'Manage Ledger transactions' and the closing action list overlap slightly, but the overall structure is tight and scannable for an agent.

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

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

With 33 parameters and 5 actions, the description is under-specified for some actions: list, overview, update_transaction are only named, not explained. An agent gets good guidance for add_expense and summary, but little orientation for choosing among list/summary/overview or for performing updates. The output schema and high param coverage soften the gap, but not enough for a tool this complex.

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 a 3. The description adds real parameter semantics by linking action='add_expense' to a natural-language utterance and by specifying months=1 plus the user's real owner_timezone for summary. This meaningfully helps an agent map intents to parameter values beyond what the schema states.

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

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

The description identifies the resource (Ledger transactions) and lists the five supported actions, plus two concrete usage examples. 'Manage' is broad, but the examples and action list make the tool's purpose clear. It does not explicitly contrast with siblings like open_ledger, but the action enum disambiguates it sufficiently.

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

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

It gives explicit when-to-use guidance: add_expense for natural-language expense statements and summary for this-month totals with months=1 and owner_timezone. This goes beyond the schema. It does not state when to avoid ledg er or prefer open_ledger, so it lacks full exclusion 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, and destructiveHint=false. The description goes beyond annotations by disclosing the one-view-per-request rule and the prohibition on combining sections, which is useful behavioral context not present in 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 concise sentences with no filler. The purpose is front-loaded, and each sentence adds a distinct piece of information about scope and section usage.

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 read-only tool with a full output schema and 100% schema coverage, the description adds the critical one-view rule and section-selection guidance. It is slightly incomplete in not addressing when to prefer this tool over sibling memory tools, but that is a secondary 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 each parameter is already documented. The description adds guidance on section selection but does not explain since/until or group_by, which the schema already handles. 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 opens with a clear verb-resource pair ('Show exactly one requested XMemo memory view') and identifies the three section modes. It does not explicitly name sibling tools, but the purpose is unambiguous and distinct enough from read_memory or search_memory.

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 rules: default overview for a broad workspace snapshot, stats only for explicit count/breakdown requests, activity only for explicit recent-change requests, and no section combination. However, it does not contrast this tool against sibling memory tools, leaving some selection inference to the agent.

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), the description adds valuable behavioral context: view=subscriptions is a compatibility value and does not imply an XMemo plan, owner_timezone must be the user's real IANA timezone and never guessed UTC, and existing transactions can be edited inside the widget while deletion stays in Chat requiring confirmation. These details clarify agent expectations without contradicting the annotations.

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

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

The description is compact yet information-dense, front-loading the primary purpose and then covering usage, disambiguation, and behavioral caveats. Every sentence serves a distinct disambiguation or instruction purpose, with no filler or repetition of schema fields beyond critical clarifications.

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 (10 parameters, many sibling tools, rich schema), the description is complete: it covers purpose, use cases, alternatives, special parameter semantics, timezone rules, and widget interaction behaviors. The output schema exists, so return value details are not needed. No significant 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 coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds extra semantic clarity for view (clarifying subscription compatibility and XMemo warning) and owner_timezone (reinforcing real IANA timezone), which pushes it above baseline. However, most parameter meanings are already well-documented in the schema.

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

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

The description clearly states the tool opens the interactive Ledger for Net flow or Renewal reminders, with a specific verb and resource. It proactively distinguishes itself from a non-existent open_subscriptions tool and differentiates from sibling ledger tools by clarifying it is the entry point for opening/browsing the Ledger.

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 this tool ('when the user asks to open, browse, explore, or work with Ledger') and names alternatives: ledger(action='summary') for quick totals, ledger(action='list') for transaction rows/search, and ledger(action='add_expense') for recording. Also warns against inventing a separate open_subscriptions tool, providing clear when-not-to-use guidance.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description reveals resolution rules: no reference always opens Home even with one accessible project, exact matches open the eight tabs, multiple/no matches return Home with candidates or no-match state, and legacy ledger values open Overview. This is valuable behavioral context not available in annotations.

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

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

The description is dense yet well-structured: it opens with the core action, then sequentially covers parameter resolution, tab enumeration, edge cases, and sibling differentiation. Every sentence contributes meaningful information, with no filler or redundancy.

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

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

Given the tool's complexity (4 parameters, 8 tabs, multiple edge cases), the description is fully complete: it covers no-reference behavior, match resolution outcomes, tab list, legacy handling, and alternative tools. The presence of an output schema reduces the need to describe return values, and annotations cover safety, so the description fills all remaining 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 coverage is 100%, so the baseline is 3, but the description adds important meaning: it explains project resolution logic (exact project_id vs. unique name/alias), outcome on multiple/no matches, and the initial_tab legacy behavior. This enriches the schema parameter descriptions with practical consequences.

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 'Open' with the resource 'Project Workspace' and lists the eight tabs, clearly distinguishing it from siblings like get_project_summary, open_todo_board, and open_ledger. It states exactly what the tool does: opens Home or a specific project's workspace.

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 guidance is given for when to use alternatives: 'For a quick text-only status, blockers, or next-actions answer use get_project_summary. Explicit standalone TODO or Ledger intent keeps using open_todo_board or open_ledger.' The description also clarifies behavior with no project reference, making the usage context unambiguous.

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, and the description adds the important behavioral constraint: 'The owner_timezone input must be the user's real IANA timezone; never guess UTC.' It also clarifies that mutations are handled elsewhere, avoiding the possibility of the 'manage tasks' phrase suggesting write actions. No contradiction with annotations.

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

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

The description is somewhat long but every sentence contributes: purpose, critical timezone note, use cases, and alternatives. It is front-loaded with the main purpose and structured clearly, though slightly wordy.

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 an output schema and thorough annotations, the description adequately covers when to use it, key behavioral constraints, and how it differs from siblings. It could mention pagination behavior but that is not necessary for a board-opening tool with output 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 each parameter is already documented. The description repeats the owner_timezone requirement but adds no new parameter semantics beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting.

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: 'Open the interactive TODO Board workspace to view, browse, and manage tasks.' It clearly distinguishes from sibling tools by explaining that this is for visual/browse workflows while todo(action='list') is for quick text answers.

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 this when the user wants to open, browse, filter, or work with their TODOs visually' with examples, and explicit alternatives: 'For a quick text-only answer..., use todo(action='list') instead' and 'Create, update, or complete TODOs with todo(action='create'|'update'|'complete')' and deletion via 'forget'. This leaves no ambiguity about when to choose this tool.

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

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

Annotations already establish the safety posture (readOnlyHint=false, destructiveHint=true, idempotentHint=false), so the description need not restate mutation/destruction. It adds meaningful context beyond annotations: conflict semantics ('with conflicts rejected'), versioning requirements ('expected_version', 'stale writes fail'), and constraint pitfalls ('resource_type is link-only', 'never memory_id'). No contradiction with annotations.

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

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

Roughly 110 words for a tool with 36 parameters and 8 schema variants — every sentence carries a distinct constraint and the core purpose is front-loaded. However, it is a single dense paragraph with heavy semicolon use, which reduces scannability when an agent needs to quickly locate the rule for a specific variant.

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?

Output schema exists, so return values need no explanation. The description covers all variants except the Settings mutation (entity='settings', action='save') and never mentions the idempotent replay key (client_mutation_id). Both are discoverable in the schema's oneOf branches and parameter descriptions, so the gap is minor, but for a tool this complex a complete walkthrough would include them.

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 conditional selection semantics the flat schema doesn't convey: which parameters pair with which action, when project_id must be omitted, the memory_ref vs memory_id pitfall, and the top-level content/tags vs patch.content/patch.tags alternative. Some details duplicate schema descriptions (stale writes fail), but the selection logic and negative constraints are genuine added 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 opening sentence 'Create or mutate an authorized project' states a specific verb and resource while explicitly distinguishing the tool from read paths: 'use open_project_workspace or get_project_summary to read.' The body enumerates the entity variants (project, memory, decision, document, conversation), so an agent can tell this is the project-scoped mutation surface rather than one of the many read/sibling tools.

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

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

Explicitly names the read alternatives and tells the agent when NOT to use this tool ('to read'). Per-variant selection rules are spelled out: 'Project create requires entity="project", action="create", and name, and omits project_id. Other actions require project_id.' Similar conditional guidance is given for memory, decision, document, and conversation mutations, leaving little 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?

Beyond the readOnlyHint, the description adds that the tool reads in character windows (pagination), only returns 'authorized' memories, uses exact IDs, and never returns embeddings. These are meaningful behavioral details not present in 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 exactly two sentences, front-loaded with the core purpose ('Read one exact authorized XMemo memory'), and every clause contributes useful information (authorization, pagination, embeddings). No fluff 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?

Given the presence of annotations, a full output schema, and the tool's relatively simple read behavior, the description fully covers the essential context: pagination semantics, the need for an ID from recall/search, and the exclusion of embeddings. The agent can confidently use this tool without additional undocumented behavior.

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 full descriptions for all three parameters (memory_id, offset, limit) with character-based semantics. The description adds a reference to next_offset for pagination, but this is also implied by the schema. No significant additional parameter meaning is provided.

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

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

The description states 'Read one exact authorized XMemo memory in character windows', which is a specific verb (read), resource (XMemo memory), and mode (character windows). This clearly distinguishes it from sibling tools like recall or search_memory that find memory IDs.

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 explicitly instructs to use a memory ID returned by recall or search, then continue long content with next_offset. This provides a clear workflow for when to use this tool (after finding the ID) and how to paginate, effectively differentiating it from alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by noting the lookup is lightweight, unscoped, and returns only the few most relevant memories, which helps the agent calibrate expectations beyond 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 two tight sentences with no filler. It front-loads the core behavior, then immediately provides routing to alternatives, earning every word.

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

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

Given the rich input schema, detailed parameter descriptions, output schema, and safe annotations, the description provides sufficient high-level context. It covers what the tool does, its lightweight nature, and how it differs from the closest siblings, so an agent has what it needs to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters in detail, including triggers, model responsibilities, and consequences. The description itself adds no parameter-level meaning, but the baseline of 3 is appropriate because the schema carries the full burden.

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 ('Recall') and resource ('saved memories'), and clearly characterizes the operation as a lightweight, unscoped lookup returning the few most relevant results. It also distinguishes itself from sibling tools by naming search_memory and recall_context, so an agent can tell them apart without opening schemas.

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

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

The description explicitly states when to use this tool versus alternatives: use search_memory for a scoped lookup and recall_context for a multi-item context pack. It also frames the tool as something to run 'before answering,' giving clear contextual 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, and destructiveHint=false, and the description reinforces safety with 'read-only'. It adds the useful behavioral trait that the pack is bounded by max_items and max_tokens. The parameter descriptions further disclose consequence-style behavior (e.g., heuristic fallback when since is omitted, fail-closed for activity_log without bounds), though those live in the schema rather than the top-level description.

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

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

Two sentences, no filler. The core purpose is front-loaded, and the alternative routing follows immediately. Every clause earns its place, and the description avoids restating the title or schema contents.

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 a rich schema, output schema, and strong annotations, the description is sufficient: it states the resource, scope, bounds, and sibling alternatives. The schema covers the remaining parameter mechanics, and the output schema removes the need to describe return values. Nothing an agent needs to decide when to call this tool is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The top-level description adds a small layer of meaning by explaining that the tool is appropriate when memory items fit 'within max_items and max_tokens', connecting those parameters to the tool's bounded-pack purpose. It doesn't repeat schema details, but provides selection-level context for the key bounds.

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 ('Build') with a clear resource ('read-only, bounded context pack from multiple relevant memories'). It distinguishes itself from siblings by explicitly naming recall and search_memory, so an agent knows this is the multi-memory bounded-pack tool, not the quick-lookup or strict-match 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?

It gives an explicit when-to-use: 'when an answer needs several memory items within max_items and max_tokens'. It also names the two alternatives and their distinguishing conditions: 'use recall for a quick forgiving lookup or search_memory for strict targeted matching'. This is exactly the routing guidance needed.

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?

Discloses that existing Projects paths attach automatically, which is not evident from annotations. Also flags create_project as deprecated compatibility input and clarifies proper routing. Annotations already establish read/write and destructiveness hints, so the description adds qualitative behavior beyond those.

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, first sentence states purpose, second adds a behavioral detail, third contains two routing caveats. No redundant fluff; all information is actionable.

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 and annotations provide safety hints, the description effectively covers purpose, exclusions, parameter nuances, and routing alternatives. It is sufficient for an agent to decide when to invoke and how to use 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 covers 100%, but description adds meaning to create_project by labeling it 'deprecated ordinary-client compatibility input' and directing to project tool. Also notes automatic attachment for Projects paths, which clarifies the path parameter's behavior.

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

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

The opening phrase 'Save durable information for future recall' clearly identifies the tool's function. It distinguishes itself from transient chat and from Ledger for financial records, and mentions project creation routing, separating it from the project 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?

Explicitly instructs to skip transient chat, provides an alternative for financial records (Ledger), and clarifies that project creation should be routed to project(entity='project', action='create') rather than using create_project. This goes beyond merely implying usage.

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 a key behavioral constraint ('previously deleted memory') and clarifies the intent ('undo a deletion'), which goes beyond the sparse annotations. However, it does not disclose potential error conditions, whether the operation is reversible, or what happens if the memory is already restored. With no meaningful annotations, the description carries the burden but remains thin on 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: the first states the action, the second provides a usage condition. It is front-loaded, contains no redundant information, and every word earns its place. This is a model of concise, well-structured documentation.

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 tool with a clear schema and output schema available, the description is largely sufficient. It explains the precondition and the exact trigger for use. It falls slightly short by not mentioning error scenarios or edge cases, but given the low complexity, this is a minor gap rather than a critical omission.

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

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

The input schema provides 100% coverage with descriptions for both parameters: 'reason' and 'memory_id'. The description does not add any parameter-specific information, so it neither enhances nor detracts from the schema. Baseline of 3 is appropriate given the schema already fully documents the parameters.

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

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

The description clearly states the action: 'Restore a previously deleted memory.' It specifies the resource (memory) and the action (restore), and distinguishes itself from siblings like 'forget' (deletion) and 'recall'/'search_memory' (retrieval). The title reinforces this but the description adds the 'previously deleted' qualifier, making the scope 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 second sentence provides explicit guidance: 'Call this only when the user explicitly asks to restore or undo a deletion.' This directly tells the agent when to use the tool, and the 'only when' phrase acts as an exclusion for all other scenarios. It effectively communicates the when and when-not, leaving no ambiguity about alternative 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=true, idempotentHint=true, and destructiveHint=false, so the safe read-only nature is covered. The description adds meaningful behavioral context beyond annotations by disclosing strong-match semantics and the fact that weak matches must not be surfaced as answers. This helps an agent predict strictness of retrieval 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 three concise sentences with no filler. The primary purpose and matching semantics are front-loaded, followed by sibling routing and a deletion pointer. Every sentence earns its place and directly supports correct tool selection and invocation.

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 seven-parameter complexity, the rich parameter descriptions in the schema, and the presence of an output schema, the description covers the essential selection and behavioral context. It identifies the core semantic distinction, names alternatives, and flags sibling tools. A small gap: it does not summarize the time-window or query-mode behaviors, but those are thoroughly explained in the schema parameter descriptions.

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 itself fully documents all seven parameters, including triggers and model responsibilities for since, until, query_mode, and time_order. The description does not add parameter-level meaning beyond the schema, but it does not need to because the schema already carries that burden.

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

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

The description states a specific verb and resource ('Search XMemo memories') and clarifies the core semantic: strong-match, targeted lookup where weak matches must not be returned. It also names recall, recall_context, and forget as distinct sibling tools, so the agent can immediately tell this tool apart from alternatives.

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 this tool: targeted lookup requiring strong matches. It also gives exact alternatives: use recall for forgiving best-effort retrieval, recall_context for a bounded multi-memory context pack, and forget for deletion. This gives clear routing guidance with no need for inference.

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

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

The description discloses behaviors such as the need for confirmation for delete_all, that deletions are recoverable (soft-delete), and that list actions need proper timezone to avoid misleading due dates. This adds transparency beyond the annotations (readOnlyHint=false, destructiveHint=true) by clarifying the nature of deletion and listing behavior. However, it doesn't mention idempotency or other potential edge cases, but given annotations and schema, 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 compact but covers essential points: the actions, the timezone requirement for list, and the confirmation for delete_all. It is front-loaded with the verb (Create, update...). However, it could be slightly more organized by separating the different action-specific guidance, but it's acceptably concise.

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

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

Given the complexity (22 params, 5 actions) and the presence of output schema, the description covers the most critical usage scenarios: it highlights timezone for list, confirmation for delete_all, and that delete is soft/recoverable. It doesn't explain returns or all actions in detail, but the output schema and the schema's per-parameter descriptions cover much. The description adds essential context for the less obvious aspects, making it fairly 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 schema has 100% description coverage for parameters, so the baseline is 3. The description adds value by explaining the purpose of `owner_timezone` (honest due dates) and `confirm_delete_all` (explicit confirmation for delete_all). It also hints at relationships between action and required params via conditional schema. The description goes beyond the schema by explaining the context for these parameters, so a 4 is warranted.

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 the tool performs 'Create, update, complete, list, or bulk soft-delete authorized TODOs' with specific verbs and resources. It clearly covers the main actions and differentiates from siblings like open_todo_board or ledger by focusing on CRUD operations for 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 explicit guidance: for action='list' it instructs to provide the user's real IANA owner_timezone or use a saved owner profile timezone to ensure honest due dates. It also specifies that delete_all should only be used after explicit user confirmation and requires confirm_delete_all=true. These are clear usage directives beyond what the schema states.

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, setting the safety baseline. The description adds useful context about the need for an exact reference and the updatable aspects, but it does not explain side effects like partial vs. full replacement, handling of non-existent IDs, or whether all optional fields default behavior. Thus it adds some value beyond annotations but not extensive.

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: two sentences, no filler, and front-loaded with the action and resource. It covers the purpose and the key constraint (exact reference) without redundancy.

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

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

For a mutating tool with an output schema and annotations, the description is reasonably complete: it explains the trigger, the aspects updated, and the need for an exact reference. However, with many sibling tools including project_workspace_memory_update, it does not explicitly distinguish from that potentially similar tool, which could cause confusion in selection. The description is adequate but not exhaustive.

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 descriptions already cover 100% of the four parameters with detailed explanations. The description's mention of 'content, location, or type' maps to the content, path, and memory_type parameters, reinforcing the schema but not adding new semantics. The baseline for full schema coverage is 3, and no additional parameter insight is provided.

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

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

The description clearly states the tool updates a specific saved memory, with a specific verb ('Updates') and resource ('saved memory'). It specifies the scope (content, location, or type) and the trigger (user asks to correct, revise, move, or reclassify), distinguishing it from create/delete/read siblings like 'remember', 'forget', and 'search_memory'.

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

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

The description provides clear context for when to use the tool ('when the user asks to correct, revise, move, or reclassify it') and notes that an exact reference identifies the record, implying that memory_id is required and likely obtained from prior search/recall. It does not explicitly name alternatives or exclusions, but the context is sufficient for most cases.

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