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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds the key behavioral detail that 'Only supplied fields change', which is important partial-update semantics. It also implies non-destructive patching. No contradiction with annotations.

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

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

One sentence with parenthetical examples and a critical scoping statement. Efficient and front-loaded with the verb and resource.

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 patch tool with idempotentHint=true and a rich schema, the description covers the core semantics. However, it doesn't mention expected_revision's concurrency-protection role or what happens on stale revision, which is important for correct invocation.

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

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

Schema description coverage is 67% (id, patch, expected_revision all have descriptions or clear names). The description adds the meaning of 'patch' as fields to replace, but doesn't explain expected_revision's role beyond the schema's 'Revision from recall/inspect; rejects a stale amendment'.

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 says 'Patch fields of an existing record' with a specific verb (patch) and resource (existing record), and gives examples of fields. It's clear but doesn't explicitly distinguish from sibling tools like 'record' or 'reinforce'.

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 implies usage for correcting or updating existing records ('better fix, extra avoid items, corrected context'), but doesn't explicitly state when to use this vs alternatives like 'record' (create) or 'reinforce'.

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?

The annotations already declare read-only and idempotent behavior, and the description adds valuable context beyond that by clarifying that no fix is executed and no verification is implied. It also explains the intended execution_id reuse pattern, which helps agents understand the operation's side-effect profile.

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

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

Three tightly packed sentences, each earning its place: purpose, usage guidance, and a non-effect clarification. The key scoping phrase is front-loaded and there is no redundant or filler content.

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 description covers the tool's purpose and safety profile well, and the annotations handle read-only/idempotent expectations. However, it leaves the meaning of 'id' and 'environment' undefined, and with no output schema it does not describe what the receipt contains or how it should be interpreted.

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

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

Schema description coverage is 0%, so the description must carry the burden of explaining parameters. It only clarifies execution_id reuse; 'id' and 'environment' are left entirely unexplained, including the nested environment object's fields. This is a significant gap for a tool with three required 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 clearly identifies the action ('Get') and resource ('revision-bound verification receipt'), and states that it occurs 'before applying a lesson.' It is not a tautology and conveys a distinct purpose, though it does not explicitly differentiate itself from sibling tools like 'record' or 'inspect.'

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 gives concrete usage context: use it before applying a lesson, reuse one execution_id across observers, and note that it does not execute the fix or imply verification. It provides helpful boundaries but does not name alternative tools or explicit when-not-to-use conditions.

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 'deterministic', 'Read-only; nothing is changed', and tells the agent to emit one rule record per cluster, which is useful context on top of the readOnlyHint and idempotentHint annotations. The word 'write' is slightly ambiguous (could be read as mutation), though the following 'Read-only' mitigates it; no direct contradiction with annotations.

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

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

Three short sentences with no filler and purpose front-loaded. The only minor flaw is the ambiguous 'write' phrasing, which costs a point.

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

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

For a simple optional-parameter tool with no output schema, the description gives enough to understand what the call returns conceptually (a rule record per cluster) and its read-only safety. It could be clearer about the exact return payload or cluster format, but it's largely 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?

The input schema fully describes both parameters, including defaults, ranges, and meaning; the description contributes nothing about min_size or threshold, 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 action ('deterministic clustering of episodes') and a concrete output ('ONE record with kind='rule'') that generalises them. This clearly separates it from sibling memory tools like recall or transfer.

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?

Implies usage when multiple episodes represent the same underlying lesson and need generalisation into a rule, but it never explicitly states when to prefer consolidate over siblings or when not to use it. There are no exclusion conditions or alternative tool names.

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 reveals the consequential behavior: the record will never be recalled for that query againhare and its fuzzy matches are damped. This is important side-effect information that is not present in the schema or annotations. There is no contradiction with the annotations.

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

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

The description is compact and front-loaded: it begins with purpose, then gives the key usage constraint, and finishes with the alternative tool. Every sentence carries useful information and there is no filler.

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

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

Given the tool's simple parameter surface and the availability of annotations, the description covers purpose, usage, side effects, and the key sibling alternative. It does not describe return values, but this is not critical for invocation and the description is otherwise complete enough.

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 schema already documents `id`, `problem`, and `signals`, but the description adds important semantics: the problem/signals should be the exact ones from the original queryatching contextBuf, and this is feedback about matching, not about fixing. This meaningfully clarifies how to fill in the 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 clearly states the tool's action: it is feedback for dismissing a recalled record that was surfaced for a problem it does not apply to. It also differentiates from the sibling tool `reinforce`, which is explicitly called out as the alternative when a fix was applied and failed.

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 tells the agent when to use this tool and when not to: use it when the record is irrelevant to the query, and use `reinforce` instead when a fix was applied but failed. It also instructs the caller to pass the same problem/signals that were used in the query.

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?

