Engram

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

Annotations already declare destructive/idempotent, and the description adds real value on top: what survives closure ('durable memories and journal history remain'), the authorization model ('only this session's member or a human workspace owner may close it; team read access does not grant close authority'), quota consumption, OAuth scope, and idempotent-replay semantics.

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 its sibling contrast, then tight operational facts. It is dense and runs several long sentences, but each line carries non-redundant information; only the return-field enumeration is arguably duplicative of the output 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?

The output schema exists so return values need not be restated, yet the description still covers auth scope, quota, idempotency, failure/re-entry behavior, and the fact that closure is not an erase. 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?

With 100% schema coverage the baseline is 3, but the description adds sourcing and negative-use guidance beyond the schema: where session_id comes from and 'never pass a repo slug', plus how to handle summary when a redacted checkpoint exists. These are practical constraints not present 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 ('atomically closes the session') plus its trigger condition ('at a real completion or handoff'). It explicitly differentiates from the sibling engram_reflect, so an agent can distinguish the two without opening either schema.

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

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

Names the alternative (engram_reflect) and the selecting condition (completion or handoff), tells the agent where to obtain session_id (start/rehydrate/list_sessions), and specifies when closure does not take effect ('a missing checkpoint or failed save leaves it active'). Guidance is explicit rather than 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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds genuinely new operational facts: it records retrieval telemetry without copying knowledge, consumes the workspace daily call quota, and requires the memory:read OAuth scope. Quota consumption and auth scope are exactly the behavioral traits annotations cannot express.

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

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

Purpose and sibling differentiation are front-loaded, followed by parameter semantics and operational constraints. It is dense and jargon-heavy ('transfer lessons and quality gates'), but every sentence carries information and nothing is repeated from the schema or annotations.

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

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

With an output schema present, return values need not be re-explained, and the description still notes the Markdown/ranked-memory shape. Annotations cover the safety profile, the schema covers all 7 parameters, and quota, auth, and telemetry are disclosed — 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 real semantic value beyond the schema: target_repo memories are excluded from the source search, source_repos restricts rather than expands scope, and include_public supplements sparse private results. These clarify the interaction between parameters that the schema describes only individually.

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

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

The opening sentence states a specific verb and resource ('Reuse a lesson solved in another repository') and names the two sibling tools it differs from (engram_recall, engram_smarter). An agent can tell exactly what this tool does and how it differs from the closest alternatives 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?

The trigger condition ('before rebuilding a shared pattern') and the explicit contrast with engram_recall/engram_smarter give clear context for selection. It stops short of stating when to prefer recall or smarter over this tool, so the routing is implied rather than fully enumerated.

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?

Far exceeds the annotations (destructiveHint, idempotentHint, readOnlyHint=false) by disclosing exactly what gets destroyed (free-text history/checkpoints/task/context of referencing sessions, outcomes, links, jobs, linked evidence), what survives (shared entities still referenced), idempotency semantics (repeat execution returns a minimal receipt), a content-fingerprint safeguard against replay repopulation, and quota consumption.

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

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

Front-loaded with the core purpose and alternative, then proceeds through prerequisites, dry-run workflow, and scope exclusions. It is dense and long, but nearly every sentence carries a distinct operational fact (irreversibility, destruction scope, fingerprint safeguard, quota, out-of-scope stores), so waste is minimal.

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 high-stakes destructive operation, the description covers permissions, irreversibility, exact destruction scope, surviving data, execution workflow, idempotency behavior, and explicit out-of-scope exclusions. With an output schema present, return-value detail is optional, and the description is more than complete.

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

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

Schema description coverage is 100%, so dry_run, memory_id, and confirmation are already documented in the schema, including the exact confirmation format and the warning not to substitute a repo name. The description restates this workflow (dry_run default true, execute with the reviewed ID) but adds little syntax or meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Preview or permanently erase one private memory and its explicit derived patterns from the live database') and explicitly distinguishes itself from the sibling engram_retract_memory. An agent can tell exactly what this does and how it differs from alternatives without opening the schema.

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

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

Explicit when-to-use ('Inspect it first'), how-to-execute ('Execute only the reviewed ID using dry_run=false and confirmation="delete:<memory_id>"'), the alternative it is not ('Unlike engram_retract_memory, execution cannot be undone'), and prerequisites ('Requires a human workspace OWNER API key; OAuth agents and member keys cannot erase'). Exclusions are also stated ('Does not delete independent memories or unrelated sessions').

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

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

Annotations already declare a safe read profile, but the description adds substantial operational context beyond them: OAuth scope memory:read, consumption of the workspace daily call quota, the bounded nature of the search (not a full memory export), the broadening behavior, and the explicit guarantee that it does not edit knowledge.

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 and the key contrast to siblings before moving to bounds, fallback behavior, and operational notes. It is dense but nearly every sentence carries distinct, decision-relevant information, with only minor redundancy against 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?

An output schema exists, so return values need not be explained, yet the description still sketches the JSON shape (repo/file/total, up to 21 entries). Combined with annotations, a full schema, and clear scope/fallback/quota notes, 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 description coverage is 100%, so all three parameters are already documented in the schema. The description restates that repo is required and that file/task refine the search without reading files, but adds little syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('audit repository knowledge by category'), enumerates the categories, and explicitly distinguishes itself from engram_recall and engram_smarter by explaining the per-category sampling vs. a single task-ranked list. An agent can differentiate this from all 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?

Names the alternatives (engram_recall, engram_smarter) and the condition that selects this one (coverage review across five separate category arrays). It also states when broadening to workspace/public occurs and that empty results are valid, leaving nothing to inference.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds context annotations cannot express: it consumes daily call quota, requires the memory:read OAuth scope, and that member_id is a filter rather than authorization. It also discloses pagination ordering (newest-started-first) and the cursor contract.

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

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

Purpose and the sibling contrast are front-loaded, then scope, filters, pagination, quota and auth follow in a logical order. Dense but each sentence carries distinct operational information; it runs slightly long for a list 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 7 optional params, an output schema, and full annotations, the remaining agent questions are answerable: what it returns, how to page, what it costs, and what auth it needs. Nothing needed 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 description coverage is 100%, so every parameter is already documented; the description largely restates defaults (scope=mine, limit 20/50) and the member_id+workspace coupling that the schema also states. Baseline 3 is appropriate since the schema carries the parameter burden.

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 ('lists bounded metadata' of sessions) and gives the concrete job it serves: 'Find an exact session_id before recovery, closing or a handoff.' It explicitly separates itself from the nearest sibling, engram_rehydrate, 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 (engram_rehydrate) and the discriminating condition (bounded metadata, no journal replay, no session mutation). It also warns that empty results are valid, preventing a retry loop.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), and the description adds value beyond them: no arguments required, the shape of the response, a quota consumption warning ('Consumes workspace daily call quota'), and the required OAuth scope (memory:read). That is exactly the operational context annotations cannot express.

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: purpose/trigger first, negative boundaries and alternatives second, operational facts (quota, auth) last. No filler, no repetition of the 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?

