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

With no annotations, the description carries the behavioral burden and discloses that each call creates a new action plus audit entry, that any requires edge creates the action as blocked, and how priority defaults and clamps. It does not cover permissions, error behavior, or rate limits, but the core create semantics are well 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?

The description is dense but front-loaded: purpose, required input, dependency behavior, priority rule, creation side effect, and alternatives are all stated without 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?

Given no annotations and no output schema, the description still explains the return shape {success,action,edges}, dependency-state effects, priority handling, and when to use sibling tools. The remaining field-level details are covered by 100% schema description coverage.

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 meaningful constraints beyond the schema: title is required, parentId and requires must name existing actions, requires is comma-separated, and priority defaults to five and is clamped 1-10.

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

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

The description states a specific verb and resource: persist a work item with optional dependency edges. It also names sibling tools for related actions, so an agent can distinguish create from update or routine execution without opening other 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?

It explicitly routes the agent to memory_action_update for existing actions and memory_routine_run for stored workflows. It also states dependency and priority behavior that determines when this create tool behaves differently.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the audit-entry side effect, the dependent-unblocking propagation from status='done' plus the caveat that it does not recheck checkpoint gates, error behavior for missing actions, and priority clamping. These are non-obvious behaviors an agent could not infer from the 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?

Three tight sentences, front-loaded with the core action and return behavior, then edge cases, then sibling disambiguation. No filler or restated name/title.

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

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

No output schema exists, but the description still states what comes back (updated action plus audit entry) and covers the error case, propagation side effects, and value constraints. Nothing needed to invoke this tool 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 the baseline is 3, but the description adds real meaning: it ties status='done' to downstream propagation and states the 1-10 clamp enforcement for priority. The only minor redundancy is restating the priority range already in the schema.

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

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

