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

With no annotations, the description carries the full behavioral burden. It usefully discloses that archiving is reversible and version-checked, but omits permissions, what archiving actually changes, error behavior on version mismatch, and whether archived items are hidden or moved.

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 sentence is short, front-loaded with the core action, and free of filler. Every clause contributes either the operation, its reversibility, or its concurrency constraint.

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

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

For a mutation tool with no annotations, no output schema, and 0% schema coverage, the description is too sparse. It does not tell the agent how to obtain expected_version, what archive state means operationally, or what happens on failure.

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 explain the two required parameters. It only hints at expected_version through 'concurrency protection' and says nothing about memory_id or version acquisition/error semantics.

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 and resource: archive a memory. It also adds two distinguishing traits, reversibility and concurrency protection, but does not explicitly differentiate this tool from siblings such as restore_memory_revision or update_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?

There is no explicit guidance on when to use archive_memory versus alternatives like update_memory, move_memory, or restore_memory_revision. The reversible-archive implication is present, but the agent must infer the selection 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?

No annotations are provided, so the description must carry the full behavioral burden. It mentions durability and idempotent retries, but it does not disclose permissions, duplicate-handling behavior beyond retry keys, whether creation is reversible, or what the tool returns.

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 short, front-loaded sentences with no wasted language. The purpose and retry instruction are stated 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?

This is a complex 12-parameter mutation tool with no annotations and no output schema. The description does not explain how to populate the three required fields or the optional fields, nor does it describe the creation effect, making it inadequate 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 only 8%, and the description explains only idempotency_key. It leaves title, body, tags, source, summary, metadata, space_id, confidence, session_id, category_id, and auto_prefetch_level unexplained, despite low schema coverage requiring the description to compensate.

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: "Save a durable memory." It also adds timing context with "after search," but it does not explicitly distinguish creation from the sibling update_memory 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?

"After search" gives implied usage context, and "Reuse the idempotency key for retries" gives retry guidance. However, it does not state when not to use this tool, how it differs from update_memory, or any prerequisites.

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 no annotations, the description carries the full burden and does add real behavioral context: secrets are global, creation occurs in the 'active provider', and space_id is deprecated. It says nothing about permissions, whether the value is stored encrypted, what happens on duplicate name collision, or what the call returns (no output schema exists), which is a meaningful gap for a write tool handling secrets.

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 short sentences, front-loaded with the action and the duplicate-check workflow, then the scope constraint, then parameter notes. Every sentence conveys something, though the phrasing is telegraphic enough that 'Defaults to the active provider' could have been clearer than 'in the active provider'.

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 mutation tool with no annotations, no output schema, and 0% schema coverage, the description covers the important global scope and deprecation details but leaves the majority of parameters and the entire return contract unexplained. It is adequate to avoid gross misuse but not complete enough to call correctly without studying the schema.

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

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

Schema description coverage is 0%, so the description must compensate and it only partly does: folder_id's empty-string-vs-omission distinction and space_id's deprecation are genuinely additive facts not present in the schema. The remaining parameters — uri, value, username, description, and especially value_type with its 7-value enum — receive no semantic guidance at all.

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 verb 'Create' plus the tool name and the scope qualifier 'in the active provider' make the action unambiguous, and 'Secrets are global' distinguishes it from anything workspace-scoped. It does not explicitly contrast itself with update_secret or the other write siblings, but the operation is easy to place.

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?