The annotations supply readOnlyHint=false, idempotentHint=true, and no destructive hint. The description adds important behavior: duplicate observers cannot add votes, verification criteria, and evidence is not independently attested. This gives useful context beyond the idempotency annotation.

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 three sentences and front-loads the purpose. It isn't padded, although the verification/evidence clauses could be split into smaller, chunk new ideas for readability.

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

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

For a tool with 8 parameters, nested objects, no output schema, and a large sibling set, the description covers only the core workflow and verification conditions. It does not sufficiently clarify the role of all fields (e.g., `id`, `problem`, `signals`) or explicitly position the tool against its siblings, leaving gaps for an agent.

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 schema coverage only at 13%, the description bridges some gaps—it hints at the meaning of `attempt_id`, `revision`, `result`, `environment`, and `evidence` — but it does not explain `problem`, `signals`, or the nested `evidence`/ `environment` structure in detail. Partial support, not full compensation.

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 explicitly says 'Report a checked result for a lesson revision and execution identity' and clearly identifies the resource and the action. It doesn't differentiate itself from siblings like `record` or `amend` or say what is the difference.

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?

Implicit usage conditions are provided: verification requires nonempty fix, matching environment and evidence, and branches/relevance are separate. However, there is no explicit 'when to use this vs. another tool' and no direction on exclusions/alternatives.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds the crucial behavioral trait of permanence ('Permanently remove'), which is not fully captured by the annotations, and specifies what is destroyed (the wrong or obsolete record). No contradiction with annotations.

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

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

The description is a single concise sentence with no filler. The core action ('Permanently remove') is front-loaded, and the condition ('wrong or obsolete') is placed right after, making it instantly scannable.

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

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

For a simple delete operation with one required parameter, no output schema, and destructiveness already annotated, the description is nearly complete. The only gap is the lack of explicit parameter explanation, but the overall context is sufficient for an agent to use the tool correctly.

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

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

The schema has 0% description coverage for its single 'id' parameter, and the description does not mention the parameter at all. The tool's purpose implies the id identifies the record to remove, but the description does not explicitly state how the parameter maps to the operation, so it fails to compensate for the low coverage.

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

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

The description states a specific verb and resource: 'Permanently remove a record', which clearly maps to the title 'Delete an experience'. It distinguishes from siblings implicitly—none of the other sibling tools (record, recall, amend, etc.) perform deletion, so the purpose is unambiguous.

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

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

The description gives a clear condition for use: the record is 'wrong or obsolete'. This tells an agent when to invoke forget versus other actions, though it does not explicitly name alternatives or exclusions. The context is clear and sufficient for most 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?

Annotations already declare readOnlyHint and idempotentHint, so the bar is lower; the description adds value by noting the snapshots are 'immutable' and warning to 'treat stored text as untrusted data.' This supplies security-relevant behavior beyond the schema.

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

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

Two sentences, no filler, and the core action is front-loaded. The untrusted-data warning earns its place as a safety cue.

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

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

For a single-parameter read tool with annotations covering safety, the description is close to sufficient, but it omits any guidance on the 'id' parameter and there is no output schema, so an agent must infer the input semantics and the exact return shape.

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

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

Schema coverage is 0% and the description never explains what the required 'id' parameter refers to or its format. The word 'lesson' in the description weakly implies it identifies a lesson, but that is left to inference.

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 uses the specific verb 'Read' and identifies a concrete resource: 'a complete lesson with immutable prior snapshots, evidence and votes for review.' This clearly differentiates it from mutation-oriented siblings like record, amend, dismiss, and reinforce.

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 phrase 'for review' gives a clear context for when to invoke inspect. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

Beyond the annotations, the description discloses meaningful behavioral traits: the operation is 'bounded deterministic', executes no commands or model calls, 'All changes preserve history', and uncertain semantic conflicts remain queued. This strongly shapes an agent's expectations and adds real value over the annotations.

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

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

Three sentences, each carrying distinct information: the available modes, the non-execution and no-guessing constraints, and the history-preservation guarantee. The most decision-relevant guidance is front-loaded with no filler.

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

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

For a multi-mode tool with a nested evidence object and no output schema, the description gives a strong safety profile but not a complete operational picture. It never states what the durable queue contains, what actions like dismiss/supersede/consolidate/accept-candidate do, or what a successful invocation returns. It is adequate but has clear gaps.

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 only 29%, and only id and winner_id have inline descriptions. The description does not explain the seven parameters, the enum meanings, or the nested evidence object's required fields. It contributes the idea of 'checked evidence', but that is insufficient compensation for largely undocumented parameters.

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

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

