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

With no annotations, the description carries the entire behavioral burden and does so richly: exact confidence deltas (+0.1 success, +0.15 for first-time cross-agent validation, -0.2 failure with 0.05 floor), freezing and queued review for 'contradiction', immediate archiving for 'obsolete', rejection of any other value, ownership restriction for private 'agent-<name>' namespaces, and archiving being reversed on feedback. This is far beyond what any structured field provides.

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 purpose and the trigger before enumerating outcomes, and every clause carries information not present in the schema. The dense run of parentheticals makes it slightly heavy to scan, but there is little genuine filler to cut.

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 0% schema coverage, the description covers timing, per-outcome behavior, and authorization thoroughly. The one remaining gap is what the caller receives back (returned confidence, review-entry id), though the state changes themselves are disclosed.

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: every meaningful value of 'outcome' is defined with its side effect and the default is noted, and 'agent' is constrained to "your own source agent id" with the private-namespace ownership rule spelled out. Only 'mem_id' is left implicit, which is reasonable for a self-evident identifier.

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 ("Report feedback on a memory with an outcome") and immediately differentiates itself from siblings like memory_write/memory_get by framing feedback as the step after a memory is adopted. The compounding-loop phrasing makes its role in the memory lifecycle unambiguous.

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?

"call after actually adopting a memory" gives a clear trigger condition, and the per-outcome effects tell the agent which outcome applies when. It stops short of explicitly comparing itself to the sibling tools or stating when not to call it, so it is clear context without full routing guidance.

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

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

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 full behavioral burden and does so richly: dual-channel vs lexical-only fallback, the meaning of the 'similarity' field per mode, that confidence/recency/type are only tie-breaks, default-scope semantics, the private-namespace reader requirement, the fail-closed project isolation, neighbor embedding behavior, and the returned shape {'hits': [...]} sorted by score.

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 'Search memories' before the mechanism detail, which is good, but the body is a dense run-on of em-dash clauses mixing score semantics, scope rules, and debugging options without paragraphing or bullets. Nearly every clause carries information, but the packing makes it hard to scan and pushes the actionable usage rules behind implementation trivia.

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 7-parameter search tool with no output schema and no annotations, the description is nearly complete: it documents return shape, ordering, scope defaults, and the downstream memory_feedback step. Only top_k's role (result count) is left implicit, which is minor given its descriptive name and default.

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 and largely does: ns, reader, explain, project, and include_neighbors all get concrete semantics beyond their terse titles, including a hard requirement on reader. The main gap is top_k, which is never mentioned in the description, though its name plus default is fairly self-evident.

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 ('Search memories') and immediately characterizes the mechanism (BM25 + optional BGE vector fused via RRF). It also differentiates from siblings by naming memory_feedback and the adoption/feedback loop, so an agent can place it in the memory toolset without opening schemas.

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

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

Explicit when-to-use guidance for every optional parameter: default scope is '_shared' plus private namespace, pass ns explicitly to narrow to one namespace, omit project to get only global memories (fail-closed), reader REQUIRED when ns is 'agent-<name>', explain for debugging, include_neighbors=False to suppress neighbors. When-not conditions (project omission consequences, reader requirement) are spelled out.

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

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

With no annotations, the description carries the full burden and does well: it discloses conflict handling ("conflict: true means a different version with the same key exists and a review entry was queued"), the post-expiry lifecycle (excluded from search but readable via memory_get), and project-based visibility scoping. It stops short of stating auth requirements, rate limits, or upsert/idempotency semantics for repeat writes.

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 grouped by parameter and lifecycle concern; nearly every sentence adds usable information. It is dense and semicolon-packed, which costs a little readability, but there is no obvious 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 9-parameter mutation tool with no annotations and no output schema, the description covers scope, conflict behavior, temporal validity, and project isolation, plus the return value. The remaining gaps are the undocumented links parameter and content semantics, which are minor but real.

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: it defines type values (episode|fact|insight|skill|decision), ns values ('_shared' or 'agent-<name>'), key semantics (stable id enabling conflict review), valid_from/valid_until format (ISO YYYY-MM-DD) and behavior, and project format (lowercase-slug) and visibility effect. Only links and content are left undocumented beyond their names.

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 memory types, which tells an agent exactly what this tool stores. It does not name a sibling explicitly, so an agent must infer that this is the write path versus memory_search/memory_get, keeping it just below 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?

Gives explicit when-and-when-not guidance: write stable facts (preferences, conventions, constraints, pitfalls) and not session-temporary details, with a stated rationale ("a stale status memory is worse than none"). It also directs the agent to reuse an existing key over creating a new entry and explains the valid_until escape hatch, leaving little to inference.

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