'Create ... after searching for duplicates' gives a concrete pre-step that maps to the search_secrets sibling, so an agent knows the intended workflow order. It stops short of naming alternatives or stating when a different write tool (update_secret, migrate_secret) should be chosen instead, so no explicit exclusions exist.

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 no annotations, the description must carry the behavioral burden. It usefully discloses that external writes are required and that existing folders should be checked first, but it omits permissions, duplicate-name handling, idempotency, and return behavior for this mutation.

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 core action and followed by the key prerequisite and side effect. There is no redundant or wasted text.

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 one-parameter create tool with no annotations or output schema, the description is minimally adequate but incomplete. It communicates creation, pre-check, and external writes, yet leaves out duplicate behavior, permissions, and what the call returns.

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 only parameter, 'name', has 0% schema description coverage, so the description must compensate. It only implies that 'name' is a vault folder name and adds no format, constraint, or uniqueness guidance.

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 has a specific verb ('Create') and resource ('vault folder'), and it distinguishes the tool from create_secret by focusing on folders. It does not explicitly name the sibling list_secret_folders as the pre-check tool, so it falls short of full 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 'after checking existing folders' gives a clear usage prerequisite, and 'Requires external writes' signals an important operating condition. There is no explicit when-not guidance or named alternative tool, but the context for when to use it is clear.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it discloses almost nothing: no mention of whether this is a safe read, what happens if the memory_id does not exist, whether archived or deleted memories are returned, or what the response contains. "its current version" is the only behavioral signal and is not explained.

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 short sentence is front-loaded and wastes no words, but the brevity comes at the cost of specification rather than from efficient information density. There is no structure beyond the one clause.

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 tool with no annotations, no output schema, and no parameter documentation, the description should explain what is returned (metadata, content, version info) and how errors are handled. Neither is covered, so an agent cannot predict the result of the call.

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% for the single required parameter memory_id, so the description must compensate. It never mentions the identifier at all, leaving the agent to infer that memory_id is the id of the record to read and what format it takes.

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 verb ("Read") and a resource ("a record"), and mentions retrieving the current version, which hints at versioning semantics. However, it calls the entity a "record" rather than a memory, and offers no differentiation from close siblings like get_memory_context, list_memory_revisions, or search_memories, so an agent cannot reliably pick it out of the list.

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

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

There is no guidance on when to use this tool versus search_memories, list_memories, get_memory_context, or list_memory_revisions. The description states what it does but never when it is the right choice or when another sibling should be used instead.

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?

No annotations are provided, so the description carries the full burden. It implies a read operation, but does not disclose permissions, side effects, error behavior, whether 'active context' changes over time, or how this differs behaviorally from related tools.

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

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

The definition is a single front-loaded sentence with no redundant or filler text. It is appropriately sized for a one-parameter retrieval 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?

Given no annotations, no output schema, and 0% parameter description coverage, the description is too sparse. An agent can infer the general purpose, but lacks enough context about usage, return behavior, and relationship to sibling tools to call it confidently.

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 0%, so the description must compensate for the undocumented session_id parameter. It partially does by indicating the tool operates on 'one conversation', implying session_id identifies that conversation, but it adds no format, validation, or lookup details.

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

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

The description has a clear verb ('Read') and resources ('active context and confirmed placement guidance') scoped to one conversation. It is understandable without the schema, though it does not explicitly distinguish itself from sibling tools such as get_placement_guidance or set_memory_context.

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 no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. The phrase 'for one conversation' implies scope but does not tell an agent when this retrieval is the right choice.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It establishes that this is a read operation and that the guidance is owner-confirmed, but it does not describe permissions, whether the guidance is static or dynamic, return behavior, or how the optional space_id affects results.

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 is efficient and contains no wasted text. However, its extreme brevity contributes to the larger semantic gaps rather than providing useful structure.

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 (one optional parameter, no output schema), but the description is incomplete for correct invocation because it does not explain the space_id parameter or what the guidance response provides. With no annotations and no output schema, more context is needed.

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

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

Schema description coverage is 0% and the description never mentions the optional space_id parameter. An agent cannot infer from the description whether omitting space_id means global guidance or whether specifying it scopes the guidance to a workspace.

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 ('Read') and a specific resource ('owner-confirmed guidance for placing new memories'), so the core purpose is understandable. It does not explicitly differentiate this tool from siblings such as create_memory or move_memory, which limits clarity in tool selection.

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 'for placing new memories' implies the use case, but there is no explicit guidance on when to choose this tool versus alternatives like create_memory or move_memory. 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.

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