For a zero-argument, read-only audit tool with an output schema and full annotation coverage, the description supplies everything an agent needs: when to call it, what it returns, what it does not do, siblings to prefer, quota cost, and auth scope. Nothing material is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description explicitly confirms 'Takes no arguments', which is consistent with the empty schema but adds little beyond it.

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 action (audit adoption) and the concrete artifact returned (JSON with memory-bank breakdowns, learning-loop activity, proof points, benchmark checklist). This is clearly distinguishable from siblings like engram_recall and engram_report_outcome.

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 triggering conditions ('before a rollout', 'when checking whether the workspace is using memory'), an explicit non-use statement ('Does not change knowledge or run a benchmark'), and names alternatives with their own use cases (engram_setup for onboarding, engram_recall for task knowledge).

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?

Beyond the annotations (readOnly/idempotent/non-destructive/closed-world), it discloses that retrieval telemetry is recorded without editing knowledge, that the call consumes workspace daily quota, to stop on quota errors, retry only transient failures, and the required OAuth scope memory:read. It also describes the zero-match behavior, which is behavioral, not schema, information.

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: the routing comparison comes first, then return shape, then guardrails. Every sentence carries information, though the embedded JSON example and the compression of quota/OAuth/telemetry rules into run-on clauses make it heavier than needed.

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

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

