polymnemo

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

The description reveals side effects and failure modes beyond the generic annotations: it verifies object existence, records real size and checksum, rejects oversized uploads, and makes the memory findable/downloadable. This is meaningful behavioral detail an agent cannot infer from readOnlyHint/destructiveHint alone.

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 core action is front-loaded, and every sentence contributes a necessary piece of information: precondition, behavior, source of id, and return shape. There is no filler or restating of title.

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

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

For a single-parameter finalization step, the description covers enough of the workflow, side effects, validation, and return value. Since an output schema exists, the described return shape is a useful addition rather than redundant, and all essential agent guidance is present.

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 only contains an unannotated string parameter id, so the description's note that id comes from create_upload is crucial. It tells the agent where to get the value and how it relates to the upload flow; a little more format detail would be nice, but it is adequate for one parameter.

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 begins with a specific verb and resource ('Confirm a media upload') and includes a precondition ('after you've PUT the bytes'). It then details what the confirmation does — verifying existence, recording size and checksum, and making the memory findable/downloadable — which clearly separates it from siblings like create_upload.

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 workflow guidance: call this only after PUTing the bytes, and use the id returned from create_upload. It does not name alternatives because the sequencing itself is sufficient to disambiguate, though there are no explicit exclusions.

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, the description discloses critical behavior: the memory stays hidden until confirm_upload is called, the size cap is enforced at that point, and the upload headers contain the signed Content-Type. This gives an agent a clear mental model of the side effects and lifecycle, which is exactly what behavioral transparency should provide. No contradiction with annotations exists.

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, front-loaded with the core purpose, and every sentence contributes actionable information. The heavily formatted upload flow and confirmation requirement are communicated without fluff. It packs a lot of necessary protocol detail into a few sentences while remaining scannable.

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

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

For a tool with four parameters, no schema descriptions, and an output schema, this description is remarkably complete. It covers the full lifecycle: registration, raw byte upload, required confirmation, visibility semantics, and default namespace behavior. An agent has enough information to invoke the tool correctly and understand what the subsequent steps should be.

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

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

The input schema has zero descriptions for its parameters, so the description carries the responsibility for clarifying them. It explains that description is embedded for recall, that content_type is signed into upload_headers, and that namespace defaults to private. Filename is not explicitly explained, but it is self-evident from the 'file / image / video' framing, so the compensation is strong.

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

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

The description opens with a specific verb and resource: 'Register a file / image / video memory and get a URL to upload its bytes.' This clearly distinguishes the tool from related siblings like recall or remember by focusing on the upload registration flow. It also names confirm_upload as the required follow-up, which further differentiates it within the sibling set.

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 concrete usage direction: PUT raw bytes to upload_url with upload_headers, then call confirm_upload. It also states that bytes never go through this channel)Skip and that media defaults to a private namespace)Skip providing strong contextual guidance. It stops short of explicitly saying 'when not to use this tool' or naming alternative tools like remember for non-upload memories, so it earns a 4 rather than 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 destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds valuable specifics beyond annotations by documenting the return shape `{id, deleted}` and the graceful `deleted=false if absent` 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 a single, front-loaded sentence with no filler. It states the action first, then the return shape, and every word earns its place.

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

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

For a simple single-parameter delete operation, the description is complete: the id is specified, the output shape is stated, absence behavior is covered, and destructive/idempotent semantics are already conveyed by annotations. An agent has what it needs to call the tool correctly.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning. It says 'by id,' which clarifies the role of the id parameter, but it does not add detail about the id format, source, or any constraints beyond the schema's plain string type.

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

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

The description uses a specific verb and resource: 'Delete a memory by id.' It clearly distinguishes this from siblings like get_memory, list_memories, remember, and recall by making the destructive action and required identifier 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 usage is implied: call this when you have a memory id and want to delete it. However, the description does not explicitly contrast with sibling tools or state when not to use it, leaving the routing to inference rather than direct 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 include readOnlyHint: true, and the description aligns by saying it's a 'short-lived URL' for downloading, which is a read operation. It goes beyond annotations by disclosing the URL is short-lived, implying the agent should call it close to when the download is needed. It also clarifies the return type and that it returns bytes, providing useful behavioral context that the schema doesn't.

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 highly concise: two sentences. It packs crucial information in a short space, front-loading the purpose and then adding essential parameter context and return format. Every word adds value; no fluff.

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

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

Given the tool's simplicity (one parameter, simple return), the description covers the essentials: what it does, how to get the id, and the return shape. It might benefit from noting the URL's expiration time, but the output schema existence reduces the need to detail the return structure. Overall, an agent has what it needs to call 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 schema has only one parameter 'id' with no description (0% coverage). The description compensates by explaining that 'id is the media memory's id (from create_upload / recall),' which directly adds semantics to the parameter that the schema lacks. Since there's only one param, this is sufficient.

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

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