No annotations exist, so the description carries the full burden and it only discloses the non-disclosure of the value. It says nothing about what metadata fields are returned, whether a not-found secret errors, or what access/permission is required — notable gaps for a tool with no 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?

A single front-loaded sentence with zero filler. It is efficient, though the brevity trends toward under-specification rather than pure conciseness.

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

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

With no annotations and no output schema, the description should explain what 'metadata' means and how scoping works. It instead leaves the return contents and the space_id parameter completely undocumented.

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% for both parameters, and the description explains neither. Critically, the optional 'space_id' scoping parameter is not mentioned anywhere, so an agent has no way to know it must be supplied when the secret lives outside a default space.

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?

A clear verb ('inspect') plus resource ('one secret') and a scope qualifier ('without revealing its value') that separates it from reveal_secret. It never names the sibling, but an agent can infer the read-only-metadata intent.

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 revealing its value' implies when to choose this over reveal_secret, but no alternative is named and no preconditions (e.g., requires access to the space, errors on missing secret) are stated. Usage is only implied.

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 no annotations, the description carries the full burden of behavioral disclosure. 'Discover' weakly implies a read operation, but it does not state whether authentication or specific permissions are required, whether the call is safe and non-destructive, or what the response shape is. These are material gaps for a discovery endpoint.

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 wasted words. It is appropriately sized, though the opaque term 'GH2 features' reduces communicative value.

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 tool, the description gives a rough inventory of what is discovered, which is minimally adequate. But with no output schema and no annotations, it should clarify what 'GH2 features' and 'permitted spaces' mean and what the agent can expect to receive, so clear gaps remain.

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 to document; the baseline for a zero-parameter schema is 4. The description does not need to compensate for missing schema coverage.

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

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

The description gives a specific verb ('Discover') and lists resources ('permitted spaces, defaults and GH2 features'), so it is not a tautology. However, 'GH2 features' is undefined jargon and 'permitted spaces' is ambiguous, leaving an agent unsure what the tool actually returns. It does not explicitly differentiate itself from the many CRUD siblings.

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 offers no when-to-use guidance, no prerequisites, and no alternatives. 'Discover' implies a read-only inspection call, but the agent is not told whether this should be called at session start, after authentication, or only when searching for capabilities.

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 no annotations and no output schema, the description carries the full disclosure burden yet says nothing about whether the call is read-only, whether it requires auth, whether it can fail/timeout, or what 'health' comprises (latency, dependency status, version). One sentence of mutation-free intent is implied but never confirmed.

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 or redundancy. It is efficient but borders on under-specification rather than being genuinely tight — the brevity comes from omission, not from careful compression.

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?

No output schema exists, so the description should describe the shape of the health response (status field, boolean vs. structured payload, degraded states). For a diagnostic tool whose entire value is the return value, leaving that undefined is a real gap, even given the tool's simplicity.

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 and the schema is empty, so there is no parameter semantics to explain — baseline 4 applies. The description could note that it accepts no arguments, but nothing is missing that an agent would need in order to fill 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?

States a verb ('Check') and a resource ('service health'), so the basic action is identifiable, but 'service' is never defined — it doesn't say whether this covers the memory store, the secrets vault, or the whole backend. No sibling duplicates a health check, so it is minimally distinguishable, but only by elimination.

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

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

There is no statement of when to call this — e.g. before a batch of memory operations, after a suspected outage, or as a connectivity preflight. No exclusions or alternatives are mentioned; the agent must guess at the trigger.

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?

No annotations are provided, so the description carries the full burden. It discloses one meaningful behavioral trait (categories are classification-only and confer no permissions), but says nothing about return shape, ordering, or whether the list is complete or paginated.

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 short sentence, front-loaded with the action and followed by the one caveat that matters. No filler, no 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 zero-parameter list tool with no output schema, the description should say something about what comes back (names, IDs, structure). It covers purpose and a semantic caveat but leaves the return values entirely unspecified.

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 nothing for the description to disambiguate. Baseline 4 applies; the schema is empty and fully consistent with the 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?

