MemorySync

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

With annotations present (readOnlyHint=false, destructiveHint=false), the description still adds real behavioral value: the extraction pipeline, filler discarding, near-duplicate merging, and the important note that a skipped result is normal rather than an error. The only gap is what happens to the existing memory when a merge occurs.

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

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

Two tight sentences with the core action front-loaded and the non-obvious pipeline behavior immediately after. No filler, no repetition of the schema.

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

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

An output schema exists, so return-value explanation is unnecessary, and the description covers the surprising result case (skipped is normal). What is missing is what a successful merge does to the prior memory and whether repeated identical calls are safe, which matters given idempotentHint=false.

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

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

Schema description coverage is 100%, so all three parameters (text, source, metadata) are already documented in the schema. The description adds no syntax, format, or content examples for 'text' beyond what the schema states, so the baseline of 3 applies.

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

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

States a specific verb and resource with scope: 'Store a durable fact or preference about the user.' An agent can distinguish this from delete_* and get_* siblings on the write/read axis, but the description never names the closest alternative (update_memory) to make the add-vs-update boundary 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?

Usage is implied by the verb 'store' and by the note that near-duplicates are merged, which hints this is for new facts rather than edits. However, there is no explicit when-to-use guidance, no mention of when to prefer update_memory, and no prerequisites stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds behavior an agent cannot infer from them: the safe-by-default dry run, the count-only preview response, and the exact confirmation string gate. This is exactly the extra context a destructive tool needs.

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

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

Three sentences, zero waste, and correctly front-loaded: what it deletes, then the safety default, then the hard precondition. Every clause carries load.

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

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

For a destructive bulk-delete with an output schema already covering the return shape, the description supplies everything an agent needs: scope, default behavior, the confirmation gate, and the explicit user-consent requirement. Nothing material 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 both parameters are already fully documented in the schema. The description restates the confirm string value and dry_run default rather than adding new meaning, which lands at the baseline for high-coverage schemas.

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

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

States a specific verb (delete) and resource (all memories) with an explicit scope qualifier: 'all memories this connection can reach.' That scope wording cleanly separates it from the singular siblings delete_memory and delete_entity.

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

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

Gives explicit usage conditions and a hard exclusion: the default is a dry run reporting only a count, and the real deletion requires dry_run=false plus an exact confirm string. It also states 'Never call this without the user explicitly asking to erase everything,' which is the strongest possible when-not guidance for a destructive tool.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotency, so the safety profile is covered. The description adds genuinely useful behavior the annotations don't: that the call defaults to a preview/dry run and should only be executed for real after explicit user confirmation, which is critical for a destructive bulk operation. It does not address re-invocation/idempotency behavior, leaving a small gap.

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

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

Two tight sentences with no filler. The destructive scope is front-loaded, followed immediately by the safety default and the confirmation gate, which is the right ordering for a destructive tool.

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

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

An output schema exists, so return values need no explanation. Given the tool is a simple three-parameter bulk delete, the description covers everything an agent needs: valid identifier source, deletion scope, dry-run default, and the confirmation requirement before real deletion.

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

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

Schema coverage is 100%, so entity_type and entity_id are already documented and the baseline is 3. The description adds value by reinforcing the dry_run semantics with a workflow rationale ('pass dry_run=false to delete after the user confirms') and by tying entity_id to list_entities output, which clarifies the dependency beyond the raw field description.

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

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

The description gives a precise verb+resource+scope: 'Delete every memory belonging to one entity returned by list_entities.' This scope language cleanly separates it from delete_memory (one memory) and delete_all_memories (everything), even without naming them, and the 'cursor' source example makes the entity concept concrete.

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 establishes the workflow context by pointing back to list_entities as the source of valid entity identifiers, and it states the safe default (dry run) plus the condition for real deletion after user confirmation. It does not explicitly contrast against delete_memory or delete_all_memories, so it stops short of a full when-to-use-one-vs-alternative statement.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds meaningful context beyond that: permanence, irreversibility, and an explicit user-confirmation requirement before invocation.

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, with the destructive consequence and the confirmation requirement front-loaded where an agent will act on them.

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

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

