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

Goes well beyond the annotations: discloses that duplicates are rejected rather than created (concretizing idempotentHint), that contradictions accelerate the contradicted memory's decay, that superseded or archived evidence stops counting, and that a relation_id is returned. Auth requirement is also stated. These are real side effects and constraints an agent could not infer from the 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 core purpose, then mode semantics, then side effects and auth — a sensible order. Dense but every clause carries information; only the parenthetical re-explanation of supports/contradicts is mildly redundant with the relation schema description.

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 write tool with no output schema, the description covers return value (relation_id), failure mode (duplicate rejection), downstream consequences (decay acceleration, superseded evidence), and auth. Nothing essential for a correct call 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 genuine meaning: it clarifies the direction of the evidence_id → memory_id arrow and what `source` does for sourced_from. It does not explain `confidence` or `agent_id`, leaving those 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 and resource ("Record evidence for a memory") and spells out the two modes of the operation (memory→memory relations vs memory→external source provenance). An agent can see this is a write of a single relation, unlike the read-oriented get_memory_evidence sibling, but no sibling is named explicitly, so it falls short of a 5.

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

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

Clear conditional guidance per mode: relation="supports"/"contradicts" link evidence_id → memory_id, relation="sourced_from" requires `source`. Prerequisites (agent key auth, source required) are stated. It does not, however, say when an agent should prefer this over save_memory or get_memory_evidence, or when not to use 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?

Discloses behavior beyond the annotations: unknown IDs are silently skipped, the response reports the confirmed row count, and repeated calls double-increment. The non-idempotency note largely mirrors idempotentHint=false, but the unknown-ID handling, return-count behavior, and auth requirement are genuine additions.

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 action and effect, then side effects, then auth. No filler and every clause carries information an agent needs.

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

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

With no output schema, the description still tells the agent what comes back (a count of confirmed rows) and covers the auth requirement and skip behavior. Nothing material is missing for a 3-parameter write tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces batch semantics ('one or more memories') and the auth requirement for api_key, but adds nothing about agent_id and no format details for 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 and resource ('confirm that one or more memories have been read') plus the exact effect (increments access_count, sets last_read_at). It is clearly distinguishable from siblings like search_memory, get_memory_evidence, or record_outcome, which do not confirm reads.

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 for when to call it (marking memories as read after the agent consumes them) and the auth precondition when a registered key exists. It does not name an alternative tool or state a when-not-to-use case, so it falls 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?

Although annotations already declare destructive and idempotent behavior, the description adds substantial operational context: what is removed, that search and injection stop working, that a snapshot is written first, that restore is outside this tool, auth requirements, and NotFound behavior on repeat deletion. No annotation is contradicted.

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 well front-loaded, starting with the core action and consequences. Every sentence contributes useful behavioral or routing information without repetition.

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 mutation tool with no output schema, the description covers the important missing context: side effects, recoverability, auth behavior, repeat-call behavior, and the correct alternative for permanent deletion. An agent has enough information to invoke it correctly and avoid mistakes.

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 parameter meanings are already documented in the input schema. The description reinforces memory_id and auth requirements but does not add syntax or format details beyond the schema, making the baseline 3 appropriate.

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

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

The description names a specific verb and resource: soft-delete one memory by ID. It precisely states the scope and consequences, including removal of the live row, FTS entry, and evidence relations, and explicitly distinguishes this from forget_memory.

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 for irreversible GDPR-style purges, forget_memory, and explains that restoration is available only through the CLI rather than this MCP tool. This gives clear when-to-use and when-not-to-use 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?

Goes well beyond the annotations by disclosing the fallback path (degrades to rule-based, surfaced via fallback_used/fallback_reason), the auth requirement when an agent key is registered, and that invalid occurred_at errors rather than silently dropping. It does not address non-idempotency (idempotentHint=false) — nothing warns that repeated calls with auto_save=true may produce duplicate memories.

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 first, then the mode distinction, then the write/auth caveat, then the occurred_at rule. Each sentence carries information, though the mode explanation partially duplicates the schema and could be trimmed.

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

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

For a 7-parameter, non-idempotent tool with no output schema, the description covers the decisions that matter: mode selection, fallback reporting, auth on write, and error semantics. The only meaningful omission is duplicate/retry behavior after a save.

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 mode, assistant_text, api_key, and occurred_at semantics; the description largely restates these rather than adding syntax or constraints. The one genuinely additive note is the auth precondition tied to auto_save, which lifts it just to baseline rather than above.

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

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