States a specific verb and resource ('List categories') plus a semantic clarification that categories classify records rather than grant access. That distinguishes it from access-control concepts, though it doesn't explicitly differentiate it from sibling listing tools.

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

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

The clause 'do not grant access' preempts a likely misreading of what the results mean, which is implicit usage guidance, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling tools.

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

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

With no annotations at all, the description carries the full disclosure burden and largely fails it. It hints that results include versions and ownership and are "permitted" (implying authorization filtering), but never says whether listing is read-only, how pagination behaves by default, or what an empty/unauthorized result looks like.

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 clause with no filler, front-loaded with the verb. It is efficient, though its brevity is partly under-specification rather than disciplined compression.

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 four-parameter, zero-annotation, no-output-schema tool, the description is far too thin. It leaves the agent without the return shapes, default filtering behavior, or space scoping needed to call this correctly in a family of eight memory-listing/search siblings.

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 only 50%: limit and offset are documented in the schema, while space_id and include_archived have no description anywhere. The description does not compensate — it never mentions scoping by space or whether archived memories are excluded by default, which are exactly the choices an agent needs to make.

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?

"List" gives a clear verb, but the resource is described generically as "records" rather than memories, and the phrase "permitted records with versions and ownership" is ambiguous about what is actually returned. Nothing distinguishes it from siblings like search_memories, prefetch_memories, or list_memory_revisions, which an agent could easily confuse it with.

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 offers no guidance on when to use this versus search_memories, prefetch_memories, or list_categories — all of which return related data. There is no statement of prerequisites, scope, or exclusions, so the agent must infer selection from the name alone.

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 no annotations, the description carries the full behavioral burden and delivers almost nothing: no indication that it is read-only, whether results are paginated or ordered, how many revisions are returned, or what "permitted" actually restricts. The only signal, permission-scoped visibility, is cryptic rather than explanatory.

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 short phrase, so it is not bloated, but brevity here is under-specification rather than efficiency. Nothing is front-loaded because there is essentially no content to front-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 required-parameter tool with no annotations and no output schema, the description supplies none of the missing context: not the parameter meaning, not the return shape, not the relationship to restore_memory_revision. It is not sufficient 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?

The schema has one required parameter (memory_id) with 0% description coverage, and the description never mentions it. There is no hint that the call must target a specific memory, leaving the sole input undocumented in both structured and natural-language form.

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?

"Inspect permitted historical snapshots" gestures at a read of revision history but never states the resource (memory revisions) or that it is scoped to a single memory. An agent must infer from the tool name alone that this lists prior versions of a memory, and the sibling restore_memory_revision is never distinguished.

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?

No statement of when to call this versus list_memories, get_memory, or restore_memory_revision, and no prerequisites. Only vague implication that it is for looking at history; the word "permitted" hints at filtering but does not explain it.

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

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

No annotations exist, so the description carries the full burden. It does disclose one genuinely useful trait — that built-in storage returns supported=false — but says nothing about permissions, what a folder record contains, or whether the list is paginated.

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 with the core action front-loaded and zero filler. The second sentence is terse to the point of being cryptic, but it does carry information rather than padding.

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 tool with no output schema, the description is adequate but thin: it never indicates the shape of the returned folder list (names, ids, hierarchy) or what an agent should do when supported=false. The unsupported-backend case is flagged but not resolved.

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 of 4 applies; the schema is empty and the description correctly implies a no-argument call. Nothing in the description contradicts or obscures that.

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 and resource ('List ... vault folders'), which clearly separates it from the mutating sibling create_secret_folder. It does not explicitly name an alternative or state scope (all folders? filtered?), so it stops short of a 5.

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

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