The description clearly states the tool's purpose: 'Get a short-lived URL to download a media memory's bytes.' It distinguishes itself from siblings like 'get_memory' and 'list_memories' by specifying it returns a download URL for media, not just metadata or full memory content. The verb 'Get' and the resource 'short-lived URL' are specific and informative.

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

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

The description implies the tool is for downloading media memory bytes, and it mentions the id comes from 'create_upload' or 'recall', giving context on when to use it. It doesn't explicitly say when not to use it or name alternatives, but the dependency on prior actions is clear, which is adequate for a simple tool with few siblings.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the useful context that the id comes from `remember`/`recall`/`list_memories`, but doesn't disclose behavior like what happens if the id is not found or whether the memory content is returned in full. With annotations covering the read-only nature, a 3 is appropriate.

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

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

A single sentence that is front-loaded with the action and resource, and includes the source of the id. Every word earns its place; 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?

For a simple single-parameter read tool with an output schema and readOnlyHint annotation, the description is nearly complete. It could mention error behavior for a missing/invalid id, but the output schema likely covers the return shape, and the read-only annotation covers safety. The main gap is the lack of explicit id format guidance.

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 0%, so the description must compensate. It does explain that `id` is the memory identifier and where to get it, which adds meaning beyond the bare schema. However, it doesn't specify the id format or any constraints, so it only partially compensates for the missing schema descriptions.

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

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

The description clearly states the tool fetches a single memory by its id, with a specific verb ('Fetch') and resource ('a single memory'). It also names the source of the id (`remember`/`recall`/`list_memories`), which distinguishes it from sibling tools like `list_memories` and `recall`.

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

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

The description implies when to use this tool: when you have a specific memory id from one of the listed tools. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to select it over `list_memories` or `recall`.

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

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

Beyond the readOnlyHint annotation, the description adds real behavioral detail: return ordering, lack of query filtering, namespace default, and pagination via next_cursor/has_more. These are exactly the traits an agent needs to predict how the call behaves.

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 tightly-scoped sentences with the core operation front-loaded and code-formatted field names. There is no filler, and every sentence adds useful information.

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

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

For a read-only list operation with three optional parameters and an output schema, the description covers the essential behavior: what is listed, sort order, namespace semantics, pagination, and return shape. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clearly explains namespace (selects collection, defaults to shared) and cursor/pagination, though it does not explicitly describe the limit parameter or spell out that next_cursor should be passed as cursor.

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 a specific operation ('List stored memories'), a concrete ordering ('newest-first'), and an explicit scope boundary ('no search query'). This immediately distinguishes the tool from search/retrieval siblings such as recall and get_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 clear usage context: this is a browse-all listing rather than a search, and it explains namespace selection and pagination workflow. It does not explicitly name the alternative tool for search or state when not to use list_memories, 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?

With readOnlyHint already provided, the description adds useful behavioral context beyond the annotation: the tool is paged, page is 0-based, and the caller must rely on has_more to continue. It does not describe error handling for missing sessions, but for a read-only pagination tool the main behavior is disclosed.

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, front-loaded with the core action, and each sentence carries useful information: the resource, the pagination approach, and the expected return shape. The listed return object is slightly redundant if a full output schema is present, but the text remains efficient.

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 that this is a simple read-only, paged retrieval tool with an output schema available, the description covers the core operational flow sufficient for an agent to loop through pages. The main gap is the under-described parameters, especially session_id and page_size semantics.

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 0%, so the description must compensate. It only explains the page parameter, including its 0-based semantics and its relationship to has_more. It does not explain what session_id refers to as an input, nor what page_size means beyond its default 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 states a specific action and resource: reload a saved session's content, and adds the distinguishing detail that it is served one character page at a time. This separates it clearly from save_session, recall, and get_memory, even without naming them.

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

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

It gives clear guidance on when the tool is applicable: reloading an already-saved session's content. It also explains the pagination loop, telling the agent to keep requesting while has_more is true. It stops short of explicitly naming alternatives or exclusion conditions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context about what the response contains (server identity and active pluggable layers) and the intended client (MCP Inspector). It doesn't disclose any side effects, but for a read-only health check with zero parameters, the description carries enough behavioral context.

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

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

Two short sentences, front-loaded with the purpose ('Health / connectivity check') and then a concise explanation of the return value. Every sentence earns its place; 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?

For a zero-parameter, read-only health check with an output schema present, the description is complete. It tells the agent what the tool does, what it returns, and who uses it. There is nothing else an agent needs to invoke it correctly.

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

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

The tool has zero parameters, so there is no parameter semantics burden. The description explains what the tool returns, which is the closest relevant semantic content. Baseline 4 for zero params is appropriate.

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

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

The description clearly identifies this as a health/connectivity check with a specific verb ('confirm the connection') and resource ('server identity plus active pluggable layers'). It distinguishes itself from the sibling tools, which are all about uploads, memories, and sessions, by being the only connectivity check.

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

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