With an output schema present, the description needn't detail returns, yet it still summarizes ranked memories/ids/trust-conflict signals and retrieval hints. Filters, depth/limit interaction, auth scope, quota behavior, and fallback on zero matches are all covered — nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters with enums and defaults. The description adds only light framing ('repo/type/tags narrow the question; limit overrides the depth budget'), much of which duplicates the limit/depth interaction already stated 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+resource: answering one concrete question from authenticated workspace/public memory. It explicitly distinguishes itself from engram_smarter (question-specific evidence, no checklists) and engram_get_context (one ranked list vs. category samples), so an agent can pick it apart 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 the decision-time/debugging context ('before deciding or debugging'), names two alternatives with the conditions that select them, and routes session recovery to engram_rehydrate. It also tells the agent what to do when there are no matches (deepen or rephrase rather than assume).

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

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

Annotations already declare readOnly=false and idempotent=false, but the description goes further with quota consumption, required OAuth scopes, session-state behavior ('leaves the session open'), and a retry/duplication warning. This is exactly the operational context annotations cannot carry.

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

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

Front-loaded with purpose, then constraints, then operational caveats; every sentence carries distinct information for a 9-parameter mutation tool. It is dense rather than padded, though the OAuth/quota sentence stack is heavy relative to the two guiding sentences at the top.

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?

Output schema exists, yet the description still sketches the return shape (stored/skipped counts, outcomes, next actions), and it covers quotas, auth scopes, session persistence and non-idempotent retries. An agent has everything needed to call it safely and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the cross-parameter constraint that at least one of four fields must be supplied (required list is empty), and the subtle store=false semantics that only affect learning storage while journal/outcomes/feedback still persist.

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 ('Checkpoint a milestone or handoff') plus the downstream purpose ('later recovery with engram_rehydrate'). It explicitly distinguishes itself from engram_store and engram_report_outcome, so an agent can route correctly without opening sibling 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 precondition ('Supply at least one of summary, learnings, used_memories or feedback') and names the alternatives with their selecting conditions: engram_store for one lesson, engram_report_outcome for one outcome. It also states what this tool does that the alternatives don't (bundled journal checkpoint).

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

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

Adds real behavioral context beyond the annotations: closed/teammate journals are read-only and never reopened, repeated recovery appends events rather than erasing history, daily call quota is consumed, and OAuth scopes are memory:read and session:write. These are consistent with destructiveHint=false, idempotentHint=false and readOnlyHint=false, but the description does not detail error modes or response shape beyond the return contents.

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 sibling differentiation, then mechanics — a sensible ordering with no filler sentences. It is dense and long, but each sentence carries operational information; slightly tighter grouping of the recovery preconditions would improve scannability.

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

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

For an 8-parameter, zero-required, open-world-false recovery tool with an output schema present, the description covers purpose, alternatives, preconditions, disambiguation, quota and auth — everything needed to invoke it correctly. Return-value detail is correctly left to the output schema.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description goes further by explaining session_id's selection semantics (accessible workspace session; closed/teammate journals readable but not writable) and since's role (filters events after session selection). The remaining parameters (repo, task, depth, reason, project, agent_tool) are left 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+resource ('Recover interrupted work after compaction, resume or lost context') and immediately names what it returns (Markdown checkpoints, decisions, gotchas, open loops, recent events). It explicitly distinguishes itself from three siblings (engram_start, engram_recall, engram_smarter), so 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?

