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

The description asserts 'Idempotent.' while annotations declare idempotentHint=false — a direct, machine-visible contradiction on the one trait that determines whether a retry is safe. It also leaves out what a delete actually does to dependent state (the schema hints that recall compares revisions to mark records stale, but the description never says forgetting invalidates anchors). With destructiveHint=true and openWorldHint=true already in structured data, the description needed to add caution, not contradict it.

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

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

Three sentences: action, the routing rule, then the safety gate — a sensible front-loaded order with no filler. The only wasted sentence is the false idempotency claim, which costs clarity rather than length.

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

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

An output schema exists, so return values needn't be described, and annotations carry the destructive/open-world profile. But the description never mentions the required `artifact` (revision + format) that every invocation must supply, and its misleading idempotency claim leaves an agent unable to decide whether a retry is safe — a material gap for a destructive mutation.

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

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

This is where the description earns its keep: it explains the routing logic between `name` (named feature), `entity_id` (anonymous notes) and `subject` (decision), which the flat schema states only in passing and never as a choice hierarchy. Schema coverage is already 75%, so the baseline is 3; the explicit either/or mapping lifts it. It omits that `artifact` is required regardless of which of the other three you pass.

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

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

The opening verb-phrase 'Delete a saved record' is then made specific by enumerating the three removal targets (named feature, entity's anonymous notes, decision), each mapped to a different argument. Siblings (remember/recall/remember_decision) are clearly a different operation class, so the tool is easily distinguished. It stops short of 5 because the mandatory `artifact` anchor — needed on every call — is never mentioned.

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?

'Use only when the user explicitly asks to remove it' gives a real gating condition rather than generic context, which for a destructive tool is the most important guidance. No alternative is named (e.g. 'use remember to overwrite instead of forgetting first'), so an agent must infer whether an update path exists.

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

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

Annotations already declare read-only, idempotent, non-destructive behaviour, yet the description still adds substantial context: it does not open the artifact, requires no shared filesystem access, and explains that the supplied revision drives per-record stale/current marking. The scoping note that an entity filter is revision-bound while text and tag filters are not is exactly the kind of non-obvious behaviour an agent could not infer from the annotations.

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

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

Purpose and required input are front-loaded in the first two sentences, and each subsequent sentence adds a distinct behavioural fact rather than restating the schema. It is on the dense side at five sentences, but almost nothing is filler.

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

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

With an output schema present, the description need not enumerate return values, and it still sketches the record shape (artifact reference, entity IDs, ID scheme). For a six-parameter tool with a nested ArtifactRef, all the information needed to call it correctly and interpret staleness is 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 high (83%), which sets the baseline at 3, but the description earns more: it tells the agent to pass the ArtifactRef from Geometry inspect, explains why revision matters for staleness, and clarifies the asymmetric matching semantics of entity_id vs search/tags. Only the limit/offset pagination behaviour is left entirely to the schema.

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

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

The description opens with a specific verb+resource ("Retrieve saved reviews for a STEP file") and enumerates the three optional filter modes, so the operation is unambiguous. It does not, however, distinguish itself from the sibling recall_decisions, which an agent could easily confuse with a review-recall 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?

"Use early in a conversation to restore persistent context about a part" gives a clear positive usage context, and it explains the hand-off pattern ("use these together when handing an annotation to another tool"). It offers no explicit exclusions or pointers to remember/forget/recall_decisions as 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?

Annotations already cover read-only/idempotent/non-destructive, and the description goes further with behavior they cannot express: results come back newest-first, records are marked stale when made against a different revision, and an entity filter silently narrows to the supplied revision because face IDs are revision-scoped. That last point is a non-obvious filtering behavior an agent would otherwise get wrong.

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?

Ordering and staleness semantics are front-loaded, and the usage sentence is placed last as a decision cue. The revision-scoping sentence is dense and could be tightened, but every sentence carries information not available in the schema.

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

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

An output schema exists, so return shape needn't be described, and pagination is handled in the schema. The description covers ordering, staleness, and filter semantics, which is what an agent needs; only edge behavior on empty results is unaddressed, a minor gap for a 6-param read tool.

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

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

Schema coverage is 83% so the baseline is 3, but the description adds genuine meaning: the `artifact` argument must be the current ArtifactRef from inspect, and the entity/revision interaction is explained with a worked rationale ("a decision about face:3 in an older revision is not a decision about face:3 now"). It also summarizes the subject/status/entity filter axes, going beyond the per-parameter schema text.

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 and adds real scope: decisions for an artifact, newest first, each flagged stale relative to the supplied revision. It stops short of differentiating itself from the sibling `recall` tool, so an agent must infer which of the two to call.

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?

"Use this when a revision reappears, to recover what was already concluded instead of reaching it again" gives a concrete triggering condition, and "Pass the current ArtifactRef from Geometry inspect" states a prerequisite. It never names `recall` as the alternative or gives an explicit when-not, so routing between the two recall tools remains inferred.

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

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

Adds real behavior beyond the annotations: a named re-save REPLACES the prior record while an unnamed re-save APPENDS. That replacement semantics is exactly the kind of nuance the annotations don't convey (destructiveHint=false would not warn an agent that a named write overwrites), and it is consistent with idempotentHint=false.

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

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

Front-loads what is saved and immediately follows with the replace/append contrast, which is the decision-critical fact. The closing line ('The more you save, the more the system understands...') is motivational filler rather than operational detail and could be dropped.

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

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

With an output schema, full annotations, and 83% param coverage, the description carries only the semantic load and mostly does: write mode, replacement vs append, and the correction use case. The one gap is no stated relationship to recall/remember_decision, which matters given four siblings.

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 already high at 83%, so the baseline is 3, but the description still adds meaning: name toggles the feature-vs-note mode and its re-save behavior, and 'the same entities' ties the append rule to the entities parameter. It does not add anything for artifact/entity_id_scheme, but those are well documented in the schema.

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

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

States a concrete verb+resource ('Save a durable review about geometry') and partitions the input space into named feature vs plain note. It is clear what the tool does, but it never distinguishes itself from the closest sibling, remember_decision, leaving the agent to infer which save tool applies.

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 usable when-to guidance: supply a name for reusable semantic groups like 'mounting holes', omit it for a plain note, and use re-remembering to correct the AI. It stops short of naming alternatives (recall, remember_decision) or exclusions, so the routing is implied rather than explicit.

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

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

Adds substantial context beyond annotations: it explains the replace-on-same-key semantics (consistent with idempotentHint=false), that decisions are keyed by subject+revision, that the server never opens/measures the artifact so stored evidence is reported, not measured, and that Geometry remains the numeric authority. No contradiction with readOnlyHint=false/openWorldHint=true.

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

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

Reasonably front-loaded — the save action and replace semantics come first — and most sentences carry distinct information (keying, verdicts, fidelity of storage, measurement disclaimer). It is on the long side and the fidelity/authority points could be tighter, but nothing is filler.

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

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

For a 7-param nested mutation tool with an output schema, the description covers the semantics an agent can't get from fields alone: the replace rule, key composition, verdict recording, and the fact that evidence is reported rather than measured. Field-level details (source enums, unresolved/conflicting states, revision pattern) are already in the schema.

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

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

Schema coverage is 86% so the baseline is 3, but the description adds real meaning: the subject is part of the record key and controls replace-vs-new, and a verdict is what turns a proposed requirement into an agreed one. It does not explain supersedes vs. the implicit replace, leaving one gap.

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

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

Opens with a specific verb+resource: 'Save the disposition reached about an artifact revision, with the basis it rests on' and then defines the basis structure. It also implicitly distinguishes itself from the read-side sibling by noting 'recall returns what was concluded, not a measurement', so an agent can tell it apart from recall/recall_decisions.

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

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

Gives concrete when-to-use rules: re-remembering the same subject on the same revision replaces the decision (revision path), a different subject starts a separate decision, record engineer verdicts when given, store requirements/evidence as stated. It doesn't give an explicit 'do not use this when...' exclusion or name a write alternative, but the context is clear.

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