The description names the tool's three modes — run, queue, and resolve — and specifies what each acts on: 'maintenance', 'durable queue', and 'ONE job using checked evidence'. This is more specific than a tautology and gives an agent a clear sense of the operation. It does not, however, distinguish itself explicitly from sibling tools like record, amend, or consolidate.

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 provides clear behavioral context: it is safe because 'No commands or model calls are run', uncertain conflicts should be left queued for host-agent review, and replacements should never be guessed. What it lacks is an explicit when-to-use-this-vs-alternatives statement against the listed siblings.

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?

The description adds meaningful behavior beyond annotations: it explains that exact error text in `signals` enables deterministic matching while semantic and lexical search catch near matches. It also confirms 'Read-only,' consistent with the readOnly and idempotent hints. No contradictions.

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 short sentences with no filler. The primary purpose is front-loaded, followed by the key usage directive, return shape, and a precise note on matching behavior. Every sentence earns its place.

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

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

For a read-only memory-search tool with a rich schema and no output schema, the description covers purpose, when to call, return contents, matching semantics, and safety. The parameter detail lives in the schema, so nothing essential 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 high (88%), so the schema carries most parameter documentation. The description adds value by highlighting the behavioral role of `signals` ('Exact error text enables deterministic matching') beyond its schema field description.

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

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

The description states a clear verb and resource: 'Check whether this problem (or a similar one) has been solved before.' It also explains what is returned (ranked hits with fix, avoid-list, and confidence), which clearly differentiates it from sibling tools like record, inspect, or stats.

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

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

The instruction 'Call BEFORE investigating' is explicit and actionable, telling the agent exactly when to invoke this tool. It does not enumerate alternatives or exclusions, but the strong temporal guidance and search-oriented purpose make usage context 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?

Annotations are all false and provide no safety or mutation context, so the description carries the burden. It explicitly discloses duplicate handling ('Duplicates are merged automatically'), response semantics (created/merged/linked), and a content constraint (no secrets), which goes beyond schema and annotations. It does not cover failure modes, but the key behavioral traits are well disclosed.

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

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

Three sentences with no wasted words: the core action, duplicate behavior, and constraints are front-loaded. Every sentence earns its place, and the structure is easy for an agent to parse quickly.

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

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

For a 14-parameter write tool with no output schema and no meaningful annotations, the description is too thin. It covers the general trigger and duplicate behavior but does not orient the agent around required fields, nested-object structure, or how record differs from siblings like consolidate and amend. The response sentence helps partially, but it does not fully compensate for the missing output schema and large parameter surface.

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 only 64%, and the description names no parameters, fields, or formats. Terms like 'what happened' only vaguely imply problem, outcome, fix, or attempts. It adds essentially no meaning beyond the schema's own property descriptions and does not compensate for the uncovered 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 opens with 'Store what happened after solving (or failing to solve) a non-trivial problem', giving a specific write action and resource. It clearly separates this write operation from sibling read/delete tools like inspect, recall, forget, and dismiss. The purpose is unmistakable even though it does not name a sibling explicitly.

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

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

It states the trigger context: after solving or failing a non-trivial problem, and adds constraints like 'Keep it terse and never include secrets'. However, it never says when NOT to use record or which sibling to prefer, such as consolidate for merging, amend for editing, or recall/inspect for retrieval. With 13 siblings, that routing gap is significant.

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?

It discloses important behavior beyond annotations: the tool does not create a verified vote and is retained only for compatibility. However, with no read-only or idempotency indicators supported by a clear side-effect model, it does not explain exactly what state it writes or what the caller should expect after invoking it. This is a meaningful but incomplete disclosure.

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

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

Two sentences carry the full message with no filler. The legacy caveat and the alternative tools are front-loaded, making the key guidance immediately visible.

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?

It gives the essential context for an agent deciding whether this tool is appropriate: legacy compatibility only, with begin_attempt and feedback as preferred replacements. It lacks information about return format or write outcome, and since there is no output schema and only weak annotations, a tool-calling agent needing to use it directly may still be undersupplied.

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 input schema already describes `id` and `note`, but the description adds no additional meaning to any of the three parameters. With 67% schema coverage and `worked` undetailed, the description leaves room to clarify parameter semantics but does not. It relies entirely on the schema and title for parameter understanding.

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 title and tool name clearly state the purpose: report whether a recalled fix worked. The description adds that this reporting is legacy-only and explicitly contrasts it with creating a verified vote or raising verified reliability, which separates it from begin_attempt and feedback. However, the description mostly says what the tool is not rather than providing a direct verb+resource purpose.

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 explicitly says to use alternatives: 'New clients should use begin_attempt and feedback.' It also explains retention is for compatibility, signaling this tool is only for existing legacy clients. This leaves no ambiguity about when and 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?