There is no statement of when to call this versus search_secrets, list_categories, or get_secret_metadata. The note about built-in storage is a behavioral caveat rather than usage guidance, leaving the agent to infer the selection criteria.

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 no annotations, the description carries the full behavioral burden. It usefully discloses non-exposure, non-overwrite behavior, user review for differing values, and dry-run previews, but it does not clarify what happens to the source secret, required permissions, failure behavior, or return output.

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 front-loaded with purpose, then moves directly into workflow and safeguards. It is appropriately sized 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 complex migration tool with no annotations, no output schema, and zero schema descriptions, the description covers the core workflow but omits important context such as required version semantics, source-secret lifecycle, and result format. It is helpful but not fully complete.

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

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

Schema coverage is 0%, so the description must compensate for all six parameters. It explains target_id, field, and dry_run, but leaves the required expected_version, id_or_name, and folder_id unexplained.

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

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

The description gives a specific verb and resource: transferring a built-in secret into the vault without exposing its value. It is distinguishable from generic create/update siblings, though it does not explicitly name or contrast 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 an explicit search-first workflow, explains when to pass target_id and field versus when to omit target_id, and states that different values require review and dry_run previews changes. This is strong operational guidance for selecting the right mode.

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 no annotations provided, the description carries the full burden. It does disclose a real behavioral constraint, dual write grants, which the agent could not learn from the schema. It omits, however, whether the move removes access in the source space, what happens on version mismatch, and whether the operation is reversible, all material for a mutation tool.

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, and the permission constraint is attached directly to the action. It is efficient, though the terseness borders on under-specification given three undocumented parameters.

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 three-parameter mutation tool with no annotations, no output schema, and zero schema descriptions, the description supplies only one fact (write grants in both spaces). Nothing covers version-conflict behavior, return values, or failure modes, so an agent cannot safely predict what the call does.

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% for all three parameters, so the description must compensate and largely does not. "Both spaces" weakly hints that space_id is the destination (source inferred elsewhere), but memory_id and expected_version, which implies optimistic concurrency and is critical to invoking correctly, are never explained.

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 has a clear verb ("move") and a scope (ownership transfer between spaces), but the resource (a memory) is only implied by the tool name, not stated in the text. It also doesn't clarify how it differs from near-siblings like update_memory, archive_memory, or migrate_secret, leaving the agent to infer that this is a cross-space relocation rather than a field edit.

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 sentence "requires write grants in both spaces" gives a genuine precondition, which is useful. However, there is no guidance on when to choose this over update_memory or archive_memory, and no mention of when not to use it (e.g. same-space edits, or when only read access exists).

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 no annotations, the description must carry the full behavioral burden, but it only hints at bounded recall and incomplete excerpts. It does not clarify permissions, read-only behavior, pagination/limits beyond schema fields, session effects, or what the returned context looks like.

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?

It is short and front-loads the recall statement, but several clauses are cryptic rather than economical. "Check entity and space" and "bounded active and General context" require inference, so the compactness costs clarity.

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?

A five-parameter recall tool with no annotations, no output schema, and 40% schema coverage needs more disclosure than this. The description omits how results are selected, how session/space affect scope, and what an agent receives back beyond vague "excerpts."

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 40%, and only max_chars and max_memories are documented in the schema; message, space_id, and session_id have no descriptions. The prose mentions checking entity and space but does not explain the message input, space_id semantics, or how session_id scopes recall.

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?

It identifies a recall-style operation over bounded active and General context, so the resource area is visible, but "prefetch" is never plainly defined and the distinction from search_memories/list_memories is only implied. The description gestures at output being excerpts that may be incomplete, but the core purpose remains vague rather than a specific verb-plus-resource statement.

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 actionable routing guidance: check entity and space, search explicitly when recall may be insufficient, and fetch full records by ID when excerpts omit evidence. Those alternatives are named, though it does not state exactly when to choose prefetch versus starting with search_memories.

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?