The description states when to use it: to confirm the connection and see how the server is wired. It doesn't explicitly name alternatives or exclusions, but the context of a health check is clear and distinct from the sibling tools. A slight gap is not saying 'use this first before other calls' or 'not for data operations'.

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 the description adds meaningful behavior beyond that: results are ranked by similarity, limited by default 8, paginated via next_cursor/has_more, and namespace defaults to shared. This gives the agent a solid model of side-effect-free search behavior 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?

Three economical paragraphs lead with the core purpose, then ordering/limit, pagination, namespace, and return shape. Every sentence carries useful operational information, and the structure lets an agent quickly absorb how to call the tool correctly.

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 4-parameter search tool with no schema descriptions and an output schema present, this description covers all needed operational details: query semantics, result ranking and bound, pagination workflow, namespace behavior, and return shape. Nothing essential is left to guesswork.

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

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

With 0% schema description coverage, the description compensates for every parameter: query (meaning-based match), limit (bounds results, default 8), cursor (use with next_cursor/has_more), and namespace (selects collection, shared default). This is far better than relying on bare property names and types.

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

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

The description opens with a specific verb+resource: 'Search memories by meaning and return the closest matches.' This distinguishes it from sibling retrieval tools like get_memory (single exact) and list_memories (listing), and from mutation tools like remember/forget. No ambiguity remains about the tool's core function.

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 establishes clear usage context: semantic similarity search with ranked results, pagination via cursor/has_more, and namespace selection. It does not explicitly name an alternative when not to use recall, but the context is clear enough for an agent to choose correctly in most 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 mark the tool as a non-read-only, non-destructive write. The description adds meaningful behavioral context: large content is chunked into multiple vectors/ids on write, namespace defaults to the shared namespace, and the return object is {ids, chunks, namespace}. These are non-obvious side effects an agent needs to know.

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 short and each sentence earns its place: purpose, chunking side effect, parameter semantics, and return shape. It is front-loaded with the primary action and contains no redundant 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?

For a write tool with one required parameter, this is complete: it names the action, the chunking side effect, namespace behavior, optional metadata, and the exact return shape. An agent has enough context to invoke it correctly without needing additional assumptions.

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 0%, so the description must carry parameter meaning. It explains that namespace groups memories and defaults to the shared namespace, and that tags/source are optional metadata; content is sufficiently implied by 'store a memory'. This compensates for missing schema descriptions, though explicit semantics for every parameter are not fully spelled out.

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 first sentence names the exact operation and resource ('store a memory') and the purpose ('for later semantic recall'), clearly distinguishing this write path from sibling retrieval/deletion tools like recall, get_memory, list_memories, and forget.

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 purpose sentence implies when to use the tool (persist a memory for later semantic recall), but it does not explicitly contrast it with siblings such as recall or update, and it states no when-not conditions. The guidance is usable but relies on inference.

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

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

The description adds useful behavioral detail about chunked storage, searchability via recall, and return shape. However, it contradicts the annotations: 'Re-saving the same session_id replaces it' describes destructive overwrite behavior, while destructiveHint=false signals no destructive operations.

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 with no filler. The core purpose is front-loaded, and each subsequent sentence adds distinct value: storage format, overwrite semantics, and return shape.

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

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

The description covers storage format, idempotency, and return value, and an output schema exists. However, namespace semantics are unexplained and the annotation contradiction undermines an agent's ability to reason about safety. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clarifies session_id as the storage key and implies content is the session content, but it never explains the content string format or the nullable namespace parameter. This is insufficient compensation for the missing schema descriptions.

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

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

The description opens with a specific verb and object: 'Persist a session's full content under session_id for later reload.' This clearly states what the tool does and distinguishes it from siblings like load_session and recall.

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 clear context: use this to save a full session for later reload, and re-saving replaces existing content. It does not explicitly name alternatives or exclusion criteria, but the intended use case is unmistakable.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds context beyond these by disclosing that the operation regenerates the embedding and returns the updated memory. It does not contradict 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?

One sentence conveys the operation, a meaningful side-effect, and the return value. It is front-loaded and contains no filler or repetition.

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

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

For a simple two-parameter mutation with annotations and an output schema, the description is largely sufficient: it names the action, the affected resource, the embedding side-effect, and the return. It lacks explicit usage differentiation, but the minimal surface area keeps this from being a major gap.

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

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

The schema provides 0% description coverage, so the description must compensate. It adds meaning for 'content' but leaves 'id' as implicitly identifying a memory; no format, constraints, or behavior for invalid ids are mentioned. This is only partial compensation for the schema gap.

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

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

The description uses a specific verb (replace) and resource (a memory's content), and adds the side-effect 're-embeds it' plus the expected return. This clearly distinguishes it from sibling tools like remember (create) and forget (delete).

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 tool's behavior implies it should be used when updating an existing memory's content via its id, but the description provides no explicit guidance on when to choose it over remember or other sibling tools, and no exclusions or prerequisites are stated.

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