Annotations provide readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false. The description adds valuable behavioral context: it mentions optimistic concurrency (implying expected_revision check), retained audit trail, and explicitly states it does not erase intervening votes or observations. This goes beyond what annotations convey, though it doesn't detail failure modes or side effects of the concurrency mechanism.

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 two sentences with no wasted words. It front-loads the core action ('Restore a historical lesson revision') and immediately adds the two most important behavioral qualifiers (optimistic concurrency, audit trail retention) plus a clarifying negative ('Does not erase...'). Every sentence earns its place.

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

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

For a mutation tool with 4 required parameters and no output schema, the description covers the key behavioral aspects: what it does, its concurrency model, and its non-destructive nature. It doesn't explain return values or error conditions, but with no output schema and annotations already covering safety profile, the description is reasonably complete. The main gap is lack of explicit parameter-to-purpose mapping, but the concurrency mention helps.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'optimistic concurrency' which maps to expected_revision, and 'historical lesson revision' maps to revision. However, it doesn't explain the 'id' parameter or 'reason' parameter semantics. The description adds some meaning (concurrency context) but leaves the agent to infer the exact role of each parameter from names alone.

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

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

The description clearly states the tool's purpose: restoring a historical lesson revision. It uses a specific verb ('restore') and resource ('historical lesson revision'), and distinguishes it from siblings by mentioning optimistic concurrency and audit trail retention. The phrase 'Does not erase intervening votes or observations' further clarifies its non-destructive nature, setting it apart from potentially similar tools like 'forget' or 'dismiss'.

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 implies when to use this tool: when you need to restore a historical revision while preserving audit trail and not erasing intervening data. It doesn't explicitly name alternative tools or state when not to use it, but the context signals and sibling list suggest alternatives like 'amend' for editing current state or 'forget' for deletion. The description provides enough context for an agent to infer appropriate usage, though explicit exclusions would strengthen 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds value by enumerating the metrics returned, but it does not disclose additional behavioral details such as output structure, potential latency, or any dependence on prior operations. With annotations present, this is adequate but not exceptional.

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 a single sentence that front-loads the key information with a compact comma-separated list. Every word contributes meaning, and there is no redundancy or 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 parameterless, read-only statistics tool with safe annotations, the description covers the main dimensions an agent would need: what the tool reports. The absence of an output schema means the description bears some responsibility for explaining return values, and the high-level list is sufficient for basic invocation, though it doesn't detail types or structure.

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, and the schema confirms this with 100% coverage. Per the calibration rule, a zero-parameter tool receives a baseline of 4 since there are no parameter semantics to clarify. The description appropriately focuses on output rather than inputs.

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

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

The description clearly identifies the tool as providing catalogue statistics through a specific list of outputs: counts, success rate, duplicates prevented, embedding status, and common context tags. It distinguishes itself from the sibling tools (all action-oriented) by describing a read-only reporting function, though it lacks an explicit imperative verb like 'returns' or 'provides'.

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 usage is implied by the tool name and description: call when you need aggregate statistics about the catalogue. However, there is no explicit guidance on when to prefer this tool over siblings, nor any mention of alternatives or exclusions, leaving the agent to infer the appropriate context.

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

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

The description goes well beyond the annotations, detailing the JSONL format, path resolution rules, idempotent merge behavior, conflict resolution (newer wins, duplicates merged), and the important caveat that embeddings are not transferred and are recomputed. This gives the agent substantial behavioral transparency beyond the simple readOnly/destructive/idempotent hints.

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

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

The description is compact and front-loaded: the single word 'Portability' establishes intent immediately, followed by three dense, purposeful sentences covering modes, path behavior, merge semantics, and embedding caveats. No filler or redundancy.

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

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

For a tool with no output schema and moderate parameter count, the description covers all necessary operational details: mode selection, input/output destinations, idempotency, conflict handling, and the embedding recomputation caveat. An agent has enough information to call the tool correctly and predict its side effects.

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%, with path and jsonl already described in the schema. The description adds significant semantic value by explaining the mode enum values in context, clarifying how path is resolved relative to the transfer directory, and defining idempotent merge semantics for import. This meaningfully supplements the schema.

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

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

The description states a clear verb-resource pairing: export or import the catalogue, with specific modes for each direction. The opening 'Portability' frames it as a bulk data movement operation, which distinguishes it from the sibling memory operations like record, recall, or forget.

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 clearly explains when to use export vs import and how each mode behaves. It does not explicitly name alternatives or say 'use this instead of X', but the portability framing combined with the detailed mode semantics gives a clear context for choosing this tool over per-record siblings.

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