No annotations are provided, so the description carries the full behavioral burden for a mutation-like operation. It mentions permission gating ('permitted') and concurrency checking, but does not explain what is overwritten, whether a new revision is created, what happens on conflict, or what permissions are required.

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 single sentence is front-loaded and has no wasted words. However, for a three-parameter revision-restoration operation with no annotations or output schema, the extreme brevity leaves it under-specified rather than appropriately 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 absence of annotations, output schema, and schema descriptions, the definition is not complete enough for an agent to call this tool confidently. It omits return behavior, conflict handling, permission requirements, and the meaning of two required parameters.

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 explain the three required parameters. It only indirectly alludes to expected_version through 'concurrent edits'; memory_id and revision_id receive no semantic explanation beyond their titles.

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 and resource: restoring a revision. It implies memory context via the tool name, but it does not distinguish this operation from sibling tools such as list_memory_revisions or update_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?

There is no explicit guidance on when to use this tool versus alternatives, nor any stated prerequisites or exclusions. The phrase 'checking concurrent edits' hints at a conflict-checking scenario but does not route the agent among sibling tools.

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

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

No annotations are provided, so the description carries the full burden. It does signal that this is a sensitive plaintext disclosure gated by authorisation and limited to one field at a time, which is real added context. However it says nothing about audit logging, whether the caller's identity is recorded, what happens on unauthorised access, or latency/secrets-manager behaviour.

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

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

Two short sentences, the purpose verb first, with no filler. It could be tightened slightly ('authorised task' is vague), but it is front-loaded and appropriately sized.

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 sensitive-value reveal with no annotations, no output schema, and 0% schema coverage on three params, the description is thin: it does not explain how the secret is identified (id_or_name naming rules), what space_id does, or what the returned value looks like for non-scalar fields such as SSH keys. Adequate to identify intent, insufficient for confident 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 0%, so the description must compensate. It does explain the domain of the `field` parameter (valid values: username, password, SSH key, notes, custom fields), which is genuinely useful. But `id_or_name` (the required param) and `space_id` are given no semantics, and nothing says whether `field` defaults to a specific field when null.

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 ('reveal') and a scoped resource ('one field' of a secret), and enumerates the field types (username, password, SSH key, notes, custom). This implicitly separates it from get_secret_metadata (metadata vs. actual value) and search_secrets, though it never names those siblings explicitly.

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?

'for an authorised task' hints at a permission precondition and 'Explicitly' hints at an intentional single-field disclosure, but there is no explicit when-to-use vs. when-not, and no routing to get_secret_metadata or search_secrets for the non-revealing 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?

With no annotations present, the description carries the full disclosure burden. It does clarify that broadening only affects reads ("this does not change writes") and that only permitted spaces are covered, but says nothing about result ordering, pagination, or permissions.

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?

Very short and front-loaded, so nothing is wasted on filler. However, phrases like "Search active space" and "Explicitly broaden across permitted spaces" are compressed to the point of ambiguity and would benefit from one clarifying clause.

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?

Six parameters, no annotations, no output schema, and undocumented fields: the description explains only the query strategy and the read-only nature of broadening. An agent still cannot tell what space_id or session_id do or what the results look like.

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 only 17% — just 'limit' is documented — so the description should compensate. It hints at 'broaden' semantics and query phrasing but leaves space_id, max_chars, and session_id entirely unexplained in both schema and 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?

States a specific verb ("Search") scoped to the "active space", which tells an agent this is a scoped retrieval tool rather than a broad listing. It does not distinguish itself from list_memories or prefetch_memories, which are close siblings in the toolset.

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?

Offers tactical query advice ("try shorter terms or synonyms when needed") and a condition for widening scope ("for other contexts"), which is genuine when-to-use guidance. It never names an alternative tool or says when not to search versus list or prefetch.

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 no annotations, the description carries the full behavioral burden. It usefully discloses that no secret values are returned and that provider_name=builtin enables local-only access during an outage, but it omits permissions, result limits, pagination, and ordering behavior.

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

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

Three short sentences, front-loaded with the core purpose. The outage fallback and no-values guarantee are each stated compactly 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 three-parameter tool with no annotations and no output schema, the description is under-specified. It lacks space_id semantics, result limits/pagination, and whether an empty query returns everything, which 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?