Gives explicit when-to-use-vs-alternatives ('unlike engram_start... unlike engram_recall or engram_smarter...'), states the preconditions for automatic recovery (one active journal for member/repo/OAuth connection within the window), and handles the 409 multi-match case by routing to list_sessions. Fallback behavior when nothing matches is also stated.

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

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

Annotations only declare the safety profile (readOnly=false, idempotent=false, destructive=false). The description goes well beyond: repeats accumulate outcomes and shift confidence, only accessible workspace/public memories are reportable, the call consumes daily quota, and OAuth scope outcome:write is required. It is also consistent with idempotentHint=false rather than contradicting 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?

The core action is front-loaded and most sentences carry distinct payloads (mechanics, restrictions, retry warning, alternatives, quota, auth). It is denser than ideal with several constraints packed into the second paragraph, 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 6 params and an output schema, the description covers everything an agent needs: auth scope, quota cost, mutation/idempotency behavior, eligibility restrictions, and sibling routing. Return values are handled by the output schema, so no gap remains.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by tying semantics to behavior: exact memory_id (not a name/URL/text), detailed evidence, failure_reason's meaning, and that success raises confidence. It does not add syntax beyond the schema, but it reinforces how parameters are meant to be supplied.

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

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

States a specific verb and resource ("Record whether a recalled memory helped") plus the confirmation return. It also separates itself from engram_reflect ("batch milestone outcomes") and engram_store ("verified replacement"), so an agent can route without opening a sibling 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 (record a recall outcome with the exact memory_id and detailed evidence), when-not (do not blindly retry because repeats mutate confidence), and named alternatives with the conditions that select them (engram_store with supersedes_memory_ids, engram_reflect for milestones).

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

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

Goes well beyond the annotations, which only cover readOnly/idempotent/destructive/openWorld. The description discloses authorization requirements, quota consumption, the 409 anti-revival behavior, the already-active idempotent no-op, the retained source-dependent history rule, and the OAuth scope memory:write.

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 the key sibling contrast, then packs edge cases into tight sentences. Dense but every sentence carries distinct information; only minor cost is the packed final 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?

An output schema exists, yet the description still names the return fields (memory_id, ACTIVE status, already_active). Combined with auth, quota, and error-path coverage, 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% and the single parameter is fully documented in the schema ('exact id from a recalled memory...'). The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('make an explicitly retracted private memory available again') and immediately distinguishes itself from engram_store, the nearest sibling, by contrasting restore-original vs. store-new behavior. An agent can route between the two without opening either schema.

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

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

Names alternatives and their conditions explicitly: engram_store for matching retired content (which returns 409), the separate replacement-review workflow for confirmed replacements or SUPERSEDED state, and the fact that permanently erased IDs cannot be restored. Preconditions (creator or human workspace OWNER) are stated up front.

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

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

Goes well beyond the annotations: names the returned JSON fields (memory_id, RETRACTED status, already_retracted), the authorization model (creator or human workspace OWNER; team read access is not write authority), the retrieval effect (excludes the memory and source-dependent patterns), recovery semantics, quota consumption, and the OAuth scope memory:write. This is unusually rich disclosure for a mutating 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 purpose and the two sibling comparisons, and every sentence carries information (permissions, idempotency, exclusions, quota). However, some phrasing is dense jargon ('source-dependent patterns', 'suppresses free text in referencing journals') that could cost clarity for marginal compression.

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

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