Opens with a specific verb + resource ("Extract structured memories from conversation text") and immediately qualifies the two operating modes, so the agent knows exactly what the tool produces. It does not name or contrast any sibling (save_memory, add_evidence), so an agent still has to infer why to extract rather than save directly.

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

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

Gives clear conditions for the key branch: rule mode for keyword matching, llm mode for semantic understanding over full context with optional assistant_text, and notes auto_save triggers a write. It stops short of saying when to pick this tool over save_memory or when extraction is unnecessary.

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 annotations: discloses that history snapshots and orphaned compliance rows are purged, that only a content-hash audit entry remains, that the operation is irreversible, that Must-priority memories are excluded unless allow_must=true, and that auth is per-agent API key with no admin tier at the MCP layer.

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: scope, sibling contrast, destructive effects, workflow, and auth in a tight block. Slightly long with some redundancy against schema descriptions (dry_run default, allow_must) but every sentence carries operational weight.

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 critical concerns for a destructive, 12-param, irreversible tool with no output schema: what gets destroyed, irreversibility, preview workflow, exclusion of Must memories, and auth. Return-value shape is not explained, but for a preview/execute purge tool the key facts are 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; the description adds value by grouping bulk criteria (namespace/namespace_prefix/source_agent_id/tag/memory_type/before_days), flagging memory_id as mutually exclusive with the criteria, and explaining the dry_run default and allow_must override. Marginal gain over schema because these details are largely restated.

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 (permanently erase / purge), the resource (one memory by id or a bulk set), and explicitly contrasts with the sibling delete_memory. An agent can distinguish it from delete_memory without opening either schema.

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

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

Gives explicit selection criteria (single id vs bulk criteria fields), names the alternative (delete_memory) and how this differs, and prescribes a two-step workflow (preview with dry_run, then execute). 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 readOnlyHint=true, idempotentHint=true and openWorldHint=false, so 'Read-only; ... does not change compliance records' largely restates them. The genuinely additive part is the aggregate-vs-single-session behavior and the default limit; 'returns JSON' is generic and, with no output schema, gives no insight into report shape.

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 compact sentences with the resource and payload front-loaded, followed by the routing rule for the optional parameter. No filler, though the trailing read-only clause is partly redundant with the annotations.

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

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

For a zero-required-parameter read-only report tool with annotations covering safety and no output schema, the description covers what the report contains, both invocation modes, the default limit, and the absence of side effects. A little more on report structure would make it fully self-sufficient.

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 67% and the undocumented parameter is limit; the description compensates by stating the default of 10 and its role in the aggregate filter. The two documented parameters (agent_id, inject_session_id) are also explained in behavioral terms (single vs aggregate), adding context beyond the terse schema 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 and resource ('Get a compliance report for injection sessions') and clarifies the payload ('follow/violation rates for MUST memories'). It is discernible from get_effectiveness_report, but nothing in the text distinguishes it from the sibling report_compliance, so sibling differentiation is only partial.

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 invocation guidance: pass inject_session_id for a single session, or omit it for an aggregate filtered by agent_id and limit (default 10). What's missing is any exclusion, e.g. when to prefer report_compliance or get_effectiveness_report instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds useful context beyond annotations: judgments are automatic, sourced from record_outcome, independent of manual compliance reporting, and returned as JSON without changing records.

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 compact and front-loaded, starting with the core purpose and then adding the automatic/manual distinction, parameter defaults, and read-only behavior. Every clause contributes useful selection or invocation context.

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 enumerates the rate categories and states that the response is JSON. It could be slightly more complete about the reporting window or whether rates are counts versus percentages, but it provides enough for correct selection and invocation.

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

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

Schema coverage is only 50%, so the description must compensate for the undocumented parameters. It explains that agent_id optionally filters the summary and that limit defaults to 10, adding meaning beyond the schema for both 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 states a specific verb and resource: get automatic effectiveness judgments for injected memories. It names the exact metrics (useful/neutral/harmful/insufficient_context rates) and distinguishes the tool from manual compliance reporting by saying it is independent of report_compliance.

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 positions the tool as the automatic effectiveness counterpart to manual report_compliance, which helps an agent choose between the two. It does not explicitly state when not to use it, but the alternative and context are clear.

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 readOnlyHint/idempotentHint annotations, the description discloses two things annotations cannot: missing or pruned evidence returns an empty chain rather than erroring, and agent auth is required when a registered key exists. It stops short of describing pagination or chain size limits, but the behavioral payoff is 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?