Schema description coverage is 0%, so the description must compensate. It loosely maps query to name/folder/website/hostname and gives one special provider_name value, but it never explains space_id and does not clarify query syntax or empty-query 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?

States a specific verb and resource: search global secret metadata, with the searchable fields enumerated (name, folder, website address, hostname). It also clarifies metadata-only scope by saying no values are returned, though it does not explicitly distinguish itself from sibling get_secret_metadata.

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 use for searching secret metadata and gives one explicit operational condition: provider_name=builtin for local-only access during a vault outage. It does not say when to use this instead of get_secret_metadata or reveal_secret, nor does it state 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?

With no annotations, the description carries the full burden, and it does disclose the key risk-limiting trait: the change is confined to a single conversation and does not alter the connection default. However, it says nothing about authorization, idempotency, invalid/missing space handling, or error behavior for a mutation tool.

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 with zero filler, and the scope constraint is front-loaded. It is efficient for the minimum it says, though brevity here borders on under-specification.

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 two-parameter mutator with no annotations and no output schema, the description covers the intent and blast radius but omits what the call returns, what happens on success/failure, and whether the session or space must pre-exist. 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 coverage is 0% and neither parameter has a description. The description's words 'conversation' and 'space' loosely map to session_id and space_id but add no format, ID type, or validity requirements, so the agent must infer both parameters from their names 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?

States a specific verb (change) and a precisely scoped resource (one conversation's active space), and clarifies the boundary versus the connection default. It implicitly distinguishes from the sibling get_memory_context by being the mutating setter, though it never names that sibling.

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 only implied: the 'without changing connection default' clause hints at when this is preferred over a connection-wide change, but there is no explicit when-to-use, when-not, or named alternative 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses optimistic concurrency and conflict recovery, but it omits other important mutation behavior such as partial-update semantics, permissions, and what happens to unspecified fields.

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

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

The description is a single compact sentence with no wasted words and the verb is front-loaded. Its brevity is efficient, though it is arguably too sparse for a nine-parameter mutation 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?

This is a complex mutation tool with nine parameters, no annotations, no output schema, and 0% schema description coverage. The description covers only version-conflict behavior and leaves most of the tool's semantics for the agent to infer.

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% across nine parameters, so the description must compensate heavily. It only indirectly explains expected_version via 'last-read version' and says nothing about memory_id, body, tags, title, summary, metadata, change_reason, or last_verified_at.

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 says 'Update' and adds version/conflict guidance, but it never names the resource being updated or what fields are involved. It relies on the tool name to convey that this updates a memory and does not distinguish itself from siblings such as create_memory or archive_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 an explicit operational guideline: use the last-read version and reread/reconcile after conflicts. However, it does not say when to choose update_memory over alternatives such as create_memory, move_memory, or restore_memory_revision.

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 no annotations, the description carries the full burden and does disclose real behaviour: it is a mutation, it is field-scoped rather than whole-object, it uses optimistic concurrency via the expected version, and it will not silently clobber a conflicting value without authorisation. It still leaves open what happens on version mismatch (error vs. merge) and what permissions are required.

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, both load-bearing, with the scope and the concurrency rule front-loaded. No filler or marketing language.

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

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

For a mutation with no annotations, no output schema, and zero schema description coverage, the description covers intent and conflict policy but omits auth requirements, mismatch behaviour, and id-vs-name resolution. Adequate to attempt the call, not enough to predict its failure modes.

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 effectively explains 'field' and 'expected_version' semantics, but 'id_or_name' (id vs. name resolution) and the null-default behaviour of the optional 'field' param are never addressed.

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 and resource ('Update one explicitly selected secret field') and adds a real constraint: a single field only, using its current metadata version. It is clearly distinct from create_secret or reveal_secret, though it never explicitly names those siblings.

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?

'Using its current metadata version' implies get_secret_metadata must be called first, and the authorisation caveat hints at the conflict path, but neither is stated as an instruction. There is no explicit guidance on when to prefer this over migrate_secret or create_secret.

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