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

With no annotations, the description carries the full burden and does so richly: it details per-outcome confidence deltas (+0.1, +0.15, -0.2 with floor 0.05), archiving, review queuing, and freezing behavior, plus auth constraints for private namespaces and reversal semantics. This is exactly the behavioral context an agent needs before a state-mutating call.

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?

Front-loaded with purpose and usage timing, then structured by outcome. Dense but every clause carries information; there is minor redundancy in the trailing sentence about archiving being reversed.

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 side-effecting tool with no annotations and no output schema, it covers the material behavior an agent needs. It does not describe the response shape or whether feedback can be resubmitted/edited, a small remaining gap.

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

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

Schema description coverage is 0% and the schema declares no enum, yet the description fully enumerates all five valid outcome values with their effects and states that anything else is rejected. It also explains 'agent' semantics (must be your own source agent id, owner rules for private namespaces), compensating for the total 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?

States a specific verb+resource (report feedback on a memory) and names the conceptual function (closes the compounding loop). It is clearly distinct from siblings like memory_write/search/get/link, which are CRUD/query operations rather than outcome reporting.

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

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

Gives clear timing guidance — 'call after actually adopting a memory' — which tells the agent the precondition for invocation. It does not explicitly name when-not to use it or route to alternatives, so it falls just short of the top band.

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 substantial work: it discloses that neighbors are returned by default, that private-namespace reads require the owner's reader id, and that embedded neighbors are filtered to global plus the caller's project. It does not describe return shape, error modes, or whether missing ids fail loudly, leaving some behavioral gaps for a 4-parameter read 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?

The core action and default behavior are front-loaded in the first clause, and the parameter notes follow in order. The longer em-dash sentences and the trailing memory_feedback instruction add real information but make the block denser than it needs to be.

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 output schema and no annotations, the description supplies the permission model, the default neighbor behavior, and the project-scoping rule — enough for an agent to call it correctly in the common case. It stops short of describing the response payload or failure behavior, which a 0%-coverage schema leaves entirely 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%, so the description must compensate and largely does: reader gets meaning plus a required-when condition, project gets meaning plus its filtering effect on neighbors, and include_neighbors is implied by 'included by default'. Only mem_id is left undefined, which is self-evident from the purpose sentence.

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: 'Fetch a memory by id', and immediately narrows scope by noting that one-hop link neighbors are included by default. It never explicitly contrasts with memory_search or memory_link, so an agent gets the gist but must infer the boundary between this and the search sibling on its own.

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 states a real conditional rule ('reader: required when the memory lives in a private agent-<name> namespace') and a follow-up workflow ('After adopting it, call memory_feedback'). What is missing is a negative case — there is no statement of when to prefer memory_search or memory_link 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?

With no annotations, the description carries the full burden, and it does disclose the mutating effect (bidirectional link), the namespace constraint, and the ownership/permission rule. However, it is silent on idempotency, what happens if the link already exists, whether links can be removed, and failure behavior beyond rejection.

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?

Front-loaded with the core action, then constraints in descending order of importance. The '(compounding source #2: association)' aside is internal jargon that interrupts the flow slightly, but the paragraph is otherwise tight and waste-free.

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 unannotated mutation tool with no output schema, the description covers the key operational constraints (namespace, ownership) an agent needs before calling. Missing details on return/error behavior are minor since no output schema exists to lean on.

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 clarifies the agent parameter ('your own source agent id') and ties it to the ownership rule, but id_a and id_b get no explanation beyond their names, leaving two required params essentially undocumented.

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+resource: 'Create a bidirectional link between two memories'. The bidirectionality and the association framing are precise. It does not name a sibling such as memory_feedback to disambiguate, but the purpose is otherwise unmistakable.

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

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

Gives clear conditions and exclusions: both memories must share a namespace, cross-namespace links are rejected, and private 'agent-<name>' namespaces accept links only from the owner. It stops short of comparing against siblings like memory_feedback or memory_write, so it is strong context without explicit alternatives.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses the dual-channel vs lexical fallback, the retrieval {mode, reason} reporting, the fail-closed project scoping rule, the auth requirement (reader) for private namespaces, and that neighbors are attached by default. Nothing about destructive/auth/fallback behavior is left implicit.

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 purpose is front-loaded, but the middle collapses into a dense run of parenthetical clauses (score normalization, namespace resolution, neighbor trimming) that is hard to parse in one pass. Most sentences carry real payload, yet the wall-of-text packaging costs readability.

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, and the description supplies the return shape {'hits', 'count', 'retrieval'} plus per-hit field semantics (similarity, explain, neighbors). For a read tool with seven parameters and no structured docs, this is sufficient to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for six of seven parameters: ns scope/defaults, reader's auth role, project's fail-closed semantics, explain's default-off payload, include_neighbors' one-hop trimming, and the similarity field's meaning. Only top_k goes unexplained, which is minor against the otherwise rich 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?

"Search memories" states a specific verb and resource, and the body makes the retrieval semantics (hybrid lexical/vector with RRF fusion) concrete. It never contrasts itself with the sibling memory_get, so an agent must infer search-vs-fetch-by-id on its own.

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

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

Gives clear conditional guidance: pass ns explicitly to target a single namespace, omit project and only global memories return, reader is required for 'agent-<name>', and attach explain=true only for debugging. It also names memory_feedback as the required follow-up after adopting a hit. What is missing is an explicit statement of when to prefer this over memory_get.

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 does so: content is capped at 262144 characters and longer payloads are rejected with nothing written; expired valid_until memories drop out of search but remain readable via memory_get; project-tagged memories are hidden from searches that don't pass the same project while untagged ones stay global; conflict: true signals a duplicate key and a queued review entry. These are exactly the non-obvious consequences an agent needs before writing.

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?

Front-loads the core action and the three critical parameters, and every clause carries real information — nothing is filler. The cost is a single dense run-on paragraph with heavy semicolon chaining that is harder to scan than a short structured list would be, but no sentence is expendable.

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?

Despite 10 parameters, zero schema description coverage, no annotations, and no output schema, the description covers the return value (stored memory plus conflict flag), the write-time rejection behavior, the visibility model for namespaces and projects, and validity-window semantics. Nothing material is left for the agent to guess.

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 10 parameters, so the description must compensate and it does: it defines ns values ('_shared' or 'agent-<name>'), the meaning of key (stable id for fact/insight/decision, enables conflict review), project's slug grammar and visibility semantics, valid_from/valid_until as ISO YYYY-MM-DD validity windows with their search-exclusion effect, lesson_role's only legal values ('lesson' or 'avoid') plus the mapping of lesson→insight and avoid→decision, and the avoid:/fixes:/contradicts: link prefixes versus free-form strings.

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?

Opens with a specific verb+resource ("Write a memory") and immediately enumerates the type vocabulary (episode|fact|insight|skill|decision), so an agent knows exactly what operation this is. It does not explicitly contrast itself with memory_search/memory_link/memory_get, so sibling differentiation is left to inference rather than stated.

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

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

Gives substantive when-to-use guidance: write only stable facts (preferences, conventions, environment constraints, pitfalls), not session-temporary details; volatile status notes must carry valid_until or stay out; prefer reusing an existing key over a new entry. It also tells the agent to declare its workspace project per host usage rules and pass it on every write/search. No explicit sibling routing (e.g. use memory_link for relations), which keeps it at 4.

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