An output schema exists and annotations cover the safety profile, yet the description still supplies the permission model, idempotency behavior, exclusion cases (public-bank/superseded records), and quota/auth requirements. 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 sourcing guidance not present in the schema ('Get memory_id from recall/context') and reinforces the non-sensitive 1–1000 character reason constraint. It adds genuine 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 ('Withdraw an exact private memory') and immediately distinguishes itself from two siblings: engram_store with supersedes_memory_ids (no replacement needed) and engram_delete_memory (this one is reversible). An agent can differentiate 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 names alternatives and the conditions selecting them ('Unlike engram_store...', 'Unlike engram_delete_memory...'), tells the agent where to source memory_id (recall/context), and guides next steps after the operation (start a clean session or restore the source). No inference required.

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

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

Annotations already declare this safe (readOnly, idempotent, non-destructive), yet the description still adds quota behavior ('Consumes workspace daily call quota; exhaustion requires reset or a plan change'), the required OAuth scope (memory:read), and the absence of pagination/installation. A mildly useful return-shape summary is also given even though an output schema exists. Strong additive disclosure above the annotation floor — though quota language is terse about how much each call costs.

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

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

Purpose and return shape are front-loaded, then exclusions/alternatives, then hint semantics, then quota and auth — a logical order with no filler sentences. It is dense and slightly overpacked (four clauses in the quota/auth tail), but 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?

Covers the areas an agent actually needs to call this correctly: what comes back, that pagination/installation are out of scope, the sibling routing, the quota cost, and the auth scope. With an output schema present, it is not obligated to detail return values, so nothing material 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 schema already documents all seven parameters in detail; the baseline is 3. The description's only param-relevant contribution — 'project names the work; repo scopes activation guidance, falling back to project when omitted' — largely restates what the schema already says about repo/project, so it adds little 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 ('Explain onboarding and inspect the authenticated workspace') and immediately frames the trigger ('when an agent needs setup guidance'). It explicitly differentiates itself from siblings by naming engram_start, engram_rehydrate and engram_proof with their distinct purposes, so an agent can route 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 when-to-use (setup guidance) plus explicit exclusions ('Does not configure the machine, open a working session or edit knowledge') and names three alternatives with the condition that selects each (begin work, recover it, audit adoption). This is the full when/when-not/alternatives triad.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, but the description adds non-obvious operational facts: it 'reads workspace/public knowledge without installing or executing anything', it 'consumes workspace daily call quota', and it requires OAuth scope 'memory:read'. Quota and auth disclosure are exactly the behavioral context annotations cannot convey.

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

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

Front-loaded with purpose, then parameter behavior, return shapes, alternatives, then side effects and auth. Dense but every sentence is actionable. Minor redundancy in enumerating return fields that the output schema already covers.

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

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

Given the single optional parameter, an output schema, and full annotations, the description covers everything an agent needs: purpose, both invocation modes, failure behavior, alternative tools, quota cost, and auth scope. No gaps for this tool's complexity.

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

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

Schema coverage is 100% and the single parameter's description already documents the omit/empty-string-to-list behavior and the count=0 unknown-name result. The description largely restates this, adding only the 'skill:' prefix example, which the schema already shows via 'skill:deployment'. 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 — 'Find a procedural checklist before a repeatable task' — and immediately distinguishes itself from siblings by naming engram_recall (project facts) and engram_smarter (task-based guide selection). An agent can tell what this does and where it fits 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?