An output schema exists and annotations carry the safety profile, so the description need not explain returns. It covers the essential caution well, though it says nothing about behavior when an id does not exist or about partial failures in a multi-id batch.

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

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

Schema coverage is 100% and the parameter is fully documented in the schema with an example. The phrase 'one or more' and 'by id' lightly reinforce the batch/array semantics but add nothing the schema does not already state.

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

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

States a specific verb and resource ('Permanently delete ... memories') and narrows scope with 'by id', which implicitly separates it from delete_all_memories. It never names the sibling explicitly, so the differentiation is inferable rather than stated.

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

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

Gives one real usage condition — confirm with the user before calling — which is valuable. But it offers no guidance on choosing between this and delete_all_memories, delete_entity, or update_memory when the user's intent is ambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds real context beyond them: this is a polling tool reporting pipeline position and searchability. It does not mention whether statuses reach terminal states or how often to poll, so not a 5.

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

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

Two tight sentences with zero waste; the purpose comes first and the usage directive second. Every clause carries 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?

With only one required parameter, an output schema covering return values, and annotations covering the safety profile, the description supplies everything needed to invoke it correctly. Minor gap in not hinting at possible ingestion states, but that is likely covered by the 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 coverage is 100% and the single parameter is fully documented as 'the memory id returned by add_memory'. The description only restates 'one memory' and adds no format or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (report) on a specific resource (one memory's position in the ingestion pipeline) plus the key output fact (whether it is searchable yet). This cleanly separates it from content-returning siblings like get_memory and list_memory_events.

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 it (poll after add_memory) and warns against a concrete misuse (adding again). The trigger condition and the anti-pattern are both stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is fully covered. The description adds only the minor point that the id originates from search/list; it says nothing about behavior on an unknown id (e.g., error vs empty result) or access requirements.

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

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

One short sentence, front-loaded with the core action and scope, with no redundant or filler content. Every clause earns its place.

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

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

With a full output schema and annotations covering safety and idempotency, the description needs only to identify the operation and its input origin, which it does. Only the not-found/error behavior is unaddressed, a minor 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% and the single parameter includes its own example ('m_123'), so the schema carries the parameter semantics. The description only adds where the id comes from, which is a marginal contribution beyond structured data.

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

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

States a specific verb ('Retrieve'), resource ('a single memory'), and lookup key ('by its id'), which distinguishes it from the bulk siblings list_memories and search_memory. It is clear but never names a sibling explicitly, so differentiation is implicit rather than 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?

'As returned by search or list' implies the usage context — fetch full detail for an id you already have — but there is no explicit when-to-use/when-not statement or named alternative. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds that the result is a derived, aggregated standing profile rather than raw hits, but does not touch on refresh semantics or behavior when no history exists — modest added value over 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 sentences with zero waste; the purpose and its contents come first, and the usage instruction follows. Every clause earns its place.

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

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

An output schema exists, so return values need not be explained, and the read-only annotations plus the usage framing make the definition largely complete. It could still note fallback behavior (e.g., cold-start users with no memories), a minor omission.

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

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

Schema coverage is 100% and the single parameter (lookback_days, default 90, range 1-365) is fully documented in the schema. The description adds no meaning beyond it, so the baseline of 3 applies.

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

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

States a specific verb ('Return') and resource ('standing profile derived from this user's memory'), then enumerates the contents (communication style, recurring topics, work context, learned preferences). It also distinguishes itself from the sibling search_memory by contrasting 'standing profile' with 'individual search hits'.

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 it ('once at the start of a conversation to personalise your replies') and names the alternative to avoid ('instead of inferring it from individual search hits'), which routes the agent away from search_memory for this purpose.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add semantics beyond that, which it does by framing this as a graph traversal over typed edges and by naming the contradiction-checking use case. It stops short of describing result shape, edge-density or truncation behaviour, so it is strong but not exhaustive.

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

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

Three tight sentences: the operation first, then the use case, then the contrast with the sibling. Every clause carries information and nothing is repeated from the schema or annotations.

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

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

An output schema exists, so return values need no explanation, and all four parameters are fully documented in the schema. The description supplies the missing conceptual layer — that results come from typed edges and can surface contradictions — leaving nothing an agent needs in order 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 memory_id, limit, direction and relationship_types. The description's enumeration of edge types loosely maps to the relationship_types values, but it gives no syntax or default guidance for direction or limit, so this is the baseline case of the schema doing 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?

States a specific verb and resource ('follow the typed relationship graph out from one memory') and enumerates the edge semantics it traverses (supports, contradicts, summarises, continues, resembles). It explicitly differentiates itself from the likely sibling: 'Search answers what is relevant; this answers what is connected.'

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

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

Gives concrete triggering conditions ('when the question is how facts relate', 'to check whether a memory you are about to rely on is contradicted by another') and names the competing approach (search) with the distinction that selects between them. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only that the listing is workspace-scoped and includes sync state; it says nothing about pagination, staleness of the sync state, or auth requirements. Useful but thin beyond what annotations provide.

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

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

A single front-loaded sentence: scope first, then examples, then the returned state. The eight-item example list is slightly enumerative, but each item genuinely expands what counts as a 'source', so it earns its space.

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 zero parameters and an output schema present, the description does not need to explain return values, and it covers scope plus the nature of the results. The one small gap is that it gives no cue about when sync state might be stale or how to act on 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?

The tool takes zero parameters, so the baseline is 4 — there is no argument syntax for the description to clarify, and the description correctly adds no parameter guidance because none is needed.

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

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

Specific verb ('List') plus resource ('knowledge sources connected to this workspace'), and it enumerates concrete examples (GitHub, Slack, Notion, Google Drive, OneDrive, Granola, S3, crawled website) so an agent knows exactly what kind of entities are returned. It also names the returned attribute (sync state), which no sibling tool covers.

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

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

Usage is implied by the name and description — read this to discover what sources exist — but there is no explicit when-to-use statement, no exclusions, and no alternatives named. The sibling list is entirely memory/entity tools, so there is little ambiguity to resolve, but the description does not do that work itself.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds little beyond that: it says results are scoped to 'this user's memories' and include counts and last activity, but since an output schema exists, those return details are partly redundant and no pagination or volume limits are mentioned.

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

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

Two sentences, zero filler, and the primary behavior (grouping with counts and last activity) is front-loaded ahead of the usage advice. Every clause carries 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?

With an output schema and rich annotations already present, the description only needs to orient the agent, and it does: scope, grouping modes, payload, and use cases. Minor gaps (whether entities are global or per-source, expected result volume) keep it from a 5, but nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns a notch above by mapping the three grouping choices to plain-language axes (origin source, extracted category, extracted type), reinforcing the enum's meaning before the agent opens the schema. It still doesn't mention the omit-to-return-all default, which the schema carries alone.

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

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

The description gives a specific verb (group/list) and resource (this user's memories as entities), and defines what an 'entity' is by naming the three grouping axes: origin source, extracted category, extracted type. It also states the payload (counts and last activity), which distinguishes it from list_memories 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?

It gives two concrete use cases: 'see what is stored before searching' and 'find an entity to delete'. The first implicitly routes against search_memory, and the second toward delete_entity. No explicit when-not or named alternative, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds only that results are 'most recent' (ordering) and that no search is performed, which is modest additional context beyond 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?

A single front-loaded sentence with no filler. Every word contributes to the tool's scope and mode.

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 annotations covering safety, an output schema defining returns, and 100% parameter description coverage, the description provides enough to invoke correctly. The only real gap is explicit sibling routing, but 'without searching' gives a usable hint.

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

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

Schema description coverage is 100%, so all eight parameters are documented in the schema itself. The description adds no parameter semantics, so the baseline of 3 applies.

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

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

States a specific verb (List) and resource (memories) with scope (user's most recent) and distinguishes itself from search_memory via 'without searching'. It does not name the alternative explicitly, so it is clear but not a perfect sibling differentiation.

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

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

The phrase 'without searching' implies a browsing use case, but no explicit when-to-use or when-not guidance is given, and no alternatives such as search_memory are named. The agent must infer that this tool is for non-query retrieval.

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 non-destructive behavior, so safety is covered. The description adds real value beyond that: newest-first ordering and an enumeration of the event kinds recorded (adds, forgets, summaries, imports), which is behavior the annotations cannot convey.

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

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

Two sentences, zero filler. The core identity of the tool (lifecycle log, newest first) is front-loaded and the use case follows immediately.

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

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

An output schema exists, so return-format detail is unnecessary, and all 7 optional filters are schema-documented. The description covers ordering and intent, leaving only marginal gaps such as whether omitted filters mean 'all events' or the scope of 'this user's memory' in a multi-workspace context.

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

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

Schema description coverage is 100% with every one of the 7 filters individually documented, so the baseline of 3 applies. The description's enumeration of event types marginally informs the event_type filter, but it adds no syntax, format, or default details beyond what the schema already provides.

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

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

The description states a specific verb and resource — reading the memory lifecycle log — and enumerates its content (adds, forgets, summaries, imports) with ordering (newest first). This clearly distinguishes it from siblings like get_memory or search_memory, but it never names an alternative explicitly, so sibling differentiation is implicit rather than stated.

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

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

'Use it to explain why a memory is present or missing' gives a concrete, actionable use case rather than mere restatement. However, there are no when-not conditions and no named alternative (e.g., get_memory for a single record's current state vs. this log), so guidance is clear but incomplete.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that results are ranked 'best matches,' but says nothing about paging behavior, result caps, or empty-result handling beyond what the schema notes. Useful but thin against an already-rich annotation set.

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

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

Two sentences with zero filler: the capability first, the usage trigger second. Front-loaded and 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?

An output schema exists, so return values and the next_offset field need no prose. Combined with 100% parameter coverage and explicit annotations, the description supplies the one thing structured data cannot: when to reach for this tool.

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

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

Schema description coverage is 100%, so every parameter (tags, tier, limit, offset, source, event_type, date bounds) is already documented, including the next_offset paging convention. The description only implies that query is natural language and adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (search) and resource (user's stored memory) and the outcome (best matches), which separates it from get_memory and list_memories by implying relevance ranking rather than lookup or enumeration. It never names those siblings explicitly, so differentiation is inferable rather than stated.

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

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

Gives a clear usage trigger: 'Use this before answering anything that depends on what the user told you previously.' That is actionable context, but there are no exclusions and no named alternatives (e.g., get_memory for an exact known ID, list_memories for full enumeration), which leaves routing 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?

Annotations already declare non-readOnly, non-destructive behavior, but the description adds important context the annotations cannot: that only labels are mutable and the memory text is immutable, plus the correction workflow via add_memory. It doesn't mention permission or auth requirements, so it isn't exhaustive.

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

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

Two tight sentences: the actionable scope comes first, followed by the key limitation and its alternative. Every clause carries information and there is 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?

With annotations covering safety and an output schema covering returns, the description supplies the one non-obvious rule an agent needs — text immutability — making it largely complete. Minor gaps remain around auth or failure behavior, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents each parameter including replace-vs-clear semantics for tags and reserved-key handling for metadata. The description only echoes the field names without adding syntax or format detail, making 3 the right baseline.

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

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

The description names a specific verb ('Change the labels') and resource ('an existing memory'), then enumerates the exact mutable fields (tags, importance, metadata, source, event_type). This clearly separates it from siblings like add_memory and delete_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 explicitly states the boundary condition — the memory text cannot be edited — and routes the agent to add_memory for corrections, which is a genuine alternative with a selecting condition. It doesn't address broader routing against get_memory or delete_memory, so it falls short of a full when/when-not map.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is fully covered. The description adds the diagnostic framing (explaining refused writes) but little beyond that; return content is carried by the output schema.

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

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

Two tight sentences with zero waste: purpose first, then the situational trigger. Nothing extraneous or repeated from structured fields.

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 carrying the return shape, rich annotations covering safety, and no parameters, this short description supplies everything an agent needs to decide to call it and interpret why.

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 takes zero parameters, so there is no per-argument semantics to document; baseline 4 applies. The description correctly implies no inputs are needed.

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

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

States a specific verb (Report) and resource (how this client is authenticated and what it is allowed to do), making the tool's function unmistakable. It is clearly distinct from all siblings, which are memory CRUD/search 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?

Gives a concrete trigger condition: 'Useful when a write is refused and you need to explain why.' This tells the agent when to reach for it. It stops short of naming when-not-to-use or alternatives, though no sibling overlaps this diagnostic role.

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