MemAI

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

With annotations only declaring write/idempotent/non-destructive, the description carries real weight: it discloses the durable effect (every read scoped to `domain` returns it), that nothing is moved, the return shape, and the dedup rule that a redundant ancestor path is dropped. This is behavior an agent cannot infer from the annotations.

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

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

The action is front-loaded in the first sentence and the rest elaborates behavior. Slightly prose-y and indirect in places ('the echo is what actually holds'), but every clause contributes information rather than 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?

Though there is no output schema, the description spells out the return shape ({uid, also: [...]}) and the dedup semantics, covering both the call and its result for a simple two-parameter tool.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds semantic depth: `domain` is a path in a tree, and paths already subsumed by the memory's own domain are silently dropped. That redundancy rule is meaning beyond the schema's one-line 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 ('cross-list an existing memory into one more domain path') and immediately distinguishes the semantics from moving ('without moving it -- use the dashboard's re-home for that'). An agent can tell this apart from move_to_project or unfile_domain without opening a schema.

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

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

Gives a concrete when-to-use scenario: a memory filed elsewhere that later proves to belong to a cross-cutting subject. It also carves out when NOT to use it (re-homing/moving) by pointing at the dashboard. No sibling tool is named as an alternative, so it stops short of a 5.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write. The description goes beyond them by disclosing write semantics an agent could not infer: a field over its ceiling is refused and nothing is written, and a near-duplicate in the store returns `similar` with a `similar_hint` to correct/drop/link. This is meaningful behavioral context beyond the annotation set.

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

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

Purpose and the primary sibling distinction are front-loaded in the first two sentences, followed by storage/read-back, sequencing, and return behavior. It is dense and every paragraph carries information, though the prose is leisurely enough that a point or two could be tightened.

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, 10 parameters and a mutating operation, the description carries the needed load: it states the return shape (uid, project, similar), the atomic refusal behavior, and the read-back labels. Combined with 100% schema coverage, an agent has enough to call and interpret it; only return-field detail is left implicit.

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

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

Schema description coverage is 100% and the property descriptions are themselves rich, so the schema does the heavy lifting (baseline 3). The description adds marginal value by mapping stored fields to their read-back labels (TEMPTATION / WHY WRONG / INSTEAD) and naming the type='anti_pattern' discriminator, which clarifies how the required fields behave downstream.

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 ('Record a pitfall: a move that looks right, why it fails, and what to do instead') and explicitly disambiguates from siblings note() and reasoning() by describing what each captures. An agent can tell this apart from the other memory-writing tools without opening a schema.

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 the trigger condition ('For a mistake worth not repeating') and contrasts it with the alternatives: a plain fact belongs in note(), a settled analysis in reasoning(). It also supplies operational guidance — one pitfall per memory, link a second temptation with link_memories() — which is explicit when-to-use and how-to-sequence advice.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and non-idempotency, so this is a write tool with tame safety semantics. The description adds real behavioral value beyond that: it discloses the refusal path, the single-active-checkpoint constraint, the `overdue` age-limit refusal that blocks all writes under a domain, and the archival-by-supersedes behavior. It does not describe the return/refusal payload shape beyond naming the `checkpoints` key.

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, then constraints, then the recovery workflow, so the critical constraint is reachable early. It is long for a description and repeats "call again" and the supersede instruction several times, but nearly every sentence carries a rule an agent needs; the redundancy is mild 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 10-param write tool with no output schema and rich annotations, the description covers purpose, write semantics, refusal handling, alternative tools, and storage type. An agent could execute the refusal-recovery loop correctly from this text alone, which is the main failure mode for this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description nonetheless adds operational meaning the schema does not carry: that these five required fields are consumed in full by every pulse() call, that they should be short and bearings-oriented, that detail belongs in note() cited via [[uid]], and how supersedes is populated from refusal output. That lifts it above the schema-only baseline.

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

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

Opens with a specific verb+resource ("Snapshot current working state") and immediately enumerates the fields that constitute the snapshot. It explicitly distinguishes itself from sibling note() by contrasting bearing-reading checkpoints with timeless archive detail, so an agent can separate the two without opening either schema.

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/when-not routing: one active checkpoint per domain, refusal when one is already filed, and the exact decision tree (done -> forget then retry; not done -> supersede with the uid). It also names the sibling read path (pulse(), get_memory()) and the archive escape hatches, leaving nothing to inference.

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

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

Annotations already establish the read-only, idempotent, non-destructive safety profile, and the description adds real value beyond that: the exclusion rules, the ranking behavior, and the fact that it returns candidates plus a similarity score for human/agent judgment rather than merging. This is exactly the useful context annotations cannot carry.

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?

Purpose is front-loaded in the first line, and each subsequent sentence adds a distinct constraint (exclusions, ranking, non-merge semantics). The parenthetical density adds minor friction but nothing is wasted.

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, but the description compensates by describing the return shape (candidate pairs, similarity score, method field) and the intended follow-up actions. Combined with the strong annotation set, an agent has enough to call and act on the result.

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

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

Schema description coverage is 100%, so the parameters are already documented; the description only adds a modest hint for domain (nested-path behavior) and references the method field on returned pairs (an output detail, not a param). Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource (surface duplicate/contradictory memory pairs) and immediately scopes what it will and will not return: lexical-overlap near-identical text only, with different-words takes explicitly excluded. This distinguishes it from siblings like search, recall, and timeline without requiring schema inspection.

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 negative guidance (same-domain/session checkpoint pairs excluded, checkpoint pairs rank below durable-type pairs) and clarifies it is not an automatic merge, routing the agent to link_memories/edit_memory/forget afterward. It falls short of explicitly naming the alternative tool for other scanning needs, so it lands at 4 rather than 5.

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

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

With annotations already declaring the write/safe/idempotency profile, the description adds real behavior beyond them: 'Returns {"uid": ...}, or {"ok": False, "errors": [...]} with nothing written at all' discloses atomic all-or-nothing semantics, and 'Node positions are computed and stored server-side' explains layout determinism. It stops short of touching auth, quota, or conflict handling, so it is strong but not exhaustive.

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

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

Purpose and the sibling contrast are front-loaded, and the guidance paragraphs are separated cleanly. It is on the long side, though: the aside that a diagram becomes 'the source of truth for its domain instead of one more wall of prose' is rhetorical padding that does not help an agent call the 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?

For an 11-parameter create tool with full schema coverage and no output schema, the description supplies what the schema cannot: the process-vs-fact routing, atomic failure behavior, and server-side layout. Nothing essential is missing, though it leaves session/domain interaction and the meaning of the required 'edges' shape entirely to 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 coverage is 100%, so the baseline is 3; the description adds meaning on top by instructing that 'label' be objective and that reasoning/caveats/history belong in that node's 'note', and by flagging that 'review_after and source_ref matter most for a flow: it describes code, and the code moves.' That is genuine parameter guidance rather than restatement of 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?

Opens with a specific verb and resource: 'Document what a routine does, start to end, as a graph. Stored as type='diagram'.' It then directly names the two nearest siblings (note(), checkpoint()) and the distinct resource each owns, so an agent can separate this from them without opening a schema.

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

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

Explicitly frames the when/when-not: 'For a PROCESS, not a fact: note() records what is true, checkpoint() where the work stands, this one how a routine runs.' That is an explicit alternative-selection rule plus an implied exclusion (do not use this for facts or status), and it points to get_diagram() for the read side.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description reinforces this by disclosing the upsert rule (re-calling with the same endpoints updates the label rather than adding a duplicate edge). It stops short of describing failure behavior, e.g. what happens when the edge or endpoints do not exist, or whether delete requires the label.

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 multi-mode capability front-loaded and the upsert caveat immediately after; no filler. Slightly dense phrasing ('wire ... that wire') but nothing is wasted.

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 output schema, the description covers the three operations and the key idempotency behavior, and annotations carry the safety profile. Gaps are minor: error conditions and the relationship to diagram_link are not covered.

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

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

Schema description coverage is 100%, so every parameter, including the branch-condition semantics of label and the removal semantics of delete, is already documented in the schema. The description adds no syntax, format, or default details beyond that, so the baseline of 3 applies.

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

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

States concrete verbs (wire, relabel, remove) and the resource (two steps of a diagram), covering all three modes of the tool. It does not distinguish itself from the sibling diagram_link, which sounds like it could do something similar, so an agent cannot fully rule siblings in or out from the description alone.

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 choose this over diagram_link, diagram_jump, or diagram_node, and no mention of prerequisites (e.g. that the referenced nodes must already exist). Usage is only implied by the verb list; the alternative tools with adjacent-sounding names are never addressed.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine non-obvious behavior: the jump is stored once and read from both ends, so the return trip already exists and get_diagram reports it on both diagrams. It stops short of describing the delete path or any permission requirements, keeping it from a 5.

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

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

Front-loaded with the verb and resource, then differentiation, use cases, and storage semantics in a logical order. Slightly longer than strictly necessary, but each sentence carries distinct information with no filler.

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

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

For a 6-parameter mutation tool with no output schema, the description covers purpose, sibling differentiation, use cases and the symmetric storage model. It omits deletion semantics and permission needs, which the delete parameter and destructiveHint leave partially addressed but not fully explained.

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

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

Schema description coverage is 100%, so all six parameters are already documented, including uid, node_key, peer_uid, peer_node and delete. The description only implies that the arrival step is optional ('optionally at one of its steps'), adding little beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Continue one step of a flow into ANOTHER flow') with the scope of the target (optionally a specific step). It also explicitly distinguishes itself from the sibling diagram_link by contrasting what each attaches, so an agent can route between them 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?

Names the alternative (diagram_link) and the exact semantic difference, then gives concrete when-to-use scenarios: a routine handing off to a sub-process, an error path owned by another flow, or a variant of the same job. Nothing about selection is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so safety is partly covered; the description adds real value on top by enumerating failure modes (unknown diagram/step/memory, self-link, delete with no such link) and the exact return shape {ok, errors}. It does not spell out permission or reversibility implications of the destructive delete path beyond what the schema states, so it falls short of a 5.

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

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

The action statement is front-loaded, followed by usage context, alternatives, and error/return behavior in logical order. The 'what turns a diagram into an index of its domain' framing is mildly rhetorical but does convey the why, so it mostly earns its place; only slightly longer than needed.

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 5-param mutation tool with no output schema, the description covers purpose, alternatives, error conditions on invalid inputs, and the return envelope, plus the bidirectional visibility via get_memory. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds conceptual meaning the schema lacks: node_key is the step the memory 'actually concerns' and relation_type defaults to 'explains' with replacement semantics on re-linking. These clarify intent beyond the terse schema 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?

Opening sentence gives a specific verb+resource: attach a memory to one specific step of a diagram. It then explicitly differentiates from the nearest siblings (link_memories for whole-diagram edges, diagram_jump for branch continuation), so an agent can route correctly 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?

Names the alternatives and the exact condition that selects each one ('for an edge to the diagram as a whole use link_memories()', 'to say the branch continues in another flow, diagram_jump()'). It also explains the intended granularity: point at the step the memory actually concerns, not the diagram.

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?

Goes beyond the annotations by disclosing partial-update semantics ('only the arguments you pass are touched'), the empty-string clear convention, and the deliberate relaxation of whole-graph validation versus diagram(). It leaves the destructive scope to the schema's delete description rather than restating it, which is acceptable given destructiveHint=true already flags the risk.

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 action, then two short paragraphs that each carry distinct value (patch semantics, validation relaxation). Slightly longer than strictly necessary but no sentence is wasted.

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 all six parameters documented and annotations carrying the safety profile, the description supplies the remaining behavioral context an agent needs (partial updates, clearing, relaxed invariants). No output schema exists, so return-value disclosure is not required.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: merge-style patching and the note="" clear idiom are behaviors the schema alone does not convey. It does not cover the required uid/key semantics beyond what the schema states.

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 opening sentence names a specific verb triad (add/patch/remove) and resource (one step of a diagram), which an agent can act on immediately. It implicitly separates 'step' from edge/link siblings but never names diagram_edge or diagram_link to sharpen the boundary.

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 explains the intended usage pattern (build a flow up across several calls, leaving steps unattached until edges are added) and points at the alternative diagram() for whole-graph enforcement. No explicit 'when not to use' for the edge/link siblings, but the incremental-vs-atomic contrast is genuinely useful.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes further by naming exactly what is destroyed: hand-adjusted positions stored server-side and edited in the admin dashboard. The explanation that positions live in the store rather than the viewer meaningfully explains the persistence model. It still says nothing about return shape, timing, 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?

The action is front-loaded and there is no filler, but the middle sentence about store-vs-viewer persistence is a long clause whose job could be done more briefly. It earns most of its place by justifying the destructive warning.

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 one-parameter mutation with no output schema, the description covers what it does, what it overwrites, and when to reach for it. The only real gap is what the caller gets back or how to confirm the relayout succeeded.

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?

There is a single parameter (uid) and schema description coverage is 100%, so the schema already carries the meaning; the description adds no syntax, format, or identifier-source detail. Baseline 3 applies when structured fields do the work.

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 precise verb+resource: 'Recompute a diagram's stored node positions from scratch.' That is unmistakably different from siblings like get_diagram (read) or diagram_node/diagram_edge (sub-resource editing), so an agent can route correctly without inspecting another schema.

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 a clear usage context -- 'the fix for a diagram dragged into a mess' -- and implicitly cautions that manual adjustments will be lost, which steers the agent away from calling it casually. It stops short of naming when-not-to-use or an alternative tool, so it is not a full 5.

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

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

Goes well beyond the annotations (destructive/non-idempotent), disclosing that the previous version is preserved in edit history, that no-op calls with all fields empty are an error rather than silent success, that empty tag/source_ref values leave stored values alone (clearing is a dashboard edit), and that diagram/task bodies are generated and would be silently overwritten.

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 operation, and the modal/refusal guidance is dense and useful. The rationale sentence about append-only stores is justificatory filler, and three paragraphs is on the long side, so it stops short of maximal 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?

For an 8-parameter mutation tool with no output schema, the description covers modes, partial-field semantics, the all-empty error case, and which memory types are editable. Combined with 100% schema coverage and annotations carrying the safety profile, an agent has everything needed 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 coverage is 100%, so the baseline is 3 and the per-parameter descriptions already carry most meaning. The prose adds one genuinely new rule not in the schema ('passing none of new_content, source_ref, title, tags and goal is an error'), which lifts it slightly above baseline.

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

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

States a specific verb+resource+scope: 'Correct a memory's content or its source reference, keeping the previous version.' It also distinguishes itself from siblings by noting it is not delete (which it contrasts against the append-only store) and not the diagram/task editors, so an agent can route correctly.

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 routing: use mode='append' when a memory gains a fact vs. mode='replace' when it turns out wrong; rewrite a diagram's flow via diagram_node/diagram_edge; rewrite a task's goal with `goal` and its items through task_item(). Both when-to-use and when-not are present.

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

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

Annotations declare a non-destructive, idempotent write; the description goes well beyond that by explaining reversibility (dashboard restore, list_by_domain visibility), the side effect that archiving an open task cancels it while items keep states, and the exact return shapes {ok: True} / {ok: False} for an unknown uid. No contradiction with destructiveHint=false or idempotentHint=true.

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 definition in the first sentence, then routing and side-effect details. Information-dense with minimal waste, though the parenthetical-heavy, multi-clause third sentence is slightly heavier than needed.

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, yet the description supplies the return contract and error case, the reversibility model, and the task-cancellation side effect. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so uid, reason and superseded_by (including the detailed superseded_by vs link_memories guidance) are already documented in the schema. The description adds no parameter-level syntax or format detail beyond that, so the baseline of 3 is appropriate.

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

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

States a specific verb+resource ('Archive a memory') and immediately defines the semantics ('soft delete -- content is kept, just excluded from default search/list'), which cleanly separates it from purge_memory and edit_memory. An agent can distinguish it from every sibling without opening a schema.

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

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

Explicitly names the trigger ('a memory that is wrong, stale or a copy') and routes to alternatives: purge_memory for irreversible deletion only on explicit user request, edit_memory to correct rather than retire. It even names the read path for archived items, list_by_domain(status='archived').

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context on top: both SVG formats write markup to a file and return only a path plus a thin step index 'deliberately too small to draw from', and the returned next_step tells the agent to read and emit the file inline. This is substantive disclosure the annotations cannot carry.

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 action and the two primary formats, then layered detail. The third paragraph is somewhat editorial ('reading the file and emitting it inline is the work, not a cost to avoid'), but each sentence still conveys actionable behavior, so efficiency is good though not maximal.

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, the description shoulders the return contract and does so well: it names the returned path, the thin index, next_step and (via the schema) next_offset paging. An agent has everything needed to call it and act on the result 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 coverage is 100%, but the schema's own param text is thin ('one of the formats above', 'the diagram.'), so the description deliberately carries the meaning of each format value and how it relates to round-tripping and layout fidelity. It adds little on `offset` beyond what the schema says, keeping it just under a 5.

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 ('Read a diagram back') and immediately anchors the two headline formats to their purpose. An agent understands the tool's job without the schema. It does not, however, explicitly distinguish itself from read-oriented siblings like 'diagram' or 'recall', so a 4 rather than 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-to-use guidance per format: svg-interactive 'to SHOW', json 'to reason about it', mermaid 'portable, but re-lays out and DISCARDS the arrangement', and flags json as 'the only round-trippable one'. This is exactly the decision an agent faces when choosing a format, with the trade-off for each stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial non-annotation context: the exact return shape, the meaning of each mode, and crucially the write-side consequence that non-conforming domains are coerced rather than rejected, with a `domain_adjusted` note surfaced on the writer's result.

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 single-sentence purpose, then the return contract, then the usage rule. Every sentence carries information an agent cannot get from the empty schema or the annotations.

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

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

There is no output schema, so the description correctly carries the return shape itself, and with no parameters and full annotation coverage, nothing needed to invoke this correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it appropriately spends no words on parameters.

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 the store's domain-casing policy', and the enumerated return modes make the scope unambiguous. It does not explicitly name the counterpart setter (set_domain_case), so it stops short of full sibling differentiation, but the read-vs-write split is obvious from the verb.

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 an explicit usage directive with rationale: 'Read this before coining a new domain so its casing matches what will be stored.' That tells the agent when to call it, but offers no exclusions or named alternative for changing the policy (set_domain_case).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral detail: that linked data is only counted, that parts are paged via 'next', and that bodies can exceed one response. It stops short of describing error behavior when a uid is missing.

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 purpose in one sentence, then a compact routing sentence. The second sentence is dense with call names but every clause carries usable information; no filler.

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

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

With no output schema, the description must carry return-value semantics, and it does: fields, counts, and how each paginated part is retrieved. The only gap is that the shape of 'fields' and the count keys themselves are left 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: edits_offset switches to edit history with bodies cut to 4000 characters, and content_offset reads a character stretch of the body. This clarifies the mode-switching behavior of the two optional params beyond the schema's own wording.

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 ('Fetch one memory') plus the scope of what is returned ('its fields, and counts of what is linked to it'), which cleanly separates it from sibling list/search tools like recall, search, and list_recent.

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 second sentence explicitly routes the agent to the correct follow-up calls for each paginated part (get_relations() for relations/diagrams, get_diagram() for a graph, task_read() for task items). It does not, however, say when to prefer get_memory over siblings such as search or recall when the uid is unknown.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds that results are paginated and driven by next_offset, which is genuinely useful behavioral context, but that same mechanism is already spelled out in the offset schema description, so the marginal value is modest. No error or empty-result behavior is described.

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 compact sentence that front-loads the core action ('List a memory's links') and ends with the actionable pagination hint. No filler.

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

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

For a simple three-parameter read tool with full schema coverage and annotations covering safety, the description is nearly complete. The one remaining gap is return shape — there is no output schema, and while 'follow next_offset' hints that next_offset appears in the response, the description does not describe the returned link records.

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

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

Schema description coverage is 100% — uid, part (with its enum-like values 'relations'/'diagrams'), and offset are all documented in the schema. The description adds no syntax, format, or defaulting detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: 'List a memory's links'. This is clearly distinguishable from write-oriented siblings like link_memories or get_memory, though it never names an alternative explicitly. The 'one page at a time' scope note sharpens the purpose further.

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

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

Usage is implied by the purpose (use it when you need a memory's links) and the pagination instruction tells the agent how to continue iterating. However, there is no explicit when-to-use/when-not guidance, no statement of prerequisites (e.g., a valid uid), and no pointer to alternatives like search or get_memory for related lookups.

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

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

Annotations already declare the safety profile (not read-only, not destructive, idempotent, closed-world), so the bar is lower. The description adds real value beyond that: the exact error contract ({"ok": False, "errors": [...]}) and the three validation rejections. It's consistent with idempotentHint since a refused duplicate leaves state unchanged. It doesn't describe the success return shape, which is the only notable gap.

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

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

The core action is front-loaded in the first sentence, followed by a short rationale and then the error behavior. The middle paragraph is slightly literary ('This is what splitting a body into several memories costs') and indirect, but it earns its place by justifying when the tool matters.

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 create-link tool with full schema coverage and annotations, the description covers purpose, validation errors, and the differentiator from prose references. There is no output schema, so a brief note on the success response would round it out, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema (including the note field's purpose and the relation_type advice). The description adds conceptual framing of the edge's directionality but no syntax or format detail beyond what the schema provides. Baseline 3 is correct here.

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 ('Create a queryable edge between two memories') and immediately distinguishes it from an adjacent concept: a [[uid]] in prose versus an edge, the latter being what get_relations() and the graph can see. An agent can tell this apart from sibling tools like get_relations or diagram_edge without opening any schema.

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

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

Gives a clear reason to choose this tool over the prose-reference alternative by naming the downstream consumer (get_relations(), the graph). It also enumerates the refusal conditions (unknown uid, self-relation, duplicate edge), which effectively tells the agent what inputs are out of scope. It stops short of naming sibling tools to prefer for other linking needs, so it's not a full when/when-not.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context on top: return shape {'results': [...], 'est_tokens': N}, snippet truncation, the need to call get_memory(uid) for full records, and the meaning of both the per-result and top-level est_tokens. This is exactly the kind of value structured fields don't carry.

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 purpose followed by usage, then return contract — good ordering with no filler sentences. The long parenthetical clauses (est_tokens, truncation) are dense but each earns its place; slightly verbose overall.

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 rich annotation coverage, the description carries the return-format burden and does so fully: result shape, truncation behavior, token estimation, and the follow-up get_memory call. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema (including the subtle domain retry/ambiguity semantics). The description adds no parameter-level meaning beyond that; the task-row 'state'/'progress' note describes return values, not inputs. Baseline 3 applies.

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

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

States a specific verb+resource with scope and ordering: 'List memories for a domain and its subdomains, most recent first.' It also positions itself against a named sibling ('Fallback when search misses'), so an agent can distinguish it from search without opening the schema.

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?

'Fallback when search misses' gives an explicit trigger condition, and the domain parameter routes the agent to list_domains() to discover paths first. It does not spell out the inverse (when search is preferable) or exclusion cases, so it falls short of a full 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial behavioral context beyond them: ordering by most recent activity, the meaning of implicit levels, and the cross-listed vs filed distinction for `also`/`subtree_also`. This is genuinely useful disclosure the structured fields do not carry.

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 one-line purpose before the field glosses, and every sentence carries load (field definitions, cross-listing, casing). It is dense and long, but not padded; the length is justified by the undocumented return shape.

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

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

No output schema exists, so the description takes on explaining the return fields and it does so completely: domain/parent/depth/count/subtree/children/implicit plus cross-listed counts. It also covers the store-wide casing dependency, leaving nothing an agent needs in order to call it correctly.

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

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

Only one parameter (offset) with 100% schema coverage, so the schema does the heavy lifting. The description says nothing extra about offset syntax, but it compensates by thoroughly defining the shape of the returned entries, which is the real semantic payload of this tool.

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 the domain tree') with scope ('every path with its counts and latest activity') and immediately frames it as warm-up discovery. An agent can distinguish it from list_by_domain, list_projects, and also_domain without opening any schema.

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?

Explains the motivating context well: domain is free text that drifts, so this surfaces actual paths instead of guessing, and it routes to get_domain_case() before coining a new domain. It gives clear when-to-use guidance but no explicit exclusion of alternatives or when-not condition.

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 readOnly/idempotent/destructive annotations already covering the safety profile, the description adds genuine behavior: the active project is switched externally in the admin dashboard and a running server follows on its next call, and writes/pulse name the project they touched. It also discloses the entry shape (`name`, `memories`, `active`), which is valuable given there is 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?

The purpose is front-loaded in the first sentence, but the passage is discursive and includes material that doesn't apply to this tool — the case-insensitive name matching note is irrelevant here since list_projects takes no project-name parameter, and the SQLite-file explanation is tangential. Several sentences do not earn their place for a one-parameter list call.

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

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

For a read-only listing tool with no output schema, the description compensates well by describing the returned entry fields and the meaning of `active`. The one gap is that pagination (offset/next_offset) is never mentioned in prose, though the schema covers it.

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

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

Schema coverage is 100% and the single `offset` parameter is already documented in the schema (including the `next_offset` continuation note). The description adds nothing about pagination, so the schema does the entire job. Baseline 3 is appropriate.

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

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

The description clearly identifies the resource (the projects in this home) and its central purpose (showing which project every call reads/writes), and explains what a project actually is. It stops short of a verb-led statement like 'list,' but no sibling tool enumerates projects, so an agent can still place it correctly.

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 implies the use case (discovering the active project and the available projects) but never states explicitly when to call this versus alternatives such as list_domains, nor any exclusions. The relevance of the active project is explained, which is useful contextual guidance, but usage is left to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so safety is covered. The description adds genuinely non-obvious behavior: results are snippet-truncated, per-result est_tokens estimates the cost of the full record, and the top-level est_tokens is the sum -- context the annotations and schema do not carry.

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 purpose is front-loaded in the first sentence, and the second sentence is dense but justified because it explains the return shape and token semantics that have no output schema to carry them. Slightly long but no empty sentences.

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, the description usefully documents the return envelope and token-cost semantics, and it points to get_memory for full records. It is complete enough to call correctly, though it omits pagination behavior (next_offset) beyond what the schema hints at and does not clarify sibling selection.

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

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

Schema description coverage is 100%, so the schema already explains type, limit, domain, offset, and subtree in detail. The description only adds 'optionally filtered by type/domain', which is weaker than the schema text itself, so it does not meaningfully enrich parameter meaning beyond the baseline.

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

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

States a specific verb and resource ('List the most recent active memories') plus a scope qualifier (recent/active) and optional filters. It is clear what the tool returns, though it does not explicitly contrast itself with close siblings like search, recall, or timeline.

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?

Provides one useful downstream pointer -- call get_memory(uid) for the full record because results are snippet-truncated -- which tells the agent how to follow up. However it gives no guidance on when to choose this over 'search', 'recall', 'timeline', or 'list_by_domain', so the core selection decision is left implicit.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond: it explains the copy-then-verify-then-purge sequencing, what gets dropped on crossing the slice boundary (relations, diagram links, jumps, superseded_by marks, [[uid]] references), that conflicts/unknown/outside items are reported, and that the purge is irreversible short of the backup. This is rich behavioral context annotations alone cannot convey.

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

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

Two well-structured sentences that front-load the core action and then disclose the staging behavior. Slightly dense but every clause carries weight; no filler.

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

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

For a destructive 5-param move tool with no output schema, the description covers the lifecycle (move, verify, purge, backup) and the drop semantics, and it points to list_projects for target discovery via the schema. It stops short of describing the backup location/format or what 'checked there' concretely validates, leaving a small 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 coverage is 100%, so each parameter already carries its own description. The description adds framing (the dry_run workflow and the meaning of the report) but doesn't enrich individual field semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

Specific verb ('carry', 'remove') plus resource ('memories') plus explicit source/target scoping ('from the active project into another one'). Clearly distinguished from siblings like forget, purge_memory, and list_projects, which don't move memories across projects.

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?

Establishes a clear workflow: dry_run defaults to true, read the report, then call again with dry_run=False. This implicitly tells the agent when to proceed vs. pause. However, it does not name alternative siblings (e.g., why not forget + note) or state exclusions, so it falls short of 5.

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

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

Annotations already declare readOnly/idempotent/destructive=false, but the description adds substantial non-obvious behavior: the exact semantics of 'pending', that 'overdue' appears only when non-empty and carries an alert to relay, and critically that 'memai refuses new writes under each until it is settled' — a side effect an agent cannot get from the annotations or 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?

Front-loaded with the core purpose and the primary return shape, then the typed variant, then edge cases (pending, overdue). It is dense and long, but the telegraphic JSON-shape notation keeps it information-dense rather than padded; only a small amount of the later prose could be trimmed.

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?

There is no output schema, so the description carries the full burden of describing returns — and it does so field by field (categories, count, type, total, items, next_offset, pinned, overdue). For a zero-required-parameter query tool, nothing an agent needs to call it or interpret results is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the empty-type behavior and the domain/pin scoping rules, but does not add syntax or format detail beyond what the schema already documents for each parameter.

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

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

The description states a specific scope and resource: 'What is still open in a scope: counts per category, or one category's headers', and lays out the exact response shapes for both modes. It is clear what the tool returns, but it never names or distinguishes itself from plausible siblings like list_recent, list_by_domain, timeline or search, so an agent must infer the boundary 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?

Usage is implied rather than stated: 'Open a header with get_memory(uid)' gives the follow-up step, and 'Every pin listed is read with get_memory(uid) before acting' prescribes behavior. However there is no explicit when-to-use-this vs when-to-use list_recent/search/recall, and no exclusion 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description adds the useful trait "timeless knowledge -- retrieved by relevance, not recency," which explains how it will resurface. It does not disclose that repeat saves create separate memories (non-idempotent) or anything about the write's side effects, so with annotations carrying the safety profile this is a moderate add.

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 purpose and the type marker before the retrieval guidance. There is no padding, though the retrieval sentence could be tightened slightly.

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, but the tool is a write operation whose result is well understood, and all 8 parameters are fully documented in the schema. The description covers purpose, storage type and retrieval path, leaving only the non-idempotent write behavior unstated.

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

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

Schema description coverage is 100% and each of the 8 parameters has a rich, self-contained description, so the baseline is 3. The description adds only the implicit type='note' value, which corresponds to no actual parameter, so it does not extend parameter meaning beyond 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 specific verb+resource ("Save a general long-term memory (fact, decision, finding)") and pins the stored type as type='note', which separates it from type-specific siblings like task_note and anti_pattern. It is clear, but it never explicitly contrasts itself against the save-side siblings (checkpoint, reasoning, anti_pattern), so it stops 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?

Gives clear retrieval context and names the alternatives for reading it back (recall(), search(type='note'), must_read(type='note')), so an agent knows the round-trip. It does not say when to prefer note over other save tools, so the when-to-write guidance is implied rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description still adds real context: what each run carries (total/pending/applied/rejected counts, note, safety-backup path once the first apply happened) and the human-in-the-loop design ('the agent proposes, the human disposes').

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?

Purpose is front-loaded in the first sentence, followed by the workflow context and return-content summary. Every sentence carries information; nothing is filler or restated from the schema.

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

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

With no output schema, the description compensates by enumerating the fields each run returns (counts, note, backup path) and by clarifying the workflow position and human-approval boundary. Nothing an agent needs to call this correctly is missing.

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

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

Only one optional parameter (offset) with 100% schema description coverage, so the schema already documents its meaning and the next_offset paging contract. The description adds no parameter-level detail beyond that, making the baseline 3 correct.

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 ('List optimization runs with their review progress') and immediately differentiates from the sibling by calling itself the 'Read-only companion to optimize_stage'. An agent can distinguish it from optimize_scan/optimize_stage/optimize_status 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?

Gives the explicit triggering condition ('after staging, use this to see whether the user has applied/rejected your suggestions') and names the sibling (optimize_stage) whose output it follows up on. It also states the boundary that applying/rejecting stays in the dashboard, so the agent knows what NOT to attempt.

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

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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial operational detail beyond them: the listing is deliberately slim to fit one response, pages end early at an internal size budget, and the `truncated`/`relations_truncated` flags define exact recovery behavior. It also explains output semantics (due, source_ref, anchors) and warns that destructive changes are rejected without verification.

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 purpose and next-step routing are front-loaded in the first two sentences, and the paragraph blocks (suspect signals, output shape, verification rule) are logically ordered. It is longer than strictly needed for a 7-param scan and some guidance bleeds into downstream propose behavior, but every section carries usable information.

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

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

With no output schema, the description carries the full burden and does so: it describes the return shape (slim listing, per-memory anchors, due, source_ref), the stats aggregates (by_domain, domains, never_recalled), and pagination/truncation recovery. Nothing an agent needs to call and interpret the scan is missing.

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

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

Schema description coverage is 100%, so all seven parameters (full, type, limit, since, domain, offset, include_archived) are already documented in the schema. The description adds only incremental meaning for offset ('after a truncated page, offset + count'); it does not explain full, since, or domain behavior beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb (dump/scan) and resource (the memory corpus) and frames it as 'Step 1 of the optimize my memories workflow', which distinguishes it cleanly from siblings like search, list_recent, or list_by_domain. An agent can tell this is the bulk-scan entry point for curation without opening the schema.

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 workflow routing: 'Read it, then stage what you decided with optimize_stage' names the follow-up tool, and 'get_relations(uid) lists them all' names the alternative for truncated relations. It also gives explicit when-NOT guidance ('do not propose archiving something because it is unread') with the reasoning, so an agent won't misuse the recalls signal.

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?

Adds substantial behavior beyond the annotations: staging is non-committal because the user applies or rejects in the dashboard, which backs up before the first apply and can undo any change — this explains the destructiveHint=false despite destructive kinds being stageable. It also discloses partial-failure semantics (invalid suggestions skipped, reported in `errors`, capped to one page with `errors_total` counting the rest) and the verified-required rule for destructive kinds.

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 purpose, then workflow position, then the non-application guarantee, then error handling — a logical order with no filler. It is dense and slightly long for a two-parameter tool, but every sentence carries information an agent needs.

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, the description supplies the return shape ({run_id, staged, errors}) and the truncated-error accounting. Combined with the staging/undo guarantee and the workflow position, nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already carries the full parameter burden, including the kind/payload matrix and the `verified` requirement for destructive kinds. The description's own parameter-adjacent content concerns return fields (`errors`, `errors_total`), not new input semantics, so baseline 3 applies.

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

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

States a specific verb (stage) and resource (a batch of curation suggestions) plus the destination (human review in the dashboard). It also positions itself in the optimize workflow, which cleanly separates it from optimize_scan, optimize_runs and optimize_status among the 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?

Explicitly says it is 'Step 2 of the "optimize my memories" workflow' and that nothing is applied here, so the agent knows when this tool belongs in a sequence. It never names the prerequisite sibling (e.g. optimize_scan) or states an explicit exclusion, so it stops short of a full when/when-not map.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the 'Read-only' line is largely redundant. The description earns credit instead by disclosing the return shape (run header plus per-suggestion kind, target_uid, payload, rationale, verified, status, decided_at) and the status vocabulary, which is genuinely useful given there is 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?

Purpose is front-loaded in one line, then a short read-only note and the payoff. The field enumeration is a long clause but it substitutes for a missing output schema, so it earns its place 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?

With no output schema, the description does the heavy lifting by naming the returned fields and status values, and the schema covers pagination. Slightly incomplete in that the description never mentions paging, but nothing needed to call it correctly is absent.

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

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

Schema description coverage is 100%: run_id and offset are both documented in the schema, including pagination via next_offset. The description adds no extra meaning about either parameter, so baseline 3 applies.

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

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

States a specific verb and resource ('Inspect one optimization run') plus the scope ('every suggestion and its decision'), which cleanly separates it from optimize_runs (lists runs) and optimize_stage (produces runs). An agent can pick this tool without opening the schema.

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

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

Gives concrete reasons to call it: tell which proposals landed, follow up on rejected ones, build on applied ones later. It does not state explicit when-not conditions, but the 'one run' scope implies alternatives already cover listing and staging.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: checkpoint selection is by created_at DESC 'never by similarity' with the rationale, relations are attached to avoid a get_relations call, est_tokens is disclosed, and truncation behavior is stated ('A long checkpoint is cut (`next` names the rest)'). Conditional fields (overdue, scope.stale, scope.also) and their presence rules are disclosed.

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

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

Front-loaded with a one-line summary, then organized field-by-field. It is long for a 2-param tool, but most sentences earn their place by explaining non-obvious return semantics. Minor redundancy in the repeated 'present only when non-zero' clauses keeps it from a 5.

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, the description carries the full burden and delivers: it enumerates the response keys (project, latest_checkpoint, must_read, pinned, read_next, scope, overdue) and explains each. An agent has everything needed to interpret the return value without a 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 100%, so the schema already documents `domain` (path resolution, scope.paths, ambiguity) and `offset` (subdomain paging). The prose adds context on how scope behaves but doesn't extend the parameter contract beyond the schema. Baseline 3 applies where the schema does the heavy lifting.

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

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

Opens with a specific verb+resource+scope: 'Session warm-up: the latest checkpoint, what is pending, and what to read next.' It explicitly differentiates from siblings, noting 'A pulse lists no memories besides the checkpoint; must_read(domain, type=...) lists headers and get_memory(uid) opens one.' An agent can distinguish it from search, must_read, and get_memory without opening a schema.

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 and routing to alternatives: 'Read them as the drill-down plan: search(query, domain=...) or list_by_domain(domain, type=..., limit=...)'. It also names the follow-up tool ('optimize_scan lists which ones') and clarifies read_next sequencing. Nothing about tool selection is left to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds genuine value beyond that: the destruction scope (edit history and relations), irreversibility, and the contrast with forget()'s reversible archive model. It does not surface the confirm_phrase user-typing guard, which is a meaningful behavioral requirement, so it stops short of 5.

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

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

Two short sentences, front-loaded with the PERMANENTLY/irreversible warning, then the routing rule. Every clause earns its place and there is no filler.

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

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

For a destructive two-parameter tool with full annotations and full schema coverage, the description supplies the critical context: what is destroyed, that it is irreversible, and when to prefer the reversible alternative. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so both parameters (uid and confirm_phrase) are fully documented in the schema, including the exact confirm_phrase construction rule. The description adds no parameter-level detail beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('PERMANENTLY delete a memory') and immediately scopes what is removed ('+ its edit history + relations'). It explicitly distinguishes itself from the sibling forget(), so an agent can route correctly without opening either schema.

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 an explicit when-to-use rule: prefer forget() 'unless the user explicitly asked to permanently remove data'. It names the alternative and the exact condition that selects this tool over it, leaving nothing to inference.

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

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

Annotations only declare the write/non-idempotent profile. The description adds genuinely new behavior: the record is stored as type='reasoning' and retrievable by filtering search/list_* on that type, plus the one-analysis-per-memory cardinality constraint. It does not cover dedup or overwrite behavior, so it stops short of full disclosure.

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 definition, then two tight sentences covering the note() contrast, storage/retrieval, and cardinality. No filler; every sentence changes how an agent would call the 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?

For a 6-required-parameter write tool with no output schema, the description covers purpose, sibling disambiguation, storage type, retrieval path, and granularity. It omits whether re-recording similar content is deduped or overwritten, a minor gap for an otherwise complete definition.

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

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

Schema description coverage is 100% with 12 richly documented parameters (hypothesis, result, revised_belief, review_after, tags, domain, etc.), so the schema already carries parameter meaning. The description adds the type='reasoning' retrieval hint but no field-level semantics, matching the baseline-3 rule for high 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?

States a specific verb and resource ('Record an analysis worth keeping: what was thought, and what it settled'), and immediately distinguishes itself from the closest sibling by naming note() as the fact-taker. An agent can tell reasoning apart from note/anti_pattern/checkpoint without opening any schema.

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

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

Explicitly routes the agent: use this for the PROCESS, note() for the fact produced, and it states a granularity rule ('ONE analysis per memory; a second hypothesis is its own reasoning()'). It lacks exclusions against other memory-writing siblings (anti_pattern, checkpoint), so it is clear context without full alternative coverage.

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

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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), yet the description adds substantial behavioral context: the return shape, snippet truncation, the need to call get_memory(uid) for full records, and what est_tokens means at both result and top level. This is real disclosure beyond structured data, with only a minor reliance on search() to explain succeeded_by/collapsed.

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 purpose and routing, and every paragraph carries information. It is slightly longer than necessary, with some decorative phrasing (the quoted 'bring back what I noted'), which keeps it short of a 5.

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 having no output schema, the description explains the return payload, the truncation model, and the follow-up call needed for full records. Combined with complete parameter coverage and clear safety annotations, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so query, limit, offset, and domain are already documented in the schema. The description restates relevance ranking but adds no new parameter-level syntax or format detail, making the baseline 3 appropriate.

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

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

States a specific verb (recall), resource (long-term notes), and mechanism (BM25 relevance-ranked search scoped to type='note'). It explicitly differentiates itself from search(type='note') and must_read(type='note'), so an agent can route correctly without opening a schema.

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-to-use guidance (timeless facts/rules/decisions wanted by relevance) and names the alternatives with their conditions: search(type='note') as the equivalent path and must_read(type='note') for the newest entries. Nothing is left to inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses that snippets are truncated and est_tokens estimates the full-record cost, explains succeeded_by and collapsed annotations, and details that confidence='contradicted' rows sort last but still return. None of this contradicts the annotations; it materially enriches them.

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 and return format are front-loaded and the result-annotation semantics are necessary given there is no output schema. It runs long (~350 words) with a few discursively framed sentences about why contradicted memories deserve a slot and how diagrams rank, but almost every sentence carries usable behavioral information.

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

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

With no output schema, the description carries the full burden of explaining the return value, and it does: results array, est_tokens at both levels, snippet truncation, match_source, fts_rank, succeeded_by, collapsed, and ranking order. Nothing an agent needs to interpret or act on results is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it says the search only widens the candidate set and that the agent must judge candidates, and it links `limit` to the collapsed-duplicate behavior. It adds modest value on top of an already verbose schema rather than fully re-explaining syntax.

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

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

States a specific verb and resource with implementation detail: 'Keyword search over memory content+tags+domain: FTS5 BM25.' It also distinguishes itself from siblings by naming recall() explicitly and clarifying that recall() is just search(type='note') and never surfaces diagrams. An agent can route between search, recall, list_recent and list_by_domain 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 is present throughout: call get_memory(uid) when the truncated snippet is insufficient, raise `limit` to see collapsed duplicates, and use recall() specifically to recall note()'d knowledge while using search() to sweep diagrams. It also states the default scope ('Only active memories by default'), so the agent knows what is excluded and how to widen.

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

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

Annotations already declare idempotent, non-destructive and non-open-world, and the description goes well beyond them: contr adicted memories sort last in search, are excluded from must_read()/pulse() outputs, remain readable, and unverified vs confirmed rank alike. It also documents the return shapes and the unknown-uid failure mode. Slight markdown is the somewhat ambiguous 'it refuses nothing' line.

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?

Purpose and value set are front-loaded in the first clause, followed by consequences and alternatives. The middle paragraph about confidence_reminder on 'any memai tool' is useful but sits outside this tool's direct scope and lengthens the definition.

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, yet the description supplies the return contract ({ok: True}/{ok: False}/error). For a two-parameter, idempotent state-setter with full annotation coverage, nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and both schema descriptions already name the parameters and the value set, so the baseline is 3. The description's added meaning for 'confidence' (the ranking/exclusion consequence of each value) is behavioral rather than syntactic, and adds nothing about uid beyond what the schema states.

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 ('Set a memory's confidence') and enumerates the exact value set. It also names the sibling boundaries explicitly — edit_memory() for text changes, forget() for retirement — so an agent can place it immediately among the 40+ 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?

Gives the trigger condition precisely: 'Call it once evidence settles a claim: the code, a run or a source checked against the memory.' It also routes to the two adjacent alternatives with their own conditions, plus guidance tied to the confidence_reminder signal, which is explicit when-to-act context.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the forward-only effect on future writes, the pre-merge collision preview in the dashboard path, and the return shape {"mode": ...}.

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

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

Three tight sentences with the scope constraint front-loaded and no filler. There is mild redundancy between 'for every domain written from now on' and 'This only governs new writes,' but nothing is padded.

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 one-parameter, non-destructive, idempotent setter with rich annotations, the description covers the forward-only semantics, the alternative path for existing data, and the return value despite no output schema. An agent has everything needed 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 coverage is 100% and the schema itself enumerates 'preserve', 'lower', and 'upper' with their effects, so the description is not required to document mode. It adds no syntax or edge-case meaning beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource — setting the store's domain-casing policy — and scopes it precisely to 'every domain written from now on.' It distinguishes this from the retrospective normalization path, though it never names its read-side sibling get_domain_case, leaving that pairing to inference.

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

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

Explicitly bounds when this applies ('only governs new writes') and routes the agent elsewhere for the excluded case ('to bring already-stored domains into line, run the "Normalize domains" action in the admin dashboard'). That is a complete when/when-not with a named alternative.

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

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

Annotations already cover the write/non-destructive/non-idempotent profile, and the description adds real behavior: storage as type='task', self-archiving once every item is done or dropped, and the [[#id]] citation convention with its label rules. It stops short of describing permissions, limits, or failure modes, but the lifecycle disclosure is substantive context the annotations do not provide.

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

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

Front-loads the definition, then the sibling routing, then the citation convention, with no filler sentences. Some phrasing ('To a person, name it item n of its task') is dense and slightly opaque, keeping it out of the top band.

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?

All 7 parameters are fully documented and the description supplies the lifecycle, storage type, and cross-tool workflow for a write tool with no output schema. Little is missing for an agent to invoke it correctly; return-shape detail is conveyed only briefly ('{id, n}').

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

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

Schema description coverage is 100%, so the per-parameter semantics are already carried by the schema and the baseline is 3. The description adds the cross-reference grammar ([[#id]] reads back as current number and label, labels never carry one) that the schema does not state, giving it genuine added value.

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 and resource — 'Open a task: a goal and a checklist' — and immediately differentiates itself from the task_item/task_add/task_comment siblings by naming what each one does. An agent can tell this is the creation entry point of the task family without opening any schema.

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

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

Explicitly routes follow-up work: task_item() to work it, task_add() to grow it, task_comment() to discuss it, must_read() to list the open ones. It lacks a comparative statement about when to open a task versus a note or checkpoint, so it is clear context rather than full when/when-not guidance.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), so the description needn't restate them. It adds genuinely non-obvious behavior the annotations don't: appending to a closed task silently reopens it, and the exact return shape. It doesn't discuss permissions or failure modes, keeping it just short of a 5.

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

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

Front-loads the core action and side effect in the first sentence, then layers routing and format rules. Every clause carries content, though the terse, aphoristic phrasing ("a label -- a title, an item's text -- never carries one") is denser than it needs to be for an agent to parse quickly.

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?

There is no output schema, so the description correctly supplies the return fields (uid, items, progress, task_state, archived) and the item shape. Combined with the reopen side effect and alternative routing, an agent has what it needs to call this correctly; only auth/permission prerequisites are unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above that by explaining a meaningful content constraint on the items parameter — that free text may cite another item only via [[#id]], that a label never carries such a reference, and how to refer to a person by item number. That is real semantics the schema's terse "one item per line" does not carry.

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 ("Append items to a task"), plus the exact input granularity (one per line). It also, in the same breath, names what it is not (task_item for existing items, task_note for detail), so an agent can separate it from the sibling task_* tools without opening a schema.

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 the precise selection condition ("For work the checklist is missing") and explicitly routes the agent to the correct alternatives with their own conditions: task_item() to move/comment on an existing item, task_note() to add detail. This is explicit when-to-use plus named alternatives, not inference.

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

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

Annotations already declare a non-destructive, non-idempotent write (readOnlyHint=false). The description adds real behaviour beyond that: a comment never edits task content, free text only cites other items via [[#id]], and labels never carry a citation. It does not state permanence/deletion or auth requirements, so it stops short of a 5.

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

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

Front-loaded with the core action, then structured into distinguishable clauses for alternatives, citation syntax, and return shape. Some phrasing is ornate ('reads back as its current number and label') but no sentence is purely decorative.

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 compensates by naming the return shape ({"uid", "comment_id"}, plus `item` and `n` on an item). Combined with the sibling routing and citation rules, an agent has what it needs; only permission/error behaviour is unstated.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value the schema does not: `item` names an item's id (default 0 comments on the task), and `body` supports the [[#id]] citation form which reads back as the item's current number and label.

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?

Opening sentence states a specific verb and resource ('Comment on a task, or on one of its items'), and immediately differentiates from siblings by naming task_note() and task_item()'s `comment` as the alternatives for adjacent behaviour. An agent can place this tool without opening the schema.

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 contrastive guidance: a comment is for rationale the checklist cannot carry, whereas item briefs/shared rules belong in task_note(), and comments accompanying a state change belong in task_item()'s `comment`. That is a true when/when-not/alternative map.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, but the description adds substantial extra behavior: closing the last open item archives the task and reopening reopens it; delete removes comments, links and note attachments and leaves DEPENDS ON referrers marked deleted; an unknown uid refuses the whole call with nothing written. This atomicity and side-effect disclosure goes well beyond the structured hints.

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 verb and resource, then the calling contract, then the return shape and referencing rule. The prose is idiosyncratic ('a label -- a title, an item's text -- never carries one') and slightly verbose in places, but every paragraph carries distinct 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 7-parameter mutation tool with no output schema, the description covers the key gaps: which parameters coexist, delete side effects, task archiving/reopening, atomic failure on unknown uid, and the return contents ('the item's number n and the task's title'). Little an agent needs is missing, though delete-only exclusivity could be stated more sharply.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema for the free-text fields: cross-item references must be written as [[#id]] and read back as a number and label, which no schema entry states. It also reinforces the 'all-or-nothing' coupling of the optional parameters.

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 pair (update/delete) and a precisely-scoped resource (one item of a task), enumerating the touchable fields (text, state, comment, related memories). An agent can place it apart from task_comment, task_note and task_add by the 'one item' scope, though it never names those siblings as alternatives.

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?

Explains the calling contract ('Give at least one of text, state, comment and related, or delete. They apply together, or not at all'), which is real operational guidance. However it offers no explicit when-to-use-this-vs-alternatives routing against siblings like task_comment or task_note, which overlap with the 'comment' field.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and non-read-only, so the safety profile is partly covered. The description adds real context ('only task_read() returns it', body 'errors beside a brief field'), but it never discloses the destructive/deletion behavior implied by the delete parameter.

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 prose is dense and poetic rather than front-loaded with the tool's action; the opening sentence is a definition, not a verb. Most sentences carry substantive information (labels, [[#id]], body free-text rule), so it is not padded, but the cryptic phrasing 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?

For a 13-parameter mutation tool with no output schema, the description explains note structure and read-back format but leaves the create/edit/delete operations to the schema and never warns that deletion is destructive. It is adequate but not fully self-contained given the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by adding semantics not in the schema: read-back labels (GOAL:/CONTEXT:/STEPS:/PITFALLS:/DONE WHEN:/DEPENDS ON:/EXTRA INFO:), the [[#id]] citation rule, and how labels never carry an id. These clarify how field values are interpreted and echoed back.

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 defines what a note is ('A note a task owns: an item's brief, a rule its items share') but never states the tool's action verb (create/edit/delete), which is only recoverable from the schema's note_id/delete fields. It does differentiate the resource by noting only task_read() returns it, but the core purpose is conceptual rather than operational.

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 line 'Not a memory: only task_read() returns it' gives some routing context away from the memory tools, and the required brief fields imply when a structured brief applies. However, there is no explicit when-to-use vs alternatives guidance against siblings like task_comment, note, or task_add.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description usefully adds the pagination loop behavior, but says nothing about error handling, size limits, or what a page looks like when the collection is empty.

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, zero filler, with the core action front-loaded ahead of the pagination rule. Every sentence earns its place.

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

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

The schema fully covers the non-trivial part/item relationship and annotations cover safety, so the description does not need to re-explain those. What is missing is routing guidance among the numerous task_* siblings, leaving the agent to guess which task tool to 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 100%, so all four parameters (uid, item, part, offset) are fully documented in the schema itself. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Read one collection of a task") plus the pagination unit ("one page at a time"). It is clear what the tool does, but it does not explicitly differentiate itself from the many sibling task_* tools (task, task_item, task_note, task_comment).

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 instruction "Follow `next_offset` until it is absent" gives real pagination usage guidance, but there is no statement of when to reach for this tool versus task, task_item, or task_note. Usage is implied rather than scoped.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial non-structured behavior: neighbours are chosen by time alone regardless of term overlap, uid beats query, the response echoes `anchored_by` and the full anchor record, neither list contains the anchor, domain/type narrow the neighbourhood rather than the anchor, and archived records are excluded.

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 purpose, then escalation to mechanics, then return shape, then the follow-up tool. Dense and well-organized, though the stylized phrasing ('reads straight down the clock') adds a little flourish that a stricter tool description wouldn't need.

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, the description carries the full return contract: the exact object shape ({anchored_by, anchor, before, after}), list ordering (oldest first), anchor exclusion, and snippet truncation with `est_tokens`. Nothing needed to invoke or interpret the result is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond it: the uid-vs-query precedence rule, and the important clarification that `domain` and `type` constrain the neighbourhood and not the anchor. `before`/`after` counts and ordering intent are also reinforced in prose.

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 opening line states a specific operation on a specific resource ('what else was being written around one memory, in creation order') and immediately distinguishes it from search: 'not what mentions this record, but what was being written when it was.' An agent can separate this from search, list_recent, and get_relations without opening a schema.

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 names the alternative ('the question search cannot ask') and the condition that selects this tool over it, then states the anchor-selection rule ('One of uid or query is required; give both and uid wins'). It even routes the agent onward for full content via get_memory(uid).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely non-derivable context: what is destroyed is only the cross-listing ('Does not touch where it is filed'), which annotations cannot convey, plus the response shape of what remains.

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 action, then the scope constraint, then the return contract. Zero filler and nothing redundant with the schema or annotations.

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

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

No output schema exists, and the description compensates by stating the return payload. Safety/idempotency are covered by annotations. Minor gap: no mention of error behavior when the cross-listing does not exist or is a duplicate, which matters for an idempotent destroyer.

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

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

Schema description coverage is 100%, so the schema already carries full parameter meaning, including the exact-match/scope nuance for 'domain'. The description adds no parameter-level detail beyond the schema; the return-shape sentence is about output, not inputs. Baseline 3 applies.

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

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

Specific verb ('Drop') plus a precise resource ('one of a memory's cross-listings'), and the second sentence scopes it against the related operations (filing location, move/delete) by stating what it does not touch. It stops short of naming the inverse sibling (also_domain) for adding cross-listings, so sibling differentiation is implicit rather than explicit.

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

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

Usage is implied by the phrasing: use it when you want to remove a cross-listing while preserving the underlying filing. However, no alternative is named (e.g., also_domain to add, move_to_project to relocate) and no when-not condition is stated beyond the scope note.

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