States a specific verb and resource ('Change an existing action's status, result or priority') and immediately names the sibling tools it is not (memory_action_create for new work, memory_lease for claiming execution). An agent can route correctly 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?

Explicit when-to-use and when-not-to-use guidance: create for new work, lease to claim execution, this tool only for mutating an existing action's fields. The exclusions are named alternatives, not inferred.

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

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

With no annotations, the description carries the full burden and does well: it discloses reversibility, that originals/IDs/provenance remain in canonical storage, that archive/restore are dry-run by default, and that apply is gated on a preview revision, digest and a reason. It omits permissions/auth requirements, rate limits, and what restore actually changes.

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?

Five sentences, no filler, and the primary capabilities are front-loaded ahead of the apply prerequisites and exclusions. It is dense but every sentence earns its place; the packing of many clauses per sentence mildly hurts scanability.

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 12-parameter, five-action tool with no annotations and no output schema, the description covers the lifecycle model, defaults, apply gating, and scope exclusions adequately. What remains thin is the return shape for list/candidates and pagination behavior, which some agents will need to infer.

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

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

Schema coverage is 100%, so the schema already documents all 12 parameters including defaults and enums; baseline is 3. The description largely restates those defaults (inspect, dry-run true) rather than adding new syntax or semantics, though the apply-gating sentence usefully ties expectedRevision/expectedDigest/reason together. It does not add meaning beyond the structured fields for most 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?

The description names five specific verbs (inspect, list, candidates, archive, restore) over a specific resource (reversible archive state and retention/TTL candidates) scoped to an exact project. It also states what the tool is not — it 'does not enable automatic retention or perform forget' — which cleanly separates it from memory_governance_delete and memory_graph_purge. An agent can place it 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?

It gives explicit routing between its own actions: default action is inspect, archive/restore default to dry-run, apply requires preview revision, digest and a reason, and candidate listing is read-only and requires individual review. It carries a clear exclusion (no automatic retention, no forget). It does not name sibling alternatives by name, so it stops short of the top band.

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

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

No annotations are provided, so the description carries the full burden. It discloses ordering ('newest first'), default limit (50), the entry contents (timestamps, affected IDs, operation details), and failure behavior ('Query failures return an error result'). What it does not state explicitly is read-only/non-mutating nature, though 'inspect' and 'queries existing audit records' strongly imply it.

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

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

Four compact sentences, front-loaded with the purpose and the sibling disambiguation, then return shape, then failure mode. Nearly every clause adds information; only the restated limit default overlaps 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 still describes the return shape (ordered entries with timestamps, IDs, details) and the error case, and the two filter parameters are fully covered by the schema. 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 the baseline is 3. The description adds value beyond the schema by specifying that operation filtering is by 'exact operation name' (exact-match semantics the schema only calls 'operation type') and restates the 50 default for limit, giving an agent confident guidance on filter strictness.

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 recorded memory operations') with the intent ('explain a change or verify its history'), and names the sibling it is not (memory_diagnose). An agent can distinguish it from the other ~50 memory 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 an explicit use context ('explain a change or verify its history') and an explicit exclusion with the alternative named: 'use memory_diagnose for current consistency checks.' 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?

With no annotations, the description carries the full burden and does well: it discloses side effects ('create/resolve persist state and audit entries'), a failure condition ('resolving a non-pending checkpoint fails'), and the downstream effect ('passing can unblock actions'). Auth/permission requirements are unstated, keeping it below 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 key distinction (a managed gate, not a live check) and then enumerates operations compactly. It is dense with semicolon-separated clauses but each sentence carries 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?

For a 6-parameter, multi-operation tool with no output schema and no annotations, the description covers operations, side effects, failure modes, and return shape ('checkpoint and unblock count, or a checkpoint list'). It is nearly self-sufficient, though permissions/reversibility remain 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 real meaning: it maps which parameters belong to which operation and explains the gating semantics of linkedActionIds and status ('passing can unblock actions'). This goes beyond the schema's field-level descriptions.

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

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

States a specific resource (a recorded external gate / checkpoint) and scopes it against the obvious confusion: it manages the gate 'rather than performing a CI, approval or deploy check itself.' This separates it from sibling sentinel tools. The verb 'manage' is slightly generic, but combined with the per-operation detail the purpose is unambiguous.

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

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

Gives operation-specific guidance ('create' requires name, 'resolve' requires checkpointId and passed/failed, 'list' reads) and names an alternative routing rule ('use sentinels for event-driven conditions'). It lacks explicit when-not-to-use guidance beyond that single alternative, so it falls just short of a 5.

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

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

With no annotations, the description carries full burden and does well: it discloses that read stores a last-read snapshot and audit entry without creating durable memories, that write destructively overwrites MEMORY.md under a line budget, and that both require an enabled bridge. It does not describe read's return payload, leaving a small 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?

Three tightly packed sentences, front-loaded with the tool's purpose followed by mode behavior and the alternative. Every clause adds 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 single-parameter tool with no output schema, the description covers prerequisites, destructive write behavior, side effects, and write return values (path and line count). Only the read-mode return shape is left unspecified, a minor omission.

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, and the description exceeds it by giving operational semantics for each direction value (read parses/stores, write overwrites/returns path+line count) rather than merely restating the enum meanings.

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 (exchange data with the Claude Code MEMORY.md bridge) and clearly enumerates the two operational modes via direction='read'/'write'. This lets an agent distinguish it from siblings like memory_export 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 what each direction does and names an explicit alternative ('Use memory_export for a complete JSON backup'), giving clear routing for the backup case. It also states prerequisites (enabled bridge, configured path), but offers no explicit 'when not to use' beyond the export pointer.

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

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

No annotations are present, so the description carries the full burden, and it does so well: it discloses the return shape, the unrecorded-SHA result ({commit:null,sessions:[]}), the error on missing/empty sha, and negative scope (does not scan Git repos or prove authorship). It stops short of stating permission or auth requirements, 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?

Front-loaded with the core action, then edge cases, then alternatives. Each sentence carries distinct information, though the density makes it slightly long for a single-parameter read 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?

With no output schema, the description supplies the return structure and both edge-case outcomes, plus a clear statement of what the tool does not do. 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% with a single required parameter, so baseline is 3. The description adds value beyond the schema by emphasizing a full SHA and documenting the error behavior for a missing or empty sha, which the schema does not state.

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 the stored commit/session link for one full git commit SHA. It also names the sibling tools it is not (memory_commits, memory_timeline), so an agent can distinguish it 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 memory_commits to discover recorded links by branch or remote repo URL, or memory_timeline to read a linked session's observations. When-to-use-this vs alternatives is fully covered.

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

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

With no annotations, the description carries the full burden and does well: it discloses result ordering, the default (100) and hard cap (500) on limit, the return key ({commits}), and that excluded ambient sessions are stripped from session links. It omits auth requirements and error behavior, 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?

Four sentences, front-loaded with what is listed and how it is ordered, then filters, then the return shape, then routing. No filler and nothing misplaced.

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

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

For a read-only list tool with no output schema, the description covers filtering, ordering, pagination limits, return shape, and the storage model behind the results. There is no output schema, so return-value explanation in prose is appropriate and present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics by specifying that the branch filter is an exact match and that repo filters on remote URL rather than a path or name. The limit default/cap is also restated in prose, which is redundant with the schema but harmless.

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

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

The description gives a specific verb and resource ('List recorded Git commit/session links') plus ordering ('newest linkedAt first'), and distinguishes itself from the sibling memory_commit_lookup by use case. An agent can select it 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?

It explicitly names the alternative tool and the condition that selects it: 'Use memory_commit_lookup when you already know a commit SHA.' It also clarifies that this reads stored links rather than scanning Git repositories, which rules out a plausible misuse.

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

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

With no annotations, the description carries the full burden and does so well: it discloses validation behavior, the destructive side effect of overwriting an existing backup, that the source is replaced, and the return shape. Permission/prerequisite and rejection conditions are also stated.

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?

Dense but every sentence carries distinct information; the core action is front-loaded before the caveats and return description. Slightly long, but no sentence is 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?

No output schema and no annotations, yet the description explains return values, failure results, prerequisites, and side effects. Nothing essential for 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?

Only one parameter with 100% schema description coverage, so the schema already documents filePath fully. The description adds no format or path syntax detail beyond what the schema provides; 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 (shorten/compress prose), specific resource (.md file), and mechanism (configured LLM), and explicitly distinguishes itself from the sibling memory_consolidate with 'Use for file compression, not durable memory consolidation.' An agent can route correctly 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 explicit prerequisites ('Requires an enabled LLM provider'), failure modes (noop mode returns disabled), exclusion conditions (rejects symlinks and sensitive-looking paths), and a named alternative it is not for (durable memory consolidation). When-to-use and when-not-to-use are both covered.

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

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

With no annotations, the description carries the full burden and does so: it discloses that the operation mutates stored memory, writes an audit entry, emits skipped reasons or errors, and can report success:true while individual tiers fail. It also flags the OBSIDIAN_AUTO_EXPORT side effect and that a disabled config or thrown pipeline failure surfaces as 'unavailable'. This is unusually complete behavioral disclosure for a mutation tool.

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

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

Dense but front-loaded: the action and mutation scope lead, followed by selection, return shape, thresholds, failure modes, and alternatives. Every sentence carries operational content, though the volume of caveats makes it heavier than ideal for quick scanning.

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 must explain returns — and it does, giving the exact shape ({success:true,results} with per-tier counts), the partial-failure caveat, and the disabled-config response. For a one-parameter tool with 100% schema coverage, nothing an agent needs 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 the enum values are already listed there, so the baseline is 3. The description adds real meaning on top: it clarifies the default (all when omitted), that episodic is not implemented, and what downstream state each tier touches, which the schema does not convey.

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 (runs the LLM-backed consolidation pipeline over stored semantic/procedural memory, reflection insights and decay strengths) and explicitly scopes what it does not cover (no project filter, episodic not implemented). An agent can distinguish this from memory_reflect, memory_crystallize and the graph tools 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?

Names concrete alternatives ('use memory_save, memory_lesson_save or memory_graph_upsert for curated writes') and gives the when-not conditions (disabled by default in zero-LLM/noop and managed local-qwen modes; explicit thresholds of 5 summaries / 2 recurring patterns). Both the appropriate and inappropriate use paths are spelled out.

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

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

With no annotations, the description carries the full burden and does so well: it discloses LLM usage, that it stores a crystal digest, attempts to save extracted lessons, and links source actions, plus the failure mode (missing or unfinished IDs fail) and the return shape {success,crystal}. This is exactly the side-effect and error context an agent needs for a mutation tool.

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

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

Front-loaded with the core action and effect, and every sentence contributes (mechanism, side effects, return value, error behavior, param format, usage routing). It is dense and slightly crammed in the parameter clause, but 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?

Despite having no output schema and no annotations, the description covers the return shape, mutation side effects, prerequisites (actions must be done/cancelled), and error conditions. Nothing essential for 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 coverage is 100% so the baseline is 3, but the description adds genuine meaning beyond the schema: actionIds is comma-separated and project/sessionId 'annotate the digest' rather than filter, clarifying these are metadata not selectors. It stops short of format examples for the IDs.

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 (summarize/crystallize) and resource (done or cancelled actions and their links) and explains the mechanism (configured LLM). It distinguishes itself from siblings by naming memory_lesson_save as the alternative path, so an agent can differentiate without opening 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?

Explicitly scopes usage: 'Use for a completed work chain, not general recall' gives both the when and the when-not, and 'zero-LLM workflows should save curated lessons directly with memory_lesson_save' names the alternative tool and the condition that selects it.

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

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

With no annotations provided, the description carries the full burden and does so: it declares the read-only nature (no repairs applied), the return shape {success,checks,summary} with pass/warn/fail and fixable counts, and the tolerance rule for unknown category names. That is meaningful behavioral context an agent cannot get from structured fields here.

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 dense sentences, front-loaded with output shape and the non-repair guarantee; every clause adds information. The middle category enumeration is list-heavy but justified since the schema does not enumerate valid values.

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 describing the return object and status semantics. Combined with the read-only declaration, sibling routing, and category handling, an agent has everything needed to call this 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 already says "Comma-separated categories to check (default all)." The description adds genuine extra meaning: unknown names are silently ignored and the covered category set is enumerated, which goes beyond the schema's 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?

Specific verb+resource ("Inspect current subsystem consistency") with an explicit enumeration of what is checked. It distinguishes itself from siblings by naming memory_heal and memory_audit and stating how each differs, so an agent can route 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 an explicit exclusion ("Does not apply repairs") plus the follow-up workflow ("Review the findings before using memory_heal") and a named alternative for a different use case ("use memory_audit for historical operations"). This is a textbook when/when-not/alternative statement.

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

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

With no annotations, the description carries the full burden and does well: it clarifies that data is returned rather than a file written, warns that the payload may be large and cross-project, and documents the transport-limit error on oversized responses. It stops short of describing any chunking or pagination workaround, so an agent hitting the limit has no stated remedy.

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

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

Four compact sentences, front-loaded with what is returned and immediately followed by the use case and the load/error caveat. No filler or restated name, and every sentence 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?

There is no output schema and no annotations, so the description must cover both behavior and return characteristics; it names the payload collections, the error mode, and the alternatives. For a zero-parameter read-only export, nothing an agent needs in order 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The note that no project filter exists is useful framing rather than parameter documentation.

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 ('Return a versioned JSON export of stored AgentMemory data') and enumerates the payload contents (sessions, observations, memories, graph, derived collections). It also distinguishes itself from the two export-shaped siblings by name, 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?

Gives an explicit use case ('backup or transfer') and names two alternatives with the condition that selects each: memory_obsidian_export for Markdown files, memory_snapshot_create for a local Git snapshot. It also flags the absence of a project filter, which is a usage-relevant constraint.

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

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

No annotations are provided, so the description carries the behavioral burden and does it well: it discloses a 50-result cap, the returned fields (targetId, targetType, matchedFacets), and that full target records are NOT returned, plus the AND/OR evaluation semantics. It omits any auth/permission or pagination behavior, but for a query operation the disclosed constraints are substantial.

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 what the tool returns, then the required inputs and their interaction, then the narrowing parameter, then the return shape and alternatives. Every sentence carries distinct information with no redundancy.

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

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

There is no output schema, so the description correctly compensates by describing the return shape and cap, and it covers input constraints and alternative routing. Nothing an agent needs to invoke this facet-query tool 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 the baseline is 3, and the description adds genuine meaning beyond it: the AND vs OR logic, the rule that both conditions must pass when supplied together, and that targetType narrows to action/memory/observation. The added interaction semantics push it 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 (Find) and resource (IDs categorized by stored dimension:value facets), making the retrieval-by-facet purpose unambiguous. It also names sibling tools memory_facet_tag and memory_recall, so an agent can distinguish it from the write-side and content-search alternatives without inspecting 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?

Explicitly states the required condition (supply at least one of matchAll/matchAny), the combined-condition rule when both are present, and routes to alternatives ('Use memory_facet_tag to add facets or memory_recall for content-based retrieval'). This gives clear when-to-use and when-to-use-something-else guidance.

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

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

With no annotations the description carries the burden and does well: it discloses idempotent dedup behavior (a duplicate targetId/dimension/value returns skipped:true instead of adding a facet), the return shape, and validation constraints. It omits permission/auth requirements and any rate limits, which keeps it 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?

Three sentences, front-loaded with the core action, then return/idempotency semantics, then the exclusion. Every sentence carries distinct information with no repetition of 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?

No output schema exists, so the description compensates by stating the return payload ({success,facet}) and the skipped case. That, combined with validation rules and the alternative-tool routing, leaves nothing essential missing for a 4-parameter mutation.

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 real value by clarifying the dimension:value composite format and the nonempty constraint that the schema does not encode. It does not, however, explain the targetType-to-targetId relationship beyond the schema's own hints.

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 ('Store a dimension:value facet on an action, memory or observation ID') and names the downstream sibling it feeds (memory_facet_query). An agent can distinguish this from both the query tool and memory_action_update 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 routes filtering use cases to memory_facet_query and explicitly excludes state/content changes, directing those to memory_action_update. Both the when and the when-not, plus the alternative tool, are stated.

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

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

With no annotations, the description carries the full burden and does so: up to 15 recent visible sessions, up to five observations per file, sessionId excludes the current session, wildcard project behavior, return shape (context block or empty string), and a real side effect — matching observations record retention access. That is unusually complete behavioral 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 purpose and free of filler, but the middle sentence is a dense run-on packing caps, wildcard rules, return shape, and side effects together. Slightly harder to parse than an ideal definition, though 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?

There is no output schema, yet the description states the return shape (agentmemory-file-context block or empty string), all scoping rules, and the retention side effect. 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, but the description adds semantics the schema does not: the search window and per-file observation cap tied to the files parameter, the '*' cross-project/cross-agent intent, and the exclusion meaning of sessionId. Marginal but real 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?

The description opens with a specific verb+resource+scope: 'Retrieve context for comma-separated file paths before editing or investigating them.' It names the sibling it is not (memory_recall for general topic searches), so an agent can distinguish it 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?

It states the triggering situation ('before editing or investigating them') and names the alternative with the condition that selects it ('use memory_recall for general topic searches'). The sessionId and project scoping notes further tell the agent how to configure the call.

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

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

With no annotations, the description carries the full burden and does well: it discloses that it suggests candidates without acquiring leases or changing status (a read-only safety profile), and that agentId excludes actions leased by others. It falls just short of 5 by not covering pagination or ordering beyond the score field.

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

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

Four dense sentences with no waste; the ranking/scope constraint is front-loaded, followed by return values, then usage routing. 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?

No output schema exists, but the description compensates by enumerating return fields (action, score, lease state, totalActions, totalUnblocked). Combined with parameter and usage guidance, 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 baseline is 3, but the description adds real meaning beyond the schema: 'project filters the set' and 'Supply agentId to exclude actions leased by others' clarify intent beyond the terse schema strings. Only 'limit' is left entirely to 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 (Rank) and resource (unfinished actions with no dependency, checkpoint or active-conflict blockers), and explicitly differentiates itself from memory_next and memory_lease. An agent can identify the tool's role 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?

Names both alternatives and the conditions that select them: memory_next for a single suggestion, memory_lease to claim an action. It also states when this tool is appropriate (suggesting candidates without acquiring leases). 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?

With no annotations provided, the description carries the full behavioral burden and does so well: permanence/irreversibility, removal of access and search-index entries, audit-reason recording, removal of archive metadata for deleted originals, enforcement of project membership, and that missing IDs are skipped rather than erroring.

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?

Dense but front-loaded: purpose and the archive alternative come first, then constraints, then return shape. It packs a lot into five sentences with little waste, though the return-value sentence is somewhat clausal and could be tighter.

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 compensates by describing the return payload (success, deleted count, requested total, archiveStatesRemoved) and skip behavior. Combined with the scope exclusions, an agent has everything needed to call this correctly for a 3-parameter mutation 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. The description adds genuine semantics beyond the schema: project is required for archive targets and, when supplied, must match every selected memory; reason is tied to audit recording. It clarifies the enforcement behavior rather than just restating field names.

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

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

The first sentence states a specific verb (permanently delete), the resource (comma-separated memoryIds plus their access/search-index entries), and a side effect (recording an audit reason). It also explicitly distinguishes itself from the sibling memory_archive ('Use memory_archive for reversible hiding').

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 reversible alternative (memory_archive), states the condition under which the project parameter is required, and gives explicit scope exclusions ('does not delete sessions or observations'). An agent knows when to pick this versus archive and what constraints apply.

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

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

With no annotations, the description carries the full burden and does so: it discloses the default action, what detach destroys vs retains, the limited scope of retire/restore (visibility only, history preserved), required prerequisites, dryRun preview semantics, the mutation side effects (graph/index update + audit entry), and the error conditions (invalid, missing, stale, wrong-project, conflicting).

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

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

Front-loaded with purpose and dense with information; every sentence earns its place by covering action behavior, requirements, side effects, and errors. It is a single unbroken block, which hurts scannability slightly, but is appropriately sized for the tool's complexity.

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

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

For a complex, multi-action mutation tool with no output schema, the description is thorough: it covers prerequisites, per-action behavior, dry-run preview, side effects, and even the return shape ({success,action,project,dryRun,changedTargets,results} plus auditId and per-target before/after). 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 80%, so the schema already documents most parameters; the description adds genuine semantics beyond it, notably that action defaults to detach and that target sources are review evidence rather than replacement relation support. It stops short of syntax-level detail, so 4 rather than 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?

States a specific verb+resource ('Correct exact graph targets in one project') with scope qualifiers and names three sibling tools it is not (memory_graph_query for inspection, memory_graph_upsert for adding relationships, memory_graph_purge for physical deletion). An agent can distinguish this reconcile tool from its graph siblings 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 memory_graph_query to inspect targets and memory_graph_upsert to add supported relationships; memory_graph_purge physically deletes a project graph.' It also clarifies per-action selection (detach default vs retire/restore) and when-required conditions (expectedUpdatedAt, review evidence, live endpoints).

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

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

No annotations exist, so the description carries the full burden and does: irreversibility, exact-match inventory requirement, failure cases with {success:false,error}, what is deleted (stale rows, incident/project edges, edge history, indexes, archive metadata) versus preserved (sessions, observations, memories, lessons), and the caveat that physical counts may exceed supplied live counts.

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 irreversible action and required reason before the preconditions, and every clause carries operational weight. It is dense and somewhat run-on as a single paragraph, which costs some readability.

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

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

A destructive tool with no output schema and no annotations, yet the description enumerates the returned fields (success, auditId, deleted counts, archiveStatesRemoved, remaining counts), the failure envelope, and the preservation boundary. Nothing an agent needs in order 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 baseline is 3, but the description adds critical semantics beyond the schema: nodeIds/edgeIds must be an exact complete live inventory, must match exactly, and are bounded at 500 nodes / 1000 edges. It does not add format detail for `project` or `reason`, keeping it just shy of 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?

States a specific verb (purge), atomic resource (graph records), and narrow scope (one exact project) plus the required audit reason. It explicitly names memory_graph_query for inventory and memory_graph_provenance_reconcile for the selective/reversible alternative, so an agent can separate it from siblings 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 a mandatory precondition (obtain the complete live inventory via memory_graph_query), states there is no dry run, and routes selective or reversible work to memory_graph_provenance_reconcile. Both the when-to-use and when-not-to-use cases are explicit.

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

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

With no annotations, the description carries the full burden and does well: it discloses that no automatic extraction is required, that edges returned are page-local versus the separate exact edge inventory, and that callers must inspect warnings and totalsExact before trusting totals. What is missing is the permission/auth profile for cross-project '*' reads and what happens if the project identifier is unregistered.

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 purpose, then dispatches parameters and caveats in tight sentences. Dense jargon ('totalsExact', 'page-local') without a wasted sentence, though the run of clauses makes it slightly harder to skim than an ideal 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?

For a 9-parameter, no-output-schema read tool with many graph siblings, the description covers return shape, pagination, truncation caveats, and sibling routing. It stops short of documenting the cross-project auth/ownership model that a '*' read implies, which is the main remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it explains the interaction between startNodeId-driven traversal and maxDepth, and clarifies the semantic distinction between page-local edges and the edgeLimit/edgeOffset inventory page.

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 (read) and resource (stored entity/concept graph nodes and edges), and explicitly carves out territory from the sibling memory_relations for memory-to-memory links. An agent can distinguish it from the other graph tools (upsert, purge, provenance_reconcile) 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 routing: '*' is only for deliberate cross-project reads, startNodeId for bounded traversal, query/nodeType for filtering, and edgeLimit/edgeOffset to opt into an independent edge inventory page. It also names the alternative tool (memory_relations) and when to prefer it.

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

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

No annotations are provided, so the description carries the full burden and does well: it discloses that the tool writes provenance and audit records, that existingNodeId is validated against a live node preserving same-name siblings, and what the response returns. It omits auth/permission needs and rate or size-limit guidance, keeping it 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 purpose, then parameter mechanics, then side effects and the sibling pointer. Dense but each clause earns its place; a few semicolon-chained clauses make it slightly run-on but nothing is 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 mutation tool with no annotations and no output schema, the description does the necessary work: it covers side effects, validation behavior, and return values, and warns that sources must belong to the project. It could say more about merge-vs-create semantics and limits, but nothing critical 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 real meaning: it clarifies that node keys are request-local edge endpoints, how sourceIndexes selects supporting groups, and that sharedSources=true shares all groups (required when sourceIndexes are omitted). This coordination logic is not fully conveyed by the schema alone.

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

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

States a specific compound verb (create or merge) with a precise resource (manually authored graph nodes and edges) and scope (an exact project, without an LLM). The 'without an LLM' qualifier distinguishes it from any LLM-extraction flow, and the trailing pointer to memory_graph_query makes it separable from the read sibling.

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

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

Explicitly routes the agent to memory_graph_query to inspect existing records first, and states the precondition that official session/observation sources must belong to the target project. Clear positive guidance, though it does not spell out when-not-to-use (e.g. versus sketch/crystallize flows).

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

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

With no annotations, the description carries the full burden and does well: it discloses that repairs can delete orphaned/expired records, that state changes are recorded with audit entries, and that the default mode applies repairs while dryRun='true' only reports. It also gives the return shape {success,fixed,skipped,details}. It stops short of stating permission/auth requirements, but the destructive profile and default behavior are clear.

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 category list, then layers dry-run behavior, return shape, and the prerequisite. Dense but every sentence carries information; no wasted 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 repair tool with no annotations and no output schema, the description supplies the missing pieces: destructive side effects, audit trail, default vs dry-run behavior, the return shape, and the prerequisite diagnostic step. An agent has everything needed to invoke it safely.

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 both parameters (dryRun, categories) are already documented in the schema. The description restates dryRun behavior and loosely references the category set but adds no syntax or format detail beyond the schema, 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 (apply repairs) on a specific resource (selected diagnostic categories) and enumerates those categories. It is clearly distinguished from memory_diagnose, which only identifies issues, and from memory_verify, making the sibling boundary obvious.

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 states the prerequisite workflow ('Run memory_diagnose first'), the condition under which dry run should be used, and a real limitation ('not every diagnostic has an automatic repair'). It names the alternative tool and the condition that selects it.

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

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

With no annotations, the description carries the full burden and does well: it discloses deleted-entry exclusion, confidence-descending ordering, the limit default of 50, and the return shape {success,insights}. It omits any note on permissions or pagination beyond limit, but for a read-only list this is a strong 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?

Three tight sentences, front-loaded with the core read operation and scoping rules, then return behavior, then the disambiguation from alternatives. Every clause earns its place with no redundancy.

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

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

There is no output schema, so the description correctly supplies the return shape and ordering. Combined with the filter semantics and sibling routing, an agent has everything needed to call this three-parameter, zero-required tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: 'exact project' match semantics that the schema's bare 'Filter by project' does not convey, plus confirmation that minConfidence acts as a threshold and limit bounds results. It goes modestly 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 and resource ('Read existing synthesized insights') and immediately scopes it with exclusion and filter rules. It also explicitly differentiates itself from memory_reflect and memory_lesson_recall, so an agent can pick it over those siblings 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 an explicit when-not ('This does not generate new insights') and names the two alternative tools with the condition that selects each. It also clarifies the omitted-project behavior, leaving nothing to inference about when this tool is the right call.

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

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

With no annotations, the description carries the full burden and does well: it discloses conflict behavior (another holder returns a conflict), state transitions (active/assigned, done, pending), that it writes lease/action/audit state, and the return shape. It stops short of permissions/auth needs or rate limits, so it's 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?

Front-loads the core action (acquire/renew/release a lease) and then layers conditions and the sibling handoff. Dense but every clause earns its place; slightly packed for a single paragraph.

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 or annotations, the description compensates by describing state changes and return values ('lease details or released:true'). It is nearly complete for a mutation tool, with only permission and TTL-enforcement details 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining what each operation value does and what 'result' triggers on release. ttlMs and agentId semantics remain schema-only, keeping it from 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?

States specific verbs (acquire, renew, release) and the resource (action lease for agentId) with a clear scope. It distinguishes itself from siblings by explicitly naming memory_action_update as the tool for dependent-completion propagation.

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 per-operation conditions: acquire requires an unfinished, unblocked action; renew requires this agent's live lease; release behavior depends on a nonempty result. It also names the alternative (memory_action_update) and the transition it handles, so the agent knows when-not to use this tool.

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

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

With no annotations present, the description carries the full burden and does so well: it discloses that deletion is soft, that it removes lessons from recall/list, and that re-saving restores a fresh lesson. It omits auth/permission requirements and behavior for a nonexistent id, keeping it 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?

Two short sentences, zero filler, with the core action and its consequence front-loaded. Every clause earns its place.

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

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

For a two-parameter, no-output-schema delete tool, the description covers the essential mechanics (soft delete, effect on recall/list, re-save behavior). Missing only edge cases like unknown ids or permission failures.

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 are already documented, including the optional project/archive caveat. The description only restates the target-by-id idea, adding no syntax or format detail beyond the schema; 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 ('Soft-delete a lesson') plus the identifier used to target it. It is clearly distinguishable from the lesson_save/recall siblings, though it does not name them explicitly.

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

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

Usage is only implied: the note that deleted lessons leave recall and list signals 'use this when you want a lesson suppressed', but there is no explicit when-not or routing to alternatives such as memory_governance_delete or a hard-delete path.

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

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

With no annotations, the description carries the full burden and does so well: it discloses exclusions (deleted/archived, below minConfidence), the return shape ({success,lessons}), the ranking criteria (relevance, confidence, recency), the limit bound, and the non-mutating nature ('without generating or reinforcing them'). This is rich behavioral context beyond structured fields.

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

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

Front-loads the search scope and special value, then behavior, then return shape, then usage routing. Every 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?

No output schema exists, but the description provides the return shape and ranking semantics. Filtering, scoping, limit behavior, and non-mutation are all covered, so an agent has enough to call this 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, but the description adds real meaning: the special '*' value for project and the minConfidence filtering behavior. Only the limit parameter is not elaborated beyond the schema default.

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

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

States a specific verb (search) and resource (saved lessons) with scope (explicit project, '*' across projects). It clearly distinguishes itself from memory_recall, which searches observations and durable memories, so an agent can route correctly 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?

Explicitly says to use it before choosing an approach, and names the alternative tool (memory_recall) along with what that alternative covers. Nothing about when to select this versus its sibling 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?

With no annotations, the description carries the full burden and does so well: it discloses upsert semantics ('matching normalized content strengthens the existing lesson and merges support/tags; otherwise creates one'), validation scope, and the return shape with action values. It stops short of permissions, rate limits, or failure modes, which keeps 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 purpose and scope, then provenance, then behavior, then sibling routing. Dense but every sentence earns its place; slightly packed but not wasteful.

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 annotations and no output schema, the description covers behavior, return shape, and sibling routing adequately. Only auth/permission expectations 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 schema already documents all seven parameters (baseline 3). The description adds genuine meaning beyond the schema by stating that 'sources pairs are preferred' over sourceIds and that both are 'validated in that project', clarifying the precedence between the two provenance inputs.

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 ('Persist a reusable lesson') plus scope ('in an exact project'), and explicitly names siblings it is not (memory_save, memory_lesson_recall). An agent can distinguish it from the other lesson/memory tools 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?

Provides explicit routing: 'Use memory_save for decisions/preferences, and memory_lesson_recall before applying earlier lessons.' This gives both the alternative tool and the condition that selects 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?

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses required authentication, peer reachability constraints, default direction, the write effects of push vs. pull ('push sends local data; pull merges received records'), local state mutation ('Updates local peer/audit state'), and partial-failure behavior ('returns per-peer pushed/pulled counts and errors, even when some peers fail').

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

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

The description is front-loaded with purpose and prerequisites, and every sentence contributes useful context. It is slightly redundant in restating parameter defaults already present in the schema, keeping it just short of ideal 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 a parameter-light but behaviorally complex synchronization tool with no output schema and no annotations, the description is complete enough: it covers purpose, prerequisites, peer selection, direction semantics, side effects, return information, and failure handling.

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 already 100% and documents both parameters, so baseline is 3. The description adds operational meaning beyond the schema by explaining the effect of each direction value ('push sends local data; pull merges received records') and by clarifying that omitting peerId selects all peers.

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 ('Exchange') and resource ('configured shared collections with registered peer AgentMemory instances'), making it clear this is peer-to-peer synchronization rather than a local memory operation. However, it does not explicitly name or distinguish itself from any sibling tool, so sibling differentiation is implicit rather than stated.

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

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

Provides clear prerequisites ('Requires AGENTMEMORY_SECRET and reachable permitted peer URLs') and a restriction ('Use only for authorized peer transfers'), which gives context for appropriate use. It does not, however, name alternative tools or describe when another sync/share tool would be preferable.

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

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

No annotations are provided, so the description carries the burden and does so well: it discloses that it is non-mutating (does not claim or start work), describes the null-result case ('suggestion:null when no actionable work is found'), and explains that agentId accounts for leases held by other agents. It stops short of covering auth or rate-limit behavior, keeping it below 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?

Three tightly written sentences, front-loaded with the core action and return value, followed by the exact non-mutating caveat and the routing alternatives. No filler or redundancy.

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

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

With no output schema present, the description compensates by describing the returned fields (action ID, title, priority, score, counts) and the null case. Combined with the routing guidance, 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, but the description adds genuine semantics: agentId is not just an identifier but a mechanism that makes the suggestion account for leases held by other agents, and project scopes the frontier. That is meaning beyond the terse schema labels.

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 ('Suggest the highest-ranked action from memory_frontier') with clear scope tied to optional project and agentId. The return shape is summarized, and the distinction from siblings memory_frontier and memory_lease is made explicit, so an agent can tell it apart 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 says what it does NOT do ('does not claim the action or start work') and routes the agent: use memory_lease to acquire, memory_frontier to compare candidates. When-to-use and the specific alternative for each adjacent need are named.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that directories are created, that matching generated filenames are overwritten, that an audit entry is recorded, and that vaultDir is constrained to AGENTMEMORY_EXPORT_ROOT (~/.agentmemory). These are exactly the mutation, safety and environment facts an agent needs before invoking a filesystem-writing tool.

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

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

Dense but front-loaded: what it writes, then the types/default rule, then the path constraint, then side effects and return values, then the alternative tool. Every sentence carries load 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?

No output schema exists, yet the description fully specifies the return value ('per-type exported counts, vaultDir and any per-file errors'), along with side effects, defaults and the path constraint. 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: 'types is comma-separated' and the omission-equals-all default, plus the AGENTMEMORY_EXPORT_ROOT containment rule for vaultDir (the schema only gives the ~/.agentmemory/vault/ default). The slight mismatch between the description's stated root and the schema's default path is a minor ambiguity.

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+resource+format: 'Write Obsidian Markdown notes and MOC.md' covering the exact entity types (memories, lessons, crystals, sessions) with frontmatter and wikilinks. It clearly distinguishes itself from the nearest sibling by naming memory_export as the JSON-output variant, so an agent can choose between them 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?

States the default behavior explicitly ('omission exports all four collections') and routes to the alternative: 'Use memory_export for returned JSON instead of filesystem output.' This is clear context plus a named alternative, but it gives no explicit when-not guidance for other cases (e.g. read-only environments, large vaults).

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

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

No annotations, so the description carries the full burden, and it does so well: it discloses the 'without an LLM' mechanism, threshold rules (file pairs ≥3 sessions, error titles ≥2 occurrences), the cap of 20 frequency-ranked results, and scope limits (visible, non-archived). It doesn't cover performance/latency or failure behavior, keeping it 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 purpose, then thresholds, then return shape, then routing guidance. Dense but each sentence carries information; only minor compression is possible.

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

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

With no output schema and no annotations, the description still explains the return shape (up to 20 ranked patterns with type, description, files, frequency, source session IDs), the thresholds, and the scoping rules. Nothing an agent needs 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%, so the baseline is 3, but the description adds meaning: it clarifies that omitting project or using '*' covers all projects and that agentId preserves the configured read scope. This adds interpretation beyond the schema's raw field descriptions.

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

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

States a specific verb+resource: 'Detect repeated file co-changes and error titles in visible, non-archived session observations.' It further distinguishes itself from siblings by naming memory_profile and memory_reflect as different capabilities, so an agent can route 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 routes the agent to alternatives ('Use memory_profile for a project overview or memory_reflect to create synthesized insights') and states the detection thresholds that gate results. It gives clear context but doesn't spell out explicit when-not conditions for this tool beyond the sibling alternatives.

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

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

No annotations are supplied, so the description carries the burden, and it does well: it discloses the one-hour cache reuse, that refresh forces recomputation, and that recomputation has side effects (persists the profile cache and an audit entry). It omits permission/auth requirements and any rate limits, so it is not fully 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?

Front-loaded with purpose and contents, then return shape, caching semantics, side effects, and the sibling pointer. Dense and mostly waste-free, though the return-shape and cache sentences 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?

Despite no output schema and no annotations, the description covers the return payload (including the no_sessions failure shape), caching behavior, write side effects, parameter expectations, and the sibling alternative. 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, but the description adds real meaning beyond the schema: it stresses supplying the exact project identifier, explains that agentId preserves configured scope, and ties refresh to recomputation and cache persistence rather than just 'force rebuild'.

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 ('Get a project overview') and enumerates exactly what the profile contains (top concepts/files, conventions, errors, recent activity) plus the 20-session window. It also names the sibling it is not (memory_patterns) so the agent can route 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 clear context (use memory_patterns for recurring co-changes or errors) and explains when to pass refresh='true'. It stops short of explicit when-not conditions or a full alternative map across the many sibling tools.

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses the side effect that returned items record retention access by default and how to disable it (trackAccess=false), plus token_budget truncation and result formats. It omits auth/permission requirements and pagination behavior.

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

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

Dense and front-loaded: purpose first, then return behavior, then parameter caveats, then the sibling alternative. Every sentence carries information, though the six-sentence run is slightly crowded.

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 correctly covers return values (ranked results, full/compact/narrative, token_budget truncation) and the retention side effect. It is nearly complete, lacking only auth/rate-limit context for a read tool with a mutation-adjacent side effect.

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 '*' semantics (agentId/project), sourceKind filtering behavior, and trackAccess. It meaningfully augments rather than repeats the field descriptions.

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

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

States a specific verb (search) and resource (project-scoped observations and durable memories), and explicitly routes a different use case to the sibling memory_smart_search. An agent can distinguish this from related recall/search tools 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 clear context ('before continuing work or checking earlier decisions') and names an alternative with its selecting condition ('Use memory_smart_search for compact search followed by ID expansion'). No explicit when-not guidance, but the '*' cross-project warning adds a negative-use caveat.

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

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

With no annotations, the description carries the full burden and does well: it discloses persistence ('persists insights and audit state'), the internal mechanism (stored graph clusters or a similarity fallback), a hard input constraint (exact project required), and the returned fields. It omits any mention of LLM cost, latency, or permission requirements, which would matter for a tool that invokes an external model.

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 dense sentences, front-loaded with the core action, then constraints, then returns, then routing to siblings. No filler, though the return-field enumeration makes it slightly list-heavy.

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 usefully enumerates the return shape (newInsights, reinforced, clustersProcessed, clustersSkipped, usedFallback) and covers the prerequisite of an enabled LLM. Combined with a fully documented 2-parameter schema, an agent has enough to call it correctly, with only cost/authorization behavior 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, but the description adds real meaning beyond the schema's terse 'Filter by project' by stating the value must be an exact project and that '*' is rejected. maxClusters is left entirely to the schema (default 10, max 20), so it is not fully compensated.

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 (synthesize/reinforce) over a specific resource (project concept clusters) via an LLM, and explicitly names two siblings (memory_insight_list, memory_patterns) it is not. An agent can distinguish this from related memory tools 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?

Names alternatives and their conditions ('Use memory_insight_list to read existing insights or memory_patterns for deterministic recurring file/error patterns'), and gives a when-not constraint ('rejects "*" or noop-provider mode'). It stops short of stating the positive trigger for choosing synthesis over consolidation or crystallize, so it is clear but not exhaustive.

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

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

With no annotations, the description carries the full burden and delivers: the starting memory is excluded from results, maxHops defaults to 2 and is capped at 5, at most 500 memories are visited, and returned memories 'record retention access' (a side effect of reading). These are substantive behavioral traits beyond anything in the 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 action, then return shape, then traversal limits, then the sibling alternative. Four tight sentences with no filler; every clause 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?

With no output schema and no annotations, the description fully compensates: it specifies the return fields (memory, hop, confidence), the exclusion rule, the traversal caps, and the retention-access side effect. Nothing needed 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 the schema already documents all three parameters, giving a baseline of 3. The description reinforces maxHops' default and adds the cap of 5 (not in the schema), but adds nothing for memoryId or minConfidence 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 ('Follow stored memory-to-memory relations, related IDs, supersession and parent links from memoryId'), naming exactly which link types are traversed. It also explicitly distinguishes itself from the sibling memory_graph_query, 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?

Provides an explicit alternative and the condition that selects it: 'Use memory_graph_query for the separate entity/concept graph rather than memory relationships.' This is a clear when-not/alternative rule, not merely implied usage.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the return shape ({success,run,actionsCreated}), error behavior ('missing routines return an error'), non-idempotency ('each call creates a fresh run and audit entry'), and crucially that it does not execute the work. This is exactly the behavioral context an agent needs before invoking.

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 mechanism, then moves to return/error behavior and the alternative tool. Four dense sentences with no filler, though the phrase 'requires edges between dependent steps' is slightly awkward and the final routing sentence could be its own clearly marked line.

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 fields, the error case, and the side effects (actions created, audit entry). For a 3-parameter tool with no annotations, nothing an agent needs 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%, so the baseline is 3, but the description adds real meaning beyond the terse schema text: 'project supplies context for created actions' and 'initiatedBy records the initiator' explain downstream effects the schema labels ('Project context', 'Agent starting the run') do not.

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 ('Start a new run of an existing routineId') and immediately clarifies the mechanism: it creates an action per stored workflow step with dependency edges. This clearly distinguishes it from memory_action_create, which it explicitly names.

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 a clear routing rule at the end: 'Use memory_action_create for a single work item,' which tells the agent when this tool is not the right choice. It also implies the positive case (multi-step routine runs), but doesn't spell out prerequisites like needing a pre-existing routineId validated elsewhere.

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

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

With no annotations, the description carries the full burden and does so well: it discloses validation rules ('*' rejected, sourceObservationIds must resolve to official observations), supersession/versioning behavior (repeated calls can create new versions), and the return payload including the advisory similarTo match.

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?

Dense and front-loaded — persistence scope and the write constraint come first, then validation, supersession, return shape, and the sibling routing. Every sentence conveys distinct actionable 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?

Despite no output schema, the description states what is returned (the saved memory plus advisory similarTo). Combined with the rich input schema and disclosed mutation semantics, 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 baseline is 3; the description adds value by stating the resolution constraint on sourceObservationIds and the project '*' rejection, which are behavioral rules the schema only partially conveys.

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 precise verb+resource ('Persist a verified insight, decision or preference') and scopes it to an exact project. It names and differentiates from the sibling memory_lesson_save, 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?

Explicitly routes reusable lessons-with-confidence to memory_lesson_save, giving a concrete condition for the alternative. It also notes '*' is rejected for writes, but does not enumerate the full set of write-alternative siblings in the landscape.

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

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

With no annotations the description carries the full burden and does reasonably well: it explains that timers schedule a local callback while other types rely on checks or external triggering, states the return shape {success,sentinel}, and notes audit state is recorded. It omits permissions, idempotency, and persistence lifetime beyond the expiresInMs param.

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

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

Front-loads the purpose, then packs config rules and behavioral notes densely with little waste. The config-per-type enumeration is efficient, though the sentence stacking makes it slightly dense to parse.

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 create tool with no annotations and no output schema, the description covers purpose, config semantics per type, runtime behavior of each type, return shape, and one alternative. Only auth/prerequisite context and the trigger/create relationship are left uncovered.

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 genuinely adds meaning: per-type config contents, the operator enum values (gt/lt/eq) not present in the schema, and the constraint that durationMs must be positive. This is real value beyond the structured fields.

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 ("Persist a watching sentinel") and clarifies scope ("optional gates on existing linkedActionIds"). It reads as a create/registration operation distinct from memory_sentinel_trigger, though it never explicitly contrasts the two, and "sentinel" remains jargon that isn't defined.

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 one alternative ("Use memory_checkpoint for a manually resolved external gate") with the condition that selects it, which is useful routing. However it gives no guidance on when to create a sentinel at all versus other mechanisms, and never addresses the obvious sibling memory_sentinel_trigger.

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

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

With no annotations, the description carries the full load and does so well: it discloses persisted status/time, audit recording, gate-driven unblocking of linked blocked actions, the explicit non-recheck of dependencies, the return shape, and the missing/non-watching error case. It omits permission requirements and re-trigger/idempotency behavior, 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?

Dense but front-loaded: the core action and payload come first, followed by side effects, return shape, error behavior, and alternatives. Every clause carries information; slightly long enumeration 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?

No output schema exists, yet the description supplies the return shape {success,sentinel,unblockedCount} and the error condition, plus the side effects and the important dependency non-recheck caveat. An agent has everything needed to call and interpret this correctly.

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

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

Schema description coverage is 100%, so both parameters (sentinelId, result) are already documented. The description restates the JSON payload and ID semantics without adding format, validation, or example details beyond the schema — 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+resource ('Fire an existing watching sentinel by ID') with the key qualifier 'watching', which separates it from the create/checkpoint siblings. An agent can identify the operation 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?

Names two alternatives and their respective roles: memory_sentinel_create to register a condition, memory_checkpoint to resolve an external check. This gives clear routing context, though it never states an explicit exclusion or precondition for choosing this tool over others.

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

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

With no annotations, the description carries the burden and does well: it discloses that archived/excluded ambient sessions are hidden, that includeExcluded requires exact project+sessionId and still hides archived, that invalid filters error, and that agentId defaults to the configured read scope. It stops short of stating explicit permission/auth requirements or any rate limits.

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 return shape, pagination, parameter behavior, filtering, and sibling routing in a logical order. It is one dense paragraph packing multiple facts per sentence, which costs a little scannability but 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?

No output schema exists, so the description supplies the return shape ({sessions,total,limit,offset,nextOffset} and the empty-result case) itself. For a six-parameter filtered read tool with no annotations, nothing an agent needs to invoke it correctly appears to be 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 only 67%, yet the description adds meaning for all six parameters: agentId's default read scope and '*' cross-agent behavior, project:'*' as a deliberate cross-project read, sessionId selecting one session, includeExcluded's exact-match requirement, and limit's default of 20 / max 500 with nextOffset-driven paging. This fully compensates for the coverage gap.

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

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

States a specific verb and resource ('Read stored session metadata') plus scope ('in an explicit project') and ordering ('newest startedAt first'). The final sentence distinguishes it from memory_timeline, so an agent can route between the two 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 clear when-to-use signal and names one explicit alternative ('Use memory_timeline for observations within a session'), plus the prerequisite for includeExcluded. It does not distinguish against the wider set of session/recall siblings, which keeps it 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?

No annotations are supplied, so the description carries the full burden, and it does disclose the key non-obvious behavior: returned unread direct messages are marked read and audited, while sent messages and broadcasts are unaffected. It also states ordering (newest first) and the limit default. It omits permission/authorization requirements and pagination behavior, which keeps 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 core action and return shape, then filters, then side effects, then the sibling pointer. Dense but each clause carries information; the only slight friction is the run-on sentence combining side-effect and visibility semantics.

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

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

For a 4-parameter read tool with no output schema and no annotations, the description covers return shape, ordering, filtering semantics, the read-marking side effect, and the alternative tool. Authorization/visibility rules ('visible to agentId') are asserted but not detailed, which is a minor remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: unreadOnly='true' excludes broadcasts and has the side effect of marking messages read, threadId narrows a conversation, and limit defaults to 50. These are semantic details the schema descriptions do not convey.

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 non-expired signals visible to agentId'), plus scope qualifiers (non-expired, visible to agentId, newest first) and the return envelope {success,signals}. This is clearly distinguishable from the sibling memory_signal_send, which it explicitly names as the counterpart.

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 routing: 'Use memory_signal_send to create a message,' and explains when to use the unreadOnly and threadId filters. It stops short of explicit when-not conditions (e.g., when to prefer memory_recall or memory_team_feed over this tool), but the operational context is unambiguous.

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

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

With no annotations, the description carries the burden and does well: it discloses the return shape {success,signal}, that message and audit state are written, the auto-threading rule for replyTo (reuse parent thread when found, else create new), the absence of a TTL parameter, and the authorization requirement. It stops short of describing failure modes or how authorization is verified.

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

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

Four dense sentences, front-loaded with the core action and the broadcast condition, with no filler. The return shape and threading detail are compactly packed, though the TTL remark is a slight tangent.

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

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

A mutation tool with no annotations and no output schema, yet the description supplies the return contract, the audit-write side effect, threading semantics, and the authorization precondition. Only failure/permission-denied behavior is left 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, but the description adds real meaning beyond the schema: the 'omit to for broadcast' rule, the nonempty from/content validation constraint, and the replyTo threading behavior (reuses parent thread when found, otherwise creates a new one) which the schema's 'auto-threads' hint does not fully explain.

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 ('Store a typed message for another AgentMemory agent, or broadcast by omitting to') and immediately distinguishes the broadcast case. An agent can tell this apart from the sibling memory_signal_read 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?

Explicitly routes the agent: 'Use memory_signal_read to retrieve messages', and states the precondition that sending requires authorization for the recipient and content. It gives clear context and a named alternative but does not enumerate when-not-to-send scenarios.

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

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

With no annotations, the description carries the full load and does disclose key lifecycle traits: the object is ephemeral, auto-expires after TTL, and can be promoted to permanent actions or discarded. It omits auth/permission needs and what the created sketch returns, but the lifecycle disclosure is substantial for a create tool.

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

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

Three short sentences, zero waste, with the ephemeral/exploratory nature front-loaded before the lifecycle note.

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?

Covers creation semantics and the full lifecycle (expire/promote/discard) for a simple 4-param tool with no output schema. Minor gaps: no mention of permissions or what is returned on success.

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 (title, project, description, expiresInMs) are already documented in the schema. The description adds no parameter-level detail beyond noting TTL, 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+resource ('Create an ephemeral action graph') plus its distinguishing scope ('for exploratory work'). This separates it from the permanent memory_action_create sibling, though it never names that sibling explicitly.

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

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

'For exploratory work' implies the usage context, and 'can be promoted ... or discarded' points at the follow-on path (memory_sketch_promote). However, it gives no explicit when-not guidance or named alternative, leaving selection 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?

With no annotations, the description carries the full burden and does so well: it discloses side effects (sketch association removed, sketch marked promoted, audit entries recorded), failure modes ('missing or non-active sketches fail'), the empty-input case, and the return shape {success,promotedIds}. It does not state required permissions or whether the promotion can be undone, which are the notable remaining gaps.

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 mechanism, then adds failure and return details, all in a compact block with little waste. The single long run-on sentence is dense but every clause contributes.

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

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

For a two-parameter, no-output-schema mutation tool, the description supplies the return shape, the failure conditions, and the empty-input behavior, so an agent can call it correctly without further context.

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 both parameters are already documented; the description only restates that the optional project overrides the project of promoted actions. Baseline 3 applies when the schema does the semantic 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 (promote), a specific resource (actions of an active sketchId) and the mechanism (removing their sketch association, becoming regular work items). It is clearly distinguishable from the sibling memory_action_create, which it explicitly names.

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 trigger ('use after exploratory work is accepted') and names the alternative path with its selecting condition ('memory_action_create directly creates regular work items'). Nothing about when to choose this tool 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?

With no annotations, the description carries the full burden and meets it: it discloses newline insertion, audit recording, the success/return shape, failure cases (missing or read-only slot, sizeLimit overflow), that overflow leaves content unchanged, and project-slot shadowing of global slots.

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 failure modes and routing. Dense but every clause is relevant; the semicolon-chained sentences pack a lot without waste, though they are slightly heavy.

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 or annotations exist, yet the description covers return values, edge cases, overflow semantics, and the label-namespace interaction. Nothing needed to invoke it correctly is missing 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 both parameters are already documented, setting a baseline of 3. The description adds real meaning to 'label' by explaining that project slots shadow global slots with the same label, which the schema does not convey.

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 text to an existing effective slot') plus two behavioral details (newline insertion, audit entry). It is immediately distinguishable from siblings memory_slot_create, memory_slot_replace, and memory_slot_delete.

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

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

Explicitly routes to alternatives under named conditions: memory_slot_replace when overflow needs compaction, and memory_slot_create when the label does not exist. Repeated-call behavior is also called out, 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?

With no annotations, the description carries the full burden and delivers: duplicate-label rejection within scope, project-shadows-global semantics, pinned-slot inclusion in context injection, audit-entry creation, and the return shape {success,slot}. These are meaningful behavioral traits an agent could not infer from the 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 action and return value, followed by tightly packed constraint and behavior clauses. Every sentence adds distinct information (format rules, collision behavior, pinning, audit), 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 with no output schema, the description supplies the return shape, defaults context, collision/scoping semantics, and side effects. Nothing critical an agent needs 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%, so baseline is 3, but the description adds real constraints beyond the schema: label max length of 64 characters, and sizeLimit as an integer bounded 1–20000 with content required to fit. It reinforces meaning rather than merely restating the schema.

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

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

The description opens with a specific verb+resource ("Persist a new size-limited context slot") and explicitly contrasts with the sibling memory_slot_replace for existing content. An agent can distinguish this from memory_slot_append, memory_slot_get, and memory_slot_list from the text 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?

It clearly routes the agent to memory_slot_replace when content already exists, establishing the create-vs-replace boundary. It does not cover other alternatives or explicitly state when-not to use it, but the primary confusion case is handled.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the failure conditions, the audit-entry side effect, the duplicate-label resolution order (project slot first, revealing the global slot on later reads), and the semantic difference between deleting the context unit and clearing its content.

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 sentences, front-loaded with the action and return value, then failure modes, then the alternative-tool routing. No sentence is 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?

No output schema or annotations exist, yet the description covers the return shape, side effects, error conditions, and edge cases (duplicate labels, retention vs deletion). An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100% and there is a single parameter, so the baseline is 3. The description adds genuine meaning beyond 'Slot label' by explaining cross-slot label collisions and which slot wins on delete.

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 ('Delete the effective slot') plus a side effect ('record an audit entry') and a return value. This clearly separates it from siblings like memory_slot_get, memory_slot_replace, and memory_slot_list.

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

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

Explicitly names the alternative and its selecting condition: 'use memory_slot_replace with empty content to retain it [the context unit]'. It also states when the call will fail (missing or read-only slots) and that seeded defaults are deletable when writable.

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

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

With no annotations, the description carries the full burden and does it well: it discloses the return shape ({success,slot,scope}), the project-over-global precedence rule, and the failure mode ('Invalid labels or missing slots return success:false'). It omits permission/auth requirements, but the core behavioral traits are covered.

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

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

Four tight sentences, front-loaded with purpose and return value, then precedence, error behavior, and routing. Every sentence earns its place 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?

There is no output schema or annotation block, so the description must stand alone and does: it explains return fields, scope precedence, error semantics, and which siblings to use. Nothing an agent needs 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?

Single parameter with 100% schema coverage, so the schema already documents 'label' with an example. The description reinforces 'the effective slot named by label' and references invalid labels, but adds no new syntax or resolution detail beyond the schema, matching the baseline 3.

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: 'Read the effective slot named by label.' It also names the distinguishing operation (read) against its siblings memory_slot_list, memory_slot_replace, and memory_slot_append, so an agent can tell it apart 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?

Explicitly routes to memory_slot_list for discovery and to memory_slot_replace/append for editing, which clarifies context. It does not state an explicit when-not or give a condition-selection rule, so it falls just short of full 5-level guidance.

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

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

With no annotations, the description carries the burden and does so well: it discloses the return shape ({success,slots}), that project-scope slots shadow global ones with the same label, and that unpinned/empty slots are still included. It omits pagination and any permission/auth notes, keeping it 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?

Four sentences, front-loaded with the operation and return contract, then behavior, then usage. Dense but each sentence adds information; slightly packed but 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 and no annotations, the description fully compensates by describing the return payload, shadowing semantics, and inclusion rules. An agent has what it needs to call and interpret the 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?

The tool takes zero parameters, so the baseline is 4. There is nothing to document beyond what the empty schema already conveys.

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 (List) and resource (effective editable memory slots), plus sorting (by label). It distinguishes itself from the sibling memory_slot_get by clarifying it returns the full set rather than a single slot.

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 use case (inspect current context before creating or editing a slot) and the alternative (memory_slot_get when you know the label). It also draws a domain distinction against relevance-ranked memories, which routes the agent correctly.

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

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

With no annotations, the description carries the full burden and delivers: empty content clears the slot, missing/read-only slots and oversized content fail without replacement, project slots shadow global slots, and an audit entry is recorded. This is unusually complete disclosure of side effects and failure modes.

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 failure modes, then alternatives; every sentence adds information. It is dense rather than wasteful, though the packed semicolon clause asks the reader to parse several facts at once.

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 supplies the return shape ({success,slot,size}), the failure conditions, the precedence rule, and the audit side effect, leaving nothing an agent needs in order to call this 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, but the description adds real meaning beyond the schema: content is a full replacement (not a merge) and empty content is a clearing signal, and label resolution has a project-over-global precedence rule.

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 precise verb and resource ('Replace the complete content of an existing effective slot') and immediately scopes it ('existing', 'effective'), which cleanly separates it from memory_slot_create and memory_slot_append named later.

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 memory_slot_append to add text or memory_slot_create for a new label.' The precondition (slot must already exist and not be read-only) is also stated, so both when-to-use and when-not-to-use are covered.

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

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

No annotations are provided, so the description carries the full burden, and it does: it discloses a retention side effect ('Search and expansion record retention access unless trackAccess=false'), the precedence rule ('expansion takes precedence over query'), and truncation reporting. These are real behavioral traits not visible in the 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 core purpose is front-loaded in the first sentence and every subsequent sentence carries distinct information (expansion, escape hatch, side effect, alternative). It is dense and slightly packed, but 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 6-parameter tool with no output schema, the description covers routing, expansion behavior, side effects, and the cross-project escape hatch. Return format is only sketched ('compact results with observation IDs'), which is the one remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond it by stating the precedence of expandIds over query and quantifying expansion ('up to 20 full observations'). The '*' semantics for project/agentId and the retention meaning of trackAccess are largely echoed from 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 ('Search') and resource ('explicit project') and adds the ranking mechanism ('hybrid keyword/semantic ranking') plus the return shape ('compact results with observation IDs'). It explicitly distinguishes itself from the sibling memory_recall, so an agent can route 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?

Names the alternative tool (memory_recall) and the exact condition that selects it ('when you need full, compact or narrative results in one call'). It also gives the when-to-use rule for the '*' cross-project escape hatch, leaving little to inference.

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

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

No annotations are provided, so the description carries the full burden and it does so well: it discloses the mutation of local files and Git state, the prerequisites (Git, writable storage), the returned fields (snapshot ID, commit hash, timestamp, message, counts), and the no-op behavior for overlapping/no-change snapshots. This is rich behavioral context rarely seen without annotations.

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

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

Three tightly packed sentences, front-loaded with the core action and effect before prerequisites, returns, and the alternative. Every sentence carries distinct, useful 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?

Despite having no output schema, the description explains the return payload and the no-op case, and covers prerequisites and side effects. An agent has everything needed to decide whether to call it and what to expect.

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% for the single 'message' parameter, so the schema already documents it as the snapshot description. The description only references 'message' as part of the return payload and adds no syntax or format detail beyond the schema, 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 ('Capture') and resource ('current exported memory state') plus the concrete effect (writes state.json and commits in the snapshot directory's Git repo). It explicitly distinguishes itself from the sibling memory_export by routing JSON-only needs there, so an agent can tell them apart 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?

Names the alternative (memory_export) and the exact condition that selects it ('when you only need returned JSON'). It also states prerequisites (requires Git and writable snapshot storage), giving clear context for when this tool is applicable versus its sibling.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the return envelope {items,total}, the limit semantics, the TEAM_ID/USER_ID dependency, and a failure mode (unavailable team backend returns a setup message). It stops short of stating side-effect safety or pagination behavior beyond limit, 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?

Three tightly packed sentences with zero filler. The core purpose and ordering are front-loaded, and the routing, return-shape, and dependency details follow in descending priority.

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 no-annotation, no-output-schema read tool with one parameter, the description covers everything needed: purpose, ordering, return shape, parameter interaction, auth dependencies, and an error path. Nothing material 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 coverage is 100% and the single parameter is already documented, so the baseline is 3. The description earns above baseline by clarifying the interaction between limit and total (limit bounds returned items; total counts all shared entries), which the schema does not convey.

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 (read) and resource (the configured team's shared memory/pattern/observation feed) plus the ordering rule (newest sharedAt first). It explicitly distinguishes itself from the sibling memory_team_share and from personal-memory tools, so an agent can route 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 clear context: use memory_team_share to publish, and this feed does not retrieve unshared personal memories, which tells the agent when to prefer memory_recall instead. It lacks an explicit statement of when this feed is the right choice over memory_patterns or memory_timeline, so it falls short of full when/when-not 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?

With no annotations, the description carries the full burden and does so well: it discloses the return shape, required TEAM_ID/USER_ID configuration, non-idempotent behavior ('repeated calls create additional shared items and audit entries'), and a known failure mode for itemType=observation. This is rich behavioral disclosure that an agent cannot get from the 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?

Three dense, front-loaded sentences with no filler: purpose first, then side effects and requirements, then routing and the failure caveat. Every sentence carries actionable 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 two-parameter mutation with no output schema, the description covers the return shape, required environment context, side effects, related tool, and a known defect. Nothing an agent needs 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%, so the baseline is 3; the description adds real value by flagging that the enum-like itemType value 'observation' currently fails, which the schema does not convey. It doesn't document itemId syntax 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 and resource ('Publish an existing memory or pattern into the configured team's shared feed') and immediately distinguishes itself from memory_team_feed, the read counterpart. The scope ('team's shared feed') and accepted inputs are unambiguous.

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

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

Provides clear routing context ('Use memory_team_feed to inspect shared items') and a guardrail ('share only content approved for that team'). It stops short of stating explicit exclusions or a true alternative publishing path, 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?

With no annotations, the description carries the full burden and does well: it discloses pagination mechanics (follow nextOffset with offset until null), hard bounds (100 entries, 2 MiB per page), project scoping defaults, and a retention side effect ('Records retention access unless trackAccess=false'). It doesn't describe the observation record shape or error/empty behavior, keeping it below 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 purpose in the first sentence, then layers window/pagination, scoping, retention, and the sibling pointer. Dense and largely waste-free, though a sentence or two overlaps with what the schema already documents.

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 must explain returns, and it does ('Returns observations and pagination metadata') along with pagination bounds and scoping behavior. Covers what an agent needs to call it correctly, with only minor gaps around record contents.

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: the relationship of before/after as the 'full window', the offset/nextOffset continuation loop, and the semantics of omitting project (search all) and trackAccess=false (non-retention analytical reads).

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 ('Retrieve') and resource ('chronological observation window around an ISO timestamp or keyword') with the goal ('reconstruct nearby activity'). It also differentiates from the relevance-ranked sibling by explicitly naming memory_smart_search, so an agent can route 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 clear context: this tool is for chronological/temporal reconstruction, and explicitly names memory_smart_search as the alternative for relevance-ranked discovery. It stops short of enumerating when-not conditions or edge cases, but the primary routing decision is spelled out.

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

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

With no annotations, the description carries full burden and does well: it discloses return shapes, the {success:false,error:'not found'} failure mode, session:null handling, and explicitly states it does NOT change confidence or access counts and checks citation records rather than factual truth. It stops short of naming required auth/permissions, keeping it just below 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 purpose, then return shapes, then error clauses, then the explicit non-guarantee and the sibling pointer. Dense but every sentence carries distinct information; slightly long but no wasted 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?

There is no output schema, so the description must explain returns, which it does in full detail for both memory and observation cases plus errors; combined with the two-param required schema and clear semantics, 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 the baseline is 3, but the description adds meaning: it clarifies that 'project' must be an exact registered identifier and constrains the '*' wildcard to deliberate cross-project use, and that missing id/project returns an error.

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 precise verb and resource: 'Read stored provenance for one memory or observation ID in an explicit project.' It clearly scopes the operation to a single ID and distinguishes itself from content-reading siblings by returning provenance/citation metadata rather than source text.

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 to use '*' only for deliberate cross-project verification, and routes the agent to memory_smart_search expandIds or memory_timeline when it actually wants source content. This is a rare, complete when/when-not/alternative triage.

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