Three compact sentences, front-loaded with the core action and followed by the use case and edge-case behavior. Slightly dense phrasing ('Read-only grounding: lets an agent...'), but no wasted text.

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

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

With no output schema, the description usefully sketches the return shape (L0 trace rows plus evidence profile, empty chain when evidence is missing) and covers the auth precondition. An agent has enough to invoke this correctly; only deeper return-format detail is absent.

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

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

Schema description coverage is 100%, so memory_id, agent_id, and api_key are already documented in the schema. The description reinforces the auth condition but adds no new syntax or semantics for memory_id beyond what the schema states. 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: retrieves the raw-evidence chain (L0 trace rows) plus evidence profile for a memory. This is clearly distinguishable from siblings like add_evidence (writes evidence) and search_memory (searches), since it is about expanding provenance for a known memory_id.

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 concrete usage context: 'read-only grounding: lets an agent quote the original session text and name its sources,' which tells the agent when this tool is the right pick. It does not explicitly name an alternative tool or state exclusions, so guidance is clear but not fully comparative.

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: says imported skills enter the review inbox unless approve=true, that repeating the same import creates duplicates (the concrete consequence behind idempotentHint=false), and that agent auth is required when the agent has a registered key. The auth and inbox-routing details can't be inferred from the annotation flags.

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 the action and parsing rule, then side effects, then auth. Every sentence carries operational information; nothing is redundant 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 write tool with no output schema, the description covers creation behavior, skip rules, duplicate risk, inbox routing, and auth. It omits what the call returns (counts, per-skill errors) and how namespace scoping affects results, which leaves a modest 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 parsing semantics not in the schema: sections without steps are skipped, and headings define skill boundaries. It covers markdown/approve/auth but says nothing about namespace, fallback_title, or agent_id, which keeps 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?

Specific verb + resource ('Import skills from a Markdown SOP document') with the parsing model spelled out (headings become skills, trigger:/verification: metadata, list-item steps). This clearly separates it from siblings like save_memory or extract_memories, which create skills from other sources.

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 applicable input form (Markdown SOP document) and discloses the routing decision point (review inbox unless approve=true) plus a duplicate-import caveat. It stops short of naming an explicit alternative such as extract_memories for non-SOP text, so it does not reach a full 5.

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

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

Richly goes beyond the annotations: discloses that a no-op returns status 'skipped' rather than an error (clean session, below friction threshold, no evidence), that repeat calls for the same session/evidence are deduped, that agent auth is required when a key is registered, and that the classification is rule-floor plus optional LLM judge with recording identical to record_outcome. The only mild tension is 'deduped' versus idempotentHint=false, but that is a storage-level dedup of the record rather than a claim the call is a pure read-replay, so it does not rise to contradiction.

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?

One dense but well-ordered paragraph: purpose, then the evidence-passing contract, then the skipped/dedup/auth caveats. Every clause carries a distinct fact, though the run-on middle sentence about the rule-floor-plus-LLM-judge pipeline could be broken out for faster 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?