Gives explicit routing rules: the no-argument/empty-string path for listing, named path for loading, and two named alternatives with the conditions that select them ('Use engram_recall for a project fact and engram_smarter for task-based guide selection'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint/idempotent/non-destructive, but the description adds behavior beyond them: it records retrieval and session telemetry 'without editing knowledge', consumes the workspace daily call quota, and requires the memory:read OAuth scope. Quota and auth requirements are exactly the operational context annotations cannot express.

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 differentiators, then the example, then operational notes — every sentence carries information. It is dense and leans on jargon like 'materially different task' and 'retrieval hints', which slightly slows parsing, but there is little true 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 7-parameter, single-required-param retrieval tool with an output schema, the description covers the remaining gaps: session semantics, quota cost, auth scope, and telemetry side effects, while leaving return-format explanation to the output schema. 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 cross-parameter semantics the schema states only in isolation: 'context states the whole goal; repo/file focus retrieval without reading local files. limit overrides depth; include_skills=false suppresses checklists.' It clarifies the interaction between depth/limit and the meaning of repo/file, though it does not add format detail beyond the schema's own examples.

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 ('brief a materially different task within the same session') and immediately positions itself against two named siblings, engram_recall and engram_get_context, explaining what it does differently (goal-focused memories plus optional checklists; ranked evidence rather than category samples). An agent can distinguish it from every other retrieval tool without opening a schema.

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

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

Explicitly names the alternative tools and the condition that selects them: 'Use engram_start to begin work and engram_rehydrate for lost context.' It also supplies a concrete example invocation showing the intended context shape, which removes ambiguity about when this tool is the right entry point.

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

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

Adds substantial behavior beyond the annotations (which only say non-readonly, non-destructive, non-idempotent, closed-world): it discloses that a session event is recorded and repeats may add events or open another session, that it consumes a workspace daily call quota whose exhaustion requires a reset/plan change rather than retries, the required OAuth scopes (memory:read, session:write), and the 409 ambiguity outcome.

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 sibling differentiation before dense operational detail. Three paragraphs for a 13-parameter tool is proportionate, and each sentence (quota, OAuth, 409, session reuse) carries distinct information; density is high but not padded.

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

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

With an output schema present, return values need no explanation, and the description still covers the substantive gaps an agent faces: auth scopes, quota limits, non-idempotent session-event recording, 409 ambiguity handling, and the context-override precedence. Nothing needed to invoke it correctly appears 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 interaction semantics the schema lists only in isolation: context overrides the generated project/market/role/stack/task query, new_session=true deliberately opens a separate journal versus default reuse of one eligible active journal, and session_id disambiguates parallel work. This is more than restatement, though a fair amount still duplicates the schema prose.

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

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

States a specific verb ('Begin meaningful work') plus resource ('repository') and enumerates the payload (session id, ranked private/public memory, workspace guidance, optional checklists). It also explicitly names and contrasts two siblings — engram_smarter (task switch) and engram_rehydrate (recovery) — so an agent can disambiguate 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 explicit when-to-use ('Use once when beginning work'), names both alternatives with their selecting conditions, and adds edge-case routing: supply session_id for parallel work, use list_sessions and pick an exact id when automatic selection returns 409, and new_session=true for a deliberately separate journal.

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

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

Annotations declare only the safety/idempotency profile; the description adds genuinely new behavior: dedup that can boost confidence so retries have side effects (consistent with idempotentHint=false), quota consumption, rejection of secrets/low-quality content, required OAuth scope memory:write, and the fact that superseding retains history rather than deleting. This is exactly the kind of context annotations cannot carry.

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

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

Purpose and sibling routing are front-loaded in the first sentence, followed by the correction workflow, side effects, and auth scope. Every sentence carries distinct information, though the second paragraph strings several unrelated facts together and 'returns a confirmation' is mildly redundant given an output schema exists.

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, non-idempotent write tool with quota and auth requirements, the description covers the correction model, dedup side effects, rejection policy, and required scope, and it correctly defers return-value detail to the existing output schema. Nothing an agent needs before calling is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond it by explaining how two parameters interact (content must hold the complete replacement when supersedes_memory_ids is supplied, and change_reason explains that replacement), which is relationship-level meaning the per-field schema text 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 ('Save one durable lesson'), plus scope ('privately for future workspace agents'), and explicitly names the siblings it is not (engram_reflect, engram_report_outcome). An agent can distinguish it from the other 16 engram_* tools 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 when-to-use routing: single lesson here, milestone with several lessons/outcomes via engram_reflect, assessment of an existing memory via engram_report_outcome. It also spells out the correction path (complete replacement in content + old ids in supersedes_memory_ids), which is a distinct usage mode.

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