For an 8-parameter, non-read-only, auth-bearing tool with no output schema, the description covers the essentials: what gets recorded, the skipped-not-error return, dedup, and auth. Only the successful return payload (beyond the 'skipped' case) is left implicit, which is a small gap given no output schema exists.

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, including the per-field evidence semantics and judge_context's "data not instructions" note. The description reinforces that `evidence` must be caller-precomputed and that the judge is optional, but adds no format or constraint detail beyond the schema. Baseline 3 applies when the schema carries this much weight.

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 ("Classify and record a task outcome") plus an explicit scope constraint ("from host-provided evidence rather than raw transcript text"). It names the sibling it mirrors (record_outcome) and the pipeline it reuses (the Claude Code Stop hook's `outcome --infer`), so an agent can place it precisely among 19 siblings.

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

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

Explicitly states the selecting condition: use this for hosts whose event model doesn't emit a Claude-Code-shaped JSONL transcript (e.g. dsh/Cordis). It also tells the caller what to supply (pre-computed friction counts, terminal state). It stops short of a clean routing sentence such as "if you already have a classified outcome, call record_outcome instead," leaving that inference to the reader.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, openWorldHint=false), yet the description still adds real value: oldest-first ordering, the absence of pagination with silent truncation of older items, and the agent-auth requirement. Those are the exact behavioral traits an agent cannot get from the annotations or schema.

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

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

Three tight sentences, front-loaded with the resource and ordering, then the safety profile, then the truncation caveat. Zero filler and nothing repeated from the annotations.

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

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

For a four-parameter read tool with full schema coverage, the description covers ordering, filtering, default page size, the truncation hazard, and auth. No output schema exists, and the return concept (pending review items) is stated clearly enough not to need one.

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 by noting the default limit of 20 and clarifying that there is no offset parameter at all. It also restates the conditional auth requirement for api_key in context.

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

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

States a specific verb and resource ("List memories pending human review") plus the sort order, which is enough to separate it from search_memory or review_memory at a glance. It never explicitly names a sibling, so the differentiation is inferred rather than stated.

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

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

Gives clear operating context: read-only, optional namespace/limit, and a warning that there is no offset so a full page silently drops older pending items. That warning effectively tells the agent when this tool is unsafe to trust naively, though it never says which alternative to use instead.

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

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

Goes well beyond the annotations by disclosing dedup semantics ('repeated calls for the same session/outcome are deduped'), the downstream effect on future tasks via lessons, and the conditional auth requirement for agents with registered keys. The dedup note sits slightly in tension with idempotentHint=false, but the scope is narrower (same session AND same outcome) so it reads as refinement rather than contradiction.

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, front-loaded with the core action and trigger, then escalating to consequences, dedup, and auth. Every sentence carries distinct information, though the auth sentence could arguably be folded into a prerequisite note rather than trailing the description.

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 11 parameters, no output schema, and permissive annotations, the description does the important work: it explains the write's downstream consequences, the dedup behavior, and the conditional auth requirement. It leaves return-value shape unexplained, but for a fire-and-record tool that is a minor gap.

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

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

Schema description coverage is 100%, so all 11 parameters are already documented, which sets the baseline at 3. The description adds real semantics for status enumeration and for how cause feeds lesson generation, but it says nothing about task_type, skill_id, namespace, or agent_id beyond what the schema already provides.

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 the outcome of a task you just executed') plus the memory subsystem (episodic memory), which separates it from add_evidence and infer_outcome. It does not explicitly name a sibling to contrast with, so the 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?

'Call this after finishing a task so past successes and failures can inform future sessions' gives a clear trigger point in the workflow. It stops short of saying when NOT to use it or naming infer_outcome/add_evidence as alternatives for related cases.

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 past the annotations: discloses item-by-item processing where a bad item is logged and skipped while the call still succeeds, warns that updated/total counts in the response must be checked, and notes the compliance-enabled-server and no-API-key requirements. Annotations only say non-readOnly, idempotent and non-destructive; the partial-success semantics are the genuinely useful addition.

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 session_start linkage are front-loaded, and each subsequent sentence adds distinct information (what to report, partial-failure behavior, prerequisites). It is dense but slightly overloaded, packing prerequisites and response-checking into a single block rather than separating them.

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

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

With no output schema, the description compensates by telling the agent what the response contains (updated/total counts) and that it must be inspected. Prerequisites, auth expectations, and partial-failure behavior are all covered, so nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and both parameter descriptions already explain inject_session_id and the reports list, so the schema carries the load. The description restates these ('a previous injection session returned by session_start', 'optional evidence') rather than adding new syntax, batching limits, or constraints, so baseline 3 applies.

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

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

States a specific verb and resource ('Report compliance') and anchors it to a concrete source of input ('a previous injection session returned by session_start'), then clarifies the action as marking injected memories followed or violated. That distinguishes it from the read-side sibling get_compliance_report without the agent needing to open 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 a clear trigger ('Call this to mark which injected memories were followed or violated') and the prerequisite that the session id comes from a prior session_start. It does not explicitly name get_compliance_report as the read-only alternative or state when not to call it, so it stops short of full routing guidance.

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

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

Beyond annotations declaring destructive/non-idempotent behavior, it adds that writes happen immediately, that edit re-embeds or clears stale vectors, that approve affects future ranking, and that auth is required when the agent has a registered key. These are meaningful operational details not expressible through the annotations alone.

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 compact and front-loaded: it names the tool, then enumerates the actions and their constraints in one dense but readable passage. Every clause carries operational 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 multi-action mutation tool with full schema descriptions and annotations, the description covers action semantics, authorization, side effects, and the key reject/delete boundary. No output schema exists, so return-value detail is not required.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning by explaining what each action value does and when edit applies to already-approved memories. It does not add much for api_key or agent_id beyond the schema, so it is not a full 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?

The description states a specific verb and resource ('Review or edit a memory') and then distinguishes the three actions with precise effects. It clearly differentiates reject from delete_memory, so an agent can select it correctly against siblings like forget_memory, delete_memory, and save_memory.

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 per-action guidance: approve for human-review marking, edit for content/instruction updates, reject only for pending memories with a direct pointer to delete_memory for approved ones. This names both when to use the tool and when to use an alternative.

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

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

Goes well beyond the destructiveHint/not-idempotent annotations: it discloses that MUST memories are exempt, that the operation is not purely reversible, and exactly when it becomes permanently destructive (MEMVAULT_FORGET_AUTO_ENABLED=1 with the default 90-day retention). The auth requirement and the enumerated return counts 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?

Front-loaded with the core action and mechanism, then the risk caveat, then auth, then return shape — a sensible order. All four sentences carry information; the parenthetical env-var detail is dense but load-bearing rather than filler.

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

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

For a destructive tool with no output schema, the description covers the mutation semantics, exemption rules, conditional irreversibility, auth prerequisites, and the shape of the return counts. An agent has everything needed to decide and 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 api_key and agent_id are already documented; baseline is 3. The description adds value by explaining when api_key is actually required ('when the agent has a registered key'), giving an agent a decision rule the schema only hints at.

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 ('Run a memory decay cycle') and immediately explains the mechanism: lowering decay_score for old memories and archiving those below threshold. This is distinguishable from siblings like run_dedup, run_promote, or forget_memory because the decay/archive semantics are unique to it.

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 conditions that select this tool are clear from the description of the cycle, and the exemption rule for MUST memories is spelled out. It does not explicitly say 'use forget_memory instead when...' or name alternatives, so it stops short of full routing guidance.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the similarity method (Jaccard), the namespace scope, the exact result fields (existing_id/new_content/similarity/action), the cap of 20 findings, and explicitly states that no merge or delete occurs. That is substantive behavioral context an agent cannot infer from annotations alone.

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 four sentences, front-loaded with the core action and scope. Each sentence adds useful information: detection method, read-only behavior, returned fields, and result cap. There is no repetitive or wasted text.

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, but the description compensates by listing the returned fields and stating the maximum number of findings. Combined with the 100% parameter schema coverage and read-only annotations, an agent has everything needed to invoke the tool correctly and understand what it will return.

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 api_key, agent_id, and namespace. The description mentions scanning 'one namespace or all namespaces,' which mirrors the schema's 'null for all' note without adding new syntax or format guidance. Baseline 3 is appropriate when the schema carries 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?

The first sentence states a specific verb and resource: 'Scan for duplicate memories and report findings.' It further distinguishes the tool by naming its detection method (lexical Jaccard similarity) and its read-only scope, making it clearly different from mutating siblings like delete_memory or forget_memory.

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 description makes the use case clear: scan for near-duplicates in one namespace or all namespaces and report findings without changing data. It does not explicitly name alternatives such as delete_memory or confirm_read, but the read-only constraint and returned 'action' field give an agent enough context to know this is a detection step rather than a cleanup step.

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 destructive/not-idempotent/not-readOnly, and the description adds genuine context beyond them: source memories are archived to L0 rather than deleted (mitigating the destructive hint), and agent auth is required when a registered key exists. It also discloses the return payload shape. Missing only cost/latency or rollback details, which keeps it at 4 rather than 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 compact sentences, with the pipeline semantics front-loaded, then safety behavior, then return value. Every sentence adds distinct information and none repeats the name or annotations.

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

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

No output schema exists, but the description states what the return contains (promoted/consolidated/merged/source counts), which covers the main gap. Slightly incomplete on preconditions and failure modes for a mutating pipeline, but well beyond adequate overall.

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 defaults for min_l1 (3) and min_l2 (2) and the api_key requirement are already documented in the schema. The description adds nothing parameter-specific beyond echoing the auth requirement, 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 (run) and resource (promote pipeline) and spells out the two-stage transformation: L1 atomics → L2 scenario summaries, stable L2 → L3 persona rules, with sources archived to L0. This is specific enough that an agent can distinguish it from run_dedup or run_decay 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?

Usage context is implied by the description of what the pipeline does, but there is no explicit when-to-use/when-not guidance and no named alternatives or prerequisites (e.g., that L1 must exist first, or that run_dedup should precede it). The agent must infer timing and ordering.

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 establish that this is a non-read-only, non-idempotent write, and the description adds substantial context beyond that: automatic embedding generation, near-duplicate skipping, merge-absorption semantics, the saved/merged/skipped response states, immediate persistence, and the registered-key auth requirement. This is exactly the behavioral detail an agent needs before calling 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?

The description is front-loaded with the core purpose and then layers in the important default behavior and exceptions without wasted sentences. The delta-write explanation is dense but each sentence contributes 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 16-parameter mutation tool with no output schema, the description covers the highest-risk behavioral details: dedup/merge behavior, force_insert bypass, immediate persistence, auth, and response status values. It does not describe the response shape beyond status, but given full schema coverage for parameters, it is largely 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 all 16 parameters are already documented in the input schema, which sets the baseline at 3. The description mentions force_insert and auth in prose, but those meanings are also present in the schema, so it adds little parameter-level detail 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?

The description opens with a specific verb+resource ("Save a new memory") and immediately defines what a memory is (preferences, facts, episodes, skills), which clearly separates it from siblings like search_memory, delete_memory, and add_evidence. 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?

It clearly explains the default delta-write behavior and the exact condition for using force_insert=true, which is strong intra-tool guidance. It stops short of explicitly routing the agent between save_memory and related siblings such as add_evidence or extract_memories, so it is clear but not fully comparative.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds meaningful behavior beyond them: hybrid/keyword/semantic fallback, search_mode reporting, min_score filtering semantics, and one-hop relation expansion. It also explicitly confirms the tool does not mutate memories.

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 explains mode behavior, fallback, supported filters, and safety in a compact sequence. It is dense but every clause is relevant for a 10-parameter search tool, with no wasted framing.

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 search tool with no output schema, the description covers the important invocation context: retrieval modes, fallback behavior, filtering options, score thresholding, relation expansion, and read-only safety. It also notes that results report search_mode, which is enough for correct use.

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 parameters and a baseline of 3 would be appropriate. The description adds useful context for mode defaults, embedding fallback, top_k default, min_score purpose, and expand_relations, though it does not mention api_key/agent_id because the schema covers them.

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 ("Search stored memories") and outlines the available modes, so the core purpose is clear. It does not explicitly distinguish this from sibling retrieval tools such as list_inbox or review_memory, but an agent can still infer that this is the query-based memory lookup tool.

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

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

Explains the mode choices and the important fallback behavior when embeddings are unavailable, including that results report search_mode='keyword'. It does not explicitly say when to prefer this tool over alternatives like list_inbox or review_memory, but the retrieval context is otherwise clear.

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, the description discloses the return format (MUST/REF instructions), the overflow-summarization behavior, the non-MCP skip path, side effects of compliance tracking (recording and returning inject_session_id), and the authentication requirement. These are substantive behavioral details that an agent would not know from the annotations alone.

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: the core purpose and return behavior come first, followed by special cases and side effects. Four sentences are appropriate for the complexity, though a slightly tighter wording could have preserved the same information with less reading overhead.

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

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

With no output schema, the description carries the full burden and does so completely: it explains the return format, the overflow fallback, the non-MCP skip path, compliance tracking side effects, and authentication requirements. An agent has everything needed to invoke and interpret the result correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter's meaning. The description adds marginal context by noting that memories are filtered by agent identity and that api_key is for authentication, but it does not meaningfully enrich the semantics of project, agent_type, or context_hint beyond what the schema provides.

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

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

The description opens with a specific verb and resource ('Start an agent session') and immediately explains what it returns: relevant memories filtered by agent identity, formatted as MUST/REF instructions. It clearly distinguishes this session-initialization role from retrieval siblings like search_memory, which is named as the fallback for overflow details.

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 description makes the usage context explicit: it is the session-start step that primes the conversation with injected memories, and it names search_memory for overflow details and report_compliance for later compliance reporting. It does not state explicit exclusions (e.g., when not to call it), but the context is clear enough for an agent to select it correctly.

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