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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false; the description adds the meaningful claim that raw records and prior report snapshots remain unchanged, reinforcing non-destructiveness. However it says nothing about what approval actually mutates, whether the pending amendment is consumed, or what happens on revision mismatch.

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 compact sentences, front-loaded with the action and the caller constraint, with no filler. Brevity here is efficient rather than under-specified, though it leaves little room for the missing parameter 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?

For a four-parameter, nested-object mutation tool with no output schema and no parameter documentation anywhere, the description is too thin. An agent cannot tell from it how to construct amendmentRef or what expectedRevision guards against, which are the main failure modes for this call.

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% for four required parameters, including a nested amendmentRef object, yet the description explains none of them. 'Exact' gives only the faintest hint that amendmentRef and expectedRevision must match current state; the concurrency/versioning semantics of expectedRevision are left entirely undocumented.

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 ('approval'/'apply') and resource ('pending amendment'), and 'exact' plus 'human-only' narrows it usefully. It implicitly contrasts with the propose/dismiss siblings but never names them.

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 'exact pending amendment' implies a prior propose step must exist and that approval rather than rejection is intended, but the description never says when to use this instead of rws_amendment_propose or rws_amendment_dismiss. Usage is inferable rather than stated.

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

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

Annotations already declare this is a non-readOnly but non-destructive, idempotent operation. The description adds meaningful behavioral context beyond that: the action is human-only and preserves proposal history rather than applying the patch. It still does not explain concurrency or request semantics.

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

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

Two short sentences, front-loaded with the core action and follow-up effect, with no wasted wording. The essential distinction from apply is included efficiently.

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 tool has a nested required object, four fully required parameters with no schema descriptions, and no output schema. While annotations cover safety traits, the description is too sparse to compensate for missing parameter semantics and does not explain what is returned or what expectedRevision guards against.

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%, and there are four required parameters including a nested amendmentRef. The description only vaguely implies amendmentRef and expectedRevision via 'exact pending amendment'; it says nothing about requestId, projectId, expectedRevision concurrency semantics, or the nested reference structure.

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 (dismiss an amendment) with clear scope (exact, pending), and distinguishes it from apply by saying the patch is not applied. An agent can tell what this tool does and how it differs from related 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?

It clearly establishes the usage context: human-only dismissal of a pending amendment, preserving history without applying the patch. This implicitly contrasts with apply, but does not explicitly name an alternative tool or explain prerequisites such as what 'pending' means operationally.

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

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

With annotations already declaring write/non-destructive/idempotent, the description still adds real behavioral facts: the operation is audited, it creates a proposal rather than mutating the record, and it does not rewrite the source. It leaves a notable gap around expectedRevision conflict behavior and what requestId deduplication does, which matters for a write 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?

Two front-loaded sentences with no filler; the core capability comes first and the non-effects second. It is efficient, though for a nested four-parameter write tool it is arguably too terse to be 'appropriately sized'.

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 tool has a nested object schema, zero parameter descriptions, no output schema, and optimistic concurrency via expectedRevision, yet the description covers none of the mechanics an agent needs (what patch accepts, what a revision mismatch means, what identifier the proposal returns for later apply/dismiss).

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% and all four top-level params plus five nested required fields are undocumented. The description only obliquely gestures at 'exact record' (targetRef) and 'audited' (evidenceRefs); requestId, expectedRevision, patch, reason, and the targetRef type enum are entirely unexplained, so it fails to compensate for the coverage gap.

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

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

States a specific verb ('Propose') plus the resource ('an audited metadata/source/lineage/recovery correction for an exact record'), which is far more informative than a bare name restatement. The propose/apply/dismiss sibling naming plus 'does not ... approve the correction' gives reasonable differentiation, though the description never names rws_amendment_apply as the approving step.

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

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

Usage is only implied: the phrase 'Does not ... approve the correction' hints at a two-phase workflow, but it never says when to call this versus rws_amendment_apply or rws_amendment_dismiss. No prerequisites (e.g. evidence must be attached, revision must match) are stated.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond that: it never mentions the optimistic-concurrency contract implied by the required expectedRevision, what happens on a revision mismatch, or that an existing id performs a partial merge.

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 short sentence, front-loaded with the primary effect, with no filler. It is arguably too terse for the schema's complexity, but nothing in it is wasted.

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 a nested record object, a merge-or-create anyOf, and a required revision token, this description is far too thin, especially with no output schema to explain the result. An agent would have to infer merge semantics and conflict handling entirely from the JSON schema.

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

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

Schema description coverage is only 25% on a four-parameter, deeply nested schema, so the description must compensate and largely does not. It names three record fields and notes codeRef can be omitted, but says nothing about requestId, projectId, or expectedRevision, which is the most error-prone required parameter.

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 (save) and resource (analysis) plus the key content fields (observations, interpretation, limitations), so the agent knows this persists an analysis record. It does not explicitly distinguish itself from close siblings like rws_experiment_save, rws_research_save, or rws_comparison_save, so the differentiation is only implicit in the resource name.

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 only guidance is the aside 'manual analysis may omit code', which is a field-relaxation note rather than a when-to-use rule. There is no statement of prerequisites, when to choose this over the sibling save tools, or when not to call 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 non-read-only, idempotent, non-destructive. The description adds materially beyond them: the record is immutable, provenance must be truthful, and the tool will not fetch arbitrary files. It does not mention the revision/concurrency semantics, which is the main remaining gap.

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

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

Three tight sentences with the core action front-loaded and the legacy-provenance caveat immediately after. No filler, though the 'does not read arbitrary files' clause is slightly orphaned without elaboration.

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 a deeply nested record schema and no output schema, the description covers the trickiest conceptual rule (provenance=known vs unresolved) but omits the optimistic-concurrency contract implied by expectedRevision and the span of supported content kinds.

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, but it only illuminates the provenance/source/description portion of the record. The required requestId, projectId, and expectedRevision parameters and the many content kinds are left entirely to the schema.

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

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

States a specific verb and resource: register an immutable output tied to its producer and configuration. This distinguishes it from sibling register tools like rws_run_register and rws_dataset_register by emphasizing the immutable-output record. It doesn't explicitly name those siblings as alternatives, keeping it 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?

Gives a clear conditional rule for the legacy case (provenance=unresolved with source evidence and description instead of inventing a producer run), and a when-not ('does not read arbitrary files'). However it never routes the agent to a specific alternative when this tool isn't appropriate, so usage is implied rather than enumerated.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful context beyond annotations by stating it returns exact identities and declared contracts, and by warning that supplied check evidence is not independent verification.

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, front-loaded with the core purpose and followed by a relevant caveat. There is no wasted wording.

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 find tool with five parameters, a nested object, no output schema, and no parameter descriptions, the definition is too thin. It gives purpose and one evidence caveat but does not explain how to use query/specRef/kind/limit or what the returned identities and contracts look like.

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% across five parameters, including the nested specRef object, enum kind, limit, and query. The description explains none of these parameter meanings, formats, or interactions, so it does not compensate for the schema gap.

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

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

States a specific verb and resource: "Find existing implementations" and frames it as avoiding duplicate/new code. It is clear enough to distinguish from registration/saving siblings, though it does not name an alternative 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?

"before building new code" gives a clear usage context for when to call it. However, it does not name alternatives, exclusions, or prerequisites, so guidance 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?

Annotations already declare a non-read, idempotent, non-destructive write. The description adds genuine value by asserting the record is immutable and that the path is never read or executed. However, it omits the concurrency contract implied by expectedRevision and how requestId provides idempotency, which an agent needs to call this safely.

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?

A single tight sentence with the key constraint front-loaded, which is good. But at this level of schema complexity the brevity crosses into under-specification; a second sentence on revision/idempotency semantics would earn 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?

A deeply nested schema with a conditional if/then branch, four required top-level params, no output schema, and zero schema descriptions demand far more explanation than one sentence. An agent cannot infer from this description what record must contain or what expectedRevision does.

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 carries the full burden — and it explains none of the four required parameters. requestId, expectedRevision, and the conditional record shape (specRef triggering required entrypoint/modulePath/repository/commit/capabilities/checkEvidence) are completely undocumented in prose.

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

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

States a specific verb+resource ('Register an immutable code identity') and adds a scoping clause about parent references. It is distinguishable from the read-side sibling rws_code_find, though the phrase 'code identity' is somewhat internal jargon.

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 clause 'never reads or runs the path' implicitly separates this from discovery tools like rws_code_find, but there is no explicit when-to-use/when-not guidance, no mention of prerequisites (e.g. needing an existing revision to target), and no named 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?

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so safety profile is covered. The description adds genuinely useful context that inputs are referenced rather than moved, but says nothing about optimistic concurrency (expectedRevision), idempotency-key behavior (requestId), or what happens on conflict/upsert — meaningful gaps for a mutation tool.

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

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

A single front-loaded sentence with no filler. It is efficient, though slightly cryptic phrasing ('without moving their original producers') costs a little clarity.

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 deep nested schemas, revision control, an idempotency key, and no output schema, the description is under-specified. Critical operational facts (create-vs-update behavior, conflict handling, what is returned) are 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 only 25% across four parameters. The record schema itself carries an update-semantics note, but the description adds no meaning for requestId (apparently an idempotency key) or expectedRevision (apparently optimistic locking), leaving the agent to infer their roles.

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 (save comparison inputs plus fixed/varying conditions) and clarifies the referencing behavior with 'without moving their original producers.' It is distinguishable from the many sibling *_save/*_register tools, though the phrasing is somewhat terse.

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?

There is no explicit when-to-use guidance, no mention of how this differs from the other save tools, and no stated prerequisites such as revision conflicts. Usage is only implied by the title-less name and the brief purpose sentence.

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

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

Annotations already declare a non-read-only, idempotent, non-destructive closed-world write, and the description reinforces that this registers an existing reference rather than creating or sending a chat. It adds useful scope, but does not explain idempotency/concurrency behavior around expectedRevision or what happens on revision mismatch.

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?

A single front-loaded sentence with no wasted words; the negative scope clause is useful. It is arguably too terse for the nested schema, but the text itself is efficient and well-structured.

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 tool has a complex nested schema, 0% parameter description coverage, and no output schema, yet the description is only one sentence. It orients the agent to the operation's purpose but leaves critical invocation details, especially record shape and expectedRevision semantics, unexplained.

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% across four required parameters, including a nested record object with title, uri, and refs, plus requestId, projectId, and expectedRevision. The description provides no meaning for any of these parameters and only vaguely alludes to a "conversation reference".

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?

Uses a specific verb, "Register", with a clear resource, "conversation reference", and adds a negative scope note that distinguishes it from chat creation or sending. The purpose is understandable without opening the schema, though it does not explicitly name a sibling alternative.

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 an existing conversation reference needs to be recorded, and explicitly excludes creating or sending a chat. However, it gives no guidance on prerequisites, when to prefer this over related save/register siblings, or how expectedRevision affects use.

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=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior by calling the dataset version 'immutable' and requiring 'exact sample IDs', but it omits what expectedRevision does, what happens on a revision mismatch, and how idempotency interacts with requestId.

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?

It is a single front-loaded sentence with no wasted words. Brevity is appropriate, though given the 4-parameter mutation with a nested object it may be too terse rather than complete.

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?

This is a mutation tool with nested parameters, an expectedRevision concurrency control, and no output schema. The description does not explain revision conflict behavior, project scoping, requestId semantics, or what a successful registration returns, leaving significant gaps for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate but does not. It only vaguely maps to record.version ('dataset version') and record.sampleIds ('exact sample IDs'); it says nothing about requestId, projectId, or the concurrency-control parameter expectedRevision.

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: 'Register an immutable dataset version and exact sample IDs.' This clearly distinguishes it from sibling registration tools like rws_code_register or rws_artifact_register by naming the dataset resource, though it does not explicitly compare itself to those 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?

There is no guidance on when to use this tool versus alternatives. The sibling list contains many registration and save tools, yet the description offers no conditions, exclusions, or prerequisites to help an agent choose rws_dataset_register over them.

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=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that registration pins protocol/code/input versions and performs validation without computing metrics, which is useful beyond annotations, but says nothing about failure modes, concurrency, or what validation rejects.

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?

A single front-loaded sentence that states the action, the resource, the version-pinning constraint, and the exclusion, with zero 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?

The input schema is deeply nested with 4 required top-level parameters and no output schema, yet the description covers only a fraction of what an agent needs. Critical semantics like expectedRevision conflict behavior and requestId idempotency are entirely absent for what is a mutating registration call.

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 carries the burden and largely does not. It hints at the protocolRef/codeRef/inputRefs fields via 'fixed protocol/code/input versions', but never explains expectedRevision (optimistic concurrency), requestId (idempotency key), or the structure of record/results.

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 specific verbs ('validate and register') and a specific resource ('existing typed evaluation results'), and explicitly scopes to fixed protocol/code/input versions. It also rules out metric computation, which cleanly separates it from compute-oriented siblings. It stops short of naming an actual alternative 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?

The clause 'does not compute metrics' implicitly signals this is for results already produced elsewhere, but there is no explicit when-to-use or when-not-to-use guidance relative to siblings like rws_result_query or rws_comparison_save. Usage must be inferred.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds useful context that the save binds a confirmed project foundation and does not execute, but omits what happens on revision conflict or what a failed bind means.

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?

A single sentence with no filler, front-loading the verb and resource before the two qualifying clauses. It is tight, though the terse phrasing leaves room for more critical detail given the schema complexity.

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

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

For a mutation tool with four required parameters, a nested polymorphic record with upsert semantics, optimistic concurrency via expectedRevision and idempotency via requestId, and no output schema, the description is far too thin to guide 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 only 25%, so the description should compensate, and it only gestures at the foundation binding (implying foundationRevision). It says nothing about expectedRevision semantics, requestId idempotency scope, or projectId scoping, leaving three of four required parameters unelaborated.

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

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

The description gives a specific verb+resource ("Save an experiment") plus a scoping clause ("bind its confirmed project foundation") and an explicit negative boundary ("does not execute it"). It is clear and distinguishable from an execution tool, though it does not explicitly contrast itself with the many other *_save 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?

"Does not execute it" supplies an implicit when-not boundary, steering the agent away from run-execution tools. However, it never names alternatives (e.g., rws_run_register or rws_project_create) or states prerequisites, so the routing logic must be inferred.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. Beyond that, the description adds useful behavioral context by naming the categories of context returned and explicitly warning that suggested actions are not execution authorization, which helps prevent misuse.

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 short sentences with no filler, and the core purpose is front-loaded. The caveat about suggestions is also placed immediately after the main purpose, where it is most useful.

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?

This is a complex tool with four parameters, nested reference objects, 0% schema description coverage, and no output schema. The description gives only a high-level content summary and does not explain how the reference parameters affect the result, what selectionRefs do, or what the returned structure looks like, so it is not complete enough for reliable 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 0%, and the description provides no explanation of any parameter. With four parameters, including nested reference objects such as researchRef, experimentRef, and selectionRefs, the description does not compensate at all for the missing schema semantics.

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 a specific verb, 'Read', with a clear resource, 'concise project/task context', and enumerates the kinds of content returned (completed facts, pending gaps, suggested actions). It is understandable on its own, but it does not distinguish this tool from nearby read-oriented siblings such as rws_record_get or rws_result_query.

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 does not say when to use this tool, when not to use it, or which sibling tool to choose instead. The sentence about suggestions not being execution authorization is a behavioral caveat, not usage guidance, so the agent is left to infer selection criteria.

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=false, idempotentHint=true, and destructiveHint=false. The description adds a meaningful authorization constraint beyond those annotations: human review only, no self-approval by MCP. However, it does not disclose what mutation is applied, what side effects occur, or what confirmation is returned, which is a gap for a mutation tool with nested required parameters.

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 short sentences with no padding and the key constraint is front-loaded. It is structurally efficient, though its brevity contributes to under-specification rather than helping the agent understand the operation.

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?

This is a complex mutation tool with five required parameters, a nested proposalRef object, no output schema, and only partial annotation coverage. The description only states a human-review guardrail and does not explain the operation, parameter meanings, revision-safety expectations, or what happens on success. Given the schema complexity, it is insufficiently 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 0%, and all five required parameters are undocumented in the schema. The description provides no information about requestId, projectId, expectedRevision, proposalRef, or baseRevision. With nested object semantics in proposalRef, the description fails to compensate for the schema coverage gap.

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

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

The description never states what rws_overview_apply actually does. It only says 'Human review only' and that MCP cannot approve its own suggestion, so an agent cannot tell from the description whether this tool applies an overview, proposal, or something else. The name hints at 'apply' and 'overview', but the description does not confirm or explain the operation.

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 an explicit when-not and alternative: MCP agents cannot use this tool to approve their own suggestion and should use the application review screen instead. That is strong routing guidance. It does not explain when, if ever, this tool is appropriate for an MCP agent, but the prohibition is 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?

The description adds a human-review constraint, but it is framed around approval rather than dismissal and does not explain what the dismiss operation changes, what revision checks mean, or what happens on success. With annotations already declaring write/idempotent/non-destructive behavior, the description still leaves the actual dismissal semantics opaque.

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 text is brief and front-loaded with a constraint, but the second sentence redirects away from the tool rather than explaining how to use it. Brevity here produces under-specification, not efficient guidance.

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 five-parameter write tool with a nested required object and no output schema, the description is completely inadequate. It does not cover purpose, preconditions, parameter values, side effects, or expected return behavior.

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% and five required parameters, including a nested proposalRef object, are entirely undocumented in the description. The text provides no parameter meaning, format, or dependency information, so it does not compensate for the schema 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?

The description never states that the tool dismisses an overview suggestion or identifies the resource being dismissed; instead it talks about approval and redirects to an application screen. An agent cannot infer what rws_overview_dismiss actually does from this text.

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

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

The only guidance is to use the application review screen, which effectively steers the agent away from this tool. It gives no condition for invoking rws_overview_dismiss and does not distinguish it from siblings like rws_overview_apply, rws_overview_propose, or rws_amendment_dismiss.

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

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

Annotations already cover the safety profile: non-read-only, idempotent, non-destructive. The description adds a useful behavioral distinction that the revision is only saved for review and is not applied, though it omits concurrency and validation behavior.

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

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

It is a single front-loaded sentence with no wasted words, and the key distinction from apply is included. Its extreme brevity is efficient, though it leaves important detail to 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?

For a mutation tool with 6 required parameters, a nested fields object, and no output schema, this one sentence is not complete enough. It does not explain revision conflict handling, what fields may be proposed, why `reason` is required, or how `sourceRefs` are used.

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% across 7 parameters, including nested `fields`, required `reason`, and concurrency fields `baseRevision`/`expectedRevision`. The description provides no parameter-specific meaning at all.

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

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

States a specific verb/resource pair: save a proposed foundation revision. The phrase 'for human review; this does not apply it' distinguishes the proposal step from application and gives an agent a clear workflow role.

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 indicates when to use it: saving a proposal for human review, and explicitly says it does not apply the revision, implicitly directing application to `rws_overview_apply`. It does not spell out exclusions or prerequisites beyond that.

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 non-destructive, idempotent, closed-world mutation semantics. The description adds the useful fact that no demo records are inherited, but it doesn't explain what 'confirmed foundation' means, what side effects occur, or how the optional 'demo' parameter interacts with that statement.

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?

It is a single front-loaded sentence with no filler. The terseness is efficient, though it contributes to the lack of explanatory detail.

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 six-parameter creation tool with no output schema and zero schema descriptions, the definition is far too thin. It should at minimum explain the required requestId, name, and what happens when demo is true.

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% across six parameters, and the description explains none of them. Required requestId and name, plus optional demo, goal, domain, and projectId, are left entirely opaque; notably the 'demo' parameter appears to interact with the statement about demonstration records but is never clarified.

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 verb+resource pair 'Create an independent project' is clear, but 'initial confirmed foundation' and 'demonstration records are inherited' are unexplained domain jargon. It does not clearly differentiate this tool from siblings such as rws_project_list or rws_overview_propose beyond the word 'create'.

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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no note about required requestId/name or idempotency behavior. The agent must infer usage entirely from the name.

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=false, so the safety profile is covered. The description's only added context is the scope word 'confirmed' for foundations, which is left undefined; it says nothing about result size, ordering, or whether all projects or only active ones are returned.

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?

A single front-loaded sentence with no filler. It is arguably under-specified rather than verbose, but nothing in it wastes space.

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

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

For a no-param, no-output-schema list tool, the description should at least explain what a 'confirmed foundation' is and roughly what the return contains. Annotations cover safety but not the shape or scope of results, leaving a meaningful 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter meaning the description could or should add. The only caveat is that with no filters, the description could clarify that everything is returned unfiltered.

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

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

States a specific verb (list) and resource (projects), which distinguishes it from the mutating sibling rws_project_create. However, the phrase 'confirmed foundations' is unexplained jargon, so an agent cannot tell exactly what the second resource category is.

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?

No indication of when to call this versus alternatives such as rws_record_get or rws_get_context, which likely also surface project data. The agent gets no routing signal beyond the tool name.

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=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context — stage changes require a human decision and read-only browsing/completed runs must not advance stages — but says nothing about replacement semantics for activeStages (does it overwrite the whole set?), revision-conflict behavior, or authorization requirements.

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 very short sentences with no filler, which is structurally fine, but the size is achieved through omission rather than economy. The most decision-relevant fact (that this overwrites the project's stage set under a revision check) is absent.

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?

This is a four-parameter, fully required mutation with zero schema descriptions and no output schema, so the description must be self-sufficient — and it is not. An agent cannot tell from it what a valid call looks like or what guarantees it has that the write succeeded and did not clobber a concurrent change.

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% across four required parameters, so the description carries the full burden and mostly fails it. 'current-stage' loosely gestures at activeStages, but projectId, requestId and especially expectedRevision (optimistic-concurrency token) get no explanation at all.

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 reads as a policy statement ('Human-only current-stage decision') rather than a statement of what the tool does. Only the tool name reveals that it sets a project's active stages; the sentence alone does not specify a verb, the resource being modified, or how it differs from siblings like rws_project_list or rws_project_create.

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?

'Human-only' implies agents should not call it autonomously, and 'browsing and completed runs never advance stages' gives a partial when-not condition. But it never states the condition that selects this tool over the surrounding project/overview/amendment tools, so the routing guidance is only implied.

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 state write, non-destructive, idempotent, closed-world. The description adds one genuinely useful behavioral fact — the registration is immutable — which implies retries are safe but edits require a new record/amendment. It stops short of stating conflict or concurrency behavior despite requiring expectedRevision.

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?

A single front-loaded clause with no filler or redundancy. It is efficient, though its brevity is partly under-specification rather than pure tightness.

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 nested, 4-required-param mutation with zero schema descriptions and no output schema, the description is too thin: it omits revision/conflict semantics, error behavior on duplicate ids, and how the nested metric objects are shaped. Immutability alone does not give an agent enough to call this correctly.

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

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

Schema description coverage is 0% across 4 required top-level params and a deeply nested record. The sentence echoes the record sub-fields (metrics, preprocessing, aggregation, missingPolicy) but says nothing about requestId, projectId, or the required expectedRevision optimistic-concurrency token, which is the parameter most likely to cause failure.

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?

Names a specific verb ('Register') and a specific resource (evaluation metric/protocol definitions, with preprocessing, aggregation and missing-data policy). That is clearly distinct from siblings like rws_dataset_register or rws_code_register, though it never says so 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?

No when-to-use guidance, no prerequisites, no alternatives. The 'immutable' wording hints that once registered a revision is frozen, but the caller gets no instruction on when this tool is the right choice versus, e.g., rws_amendment_propose or rws_spec_save.

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 a safe, idempotent, read-only, closed-world operation. The description adds that it can retrieve a historical version, but does not cover not-found behavior, permissions, or response 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?

The description is a single front-loaded sentence with no filler. It is tightly scoped, though its brevity leaves gaps that are captured in other dimensions.

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 nested-ref tool with no output schema and no schema field descriptions, the definition is too thin. It does not explain the ref object's required fields, valid record types, or what a returned record contains.

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% and the single parameter is a nested ref object with required projectId, type, and id plus optional version. The description only hints at the version field via "historical version" and does not explain the ref structure or enum type meanings.

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

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

The description states a specific verb and resource: read a record or historical version. The word "exact" helps distinguish it from broader query siblings, but it does not explicitly name or contrast against any sibling 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?

It implies use when an exact record reference is known, but gives no explicit when-to-use guidance, prerequisites, or alternatives such as querying. The agent must infer when this is preferable to rws_result_query or other retrieval tools.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, so safety is covered. The description adds the valuable idea that referenced evidence becomes a frozen snapshot rather than a live link, which is real behavioral context beyond annotations, but it says nothing about concurrency handling or what happens on a stale expectedRevision.

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 front-loaded sentence with the action first and no filler. It is efficient, though the compression into jargon costs comprehension rather than saving space productively.

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?

Against a deeply nested record schema, four required parameters, and no output schema, a single sentence is not sufficient. Nothing explains the two-pass record semantics (id-only vs full record), version pinning on refs, or the revision conflict behavior.

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 25% — only `record` has a description. The description itself mentions no parameters, leaving requestId (idempotency key) and expectedRevision (optimistic concurrency guard) unexplained in both places, which is a critical gap for a mutation tool.

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 verb+resource pair 'Create a report version' is identifiable, but the qualifier 'immutable foundation and transitive evidence snapshots' is opaque jargon that does not tell an agent concretely what the resulting version contains or how it differs from a plain record save.

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?

No statement of when this tool should be used versus alternatives such as rws_record_get or any save/register sibling, and no prerequisites (e.g., a prior base revision) are given. The agent must infer the workflow entirely.

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=false, idempotentHint=true, destructiveHint=false, so the write/idempotent profile is covered. The description adds a genuine governance fact — saving does not confer scientific validity, so judgment fields remain human-owned — which is context beyond the annotations. It omits the more consequential behaviors: upsert/merge semantics for an existing id and the mandatory optimistic-concurrency revision, both of which an agent must understand before calling.

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?

A single front-loaded sentence with the resource stated first and the caveat second; nothing is wasted. It is arguably too terse for a tool with nested objects and four required parameters, but there is no padding 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?

This is a nested-object mutation with 25% schema coverage, no output schema, and a required concurrency token, so the description should carry more weight than one clause. Key operational facts — merge-vs-replace on update, stale-revision failure behavior, and that kind/stage/status drive the record shape — are absent. What is present is accurate but insufficient for confident 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 only 25%, so the description is expected to compensate, and it largely does not. It hints that the hypothesis is optional and that the question is the core payload, but says nothing about requestId, projectId, or the required expectedRevision, which is the highest-risk parameter for a mutation tool. The richer guidance (omitted fields preserved, explicit null clears) lives only in the schema's record 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?

Specific verb+resource: 'Save a research question or optional hypothesis' clearly identifies the record type being written, and the 'research' resource name implicitly separates it from rws_experiment_save, rws_spec_save, rws_usage_save and other *_save siblings. It does not explicitly name an alternative, but an agent can tell 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?

No statement of when to use this versus rws_experiment_save or rws_spec_save, no mention of create-vs-update behavior, and nothing about the required expectedRevision concurrency check. The only guidance, 'does not decide scientific validity,' is a scope caveat rather than a use condition.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description usefully adds that results retain producer/case/configuration/observation coordinates and are never silently merged, which is real behavioral context. It says nothing about ordering, pagination behavior, or result size limits despite limit/offset parameters.

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 tight sentences with the purpose front-loaded and no filler. The second sentence is dense but earns its place by disclosing de-duplication behavior.

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?

Six parameters, one required, with 0% schema description coverage and no output schema. Pagination semantics, filter combination rules, and the shape of returned results are all undocumented, which is a substantial gap for a query tool handling multiple coordinate types.

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% and the description never mentions projectId, limit, offset, codeRefs, sampleIds, or semantics by name. The phrase "producer, case, configuration and observation coordinates" hints at filter dimensions but cannot be mapped to any parameter, so the schema gaps stay unaddressed.

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 ("Find") and resource ("exact outputs across runs in this project") with a scoping constraint. It does not name or differentiate itself from plausibly overlapping siblings such as rws_record_get or rws_get_context, so an agent can't be fully sure which to pick.

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?

There is no statement of when to use this tool, when not to, or which sibling to prefer for related lookups. Only an implicit usage is conveyed by the word "Find", leaving routing decisions entirely to inference.

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

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

Annotations already establish that this is a write operation that is idempotent and non-destructive. The description adds meaningful behavioral context beyond annotations: it clarifies that no program is launched and that producer bindings are immutable. It does not cover concurrency or authorization behavior, so it is not a 5.

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

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

Two short sentences, front-loaded with the core action and followed by two high-value behavioral constraints. There is no filler or redundant restatement.

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?

This is a complex mutation with a nested record schema, four required parameters, low schema coverage, and no output schema. The description does not explain expectedRevision, requestId idempotency, or key record semantics, leaving significant gaps for correct invocation despite useful annotations.

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 low at 25%, and the description does little to compensate for the four required parameters. It mentions 'status' and 'run' conceptually, but does not explain requestId, projectId, expectedRevision, or the structure of the record beyond what the schema itself says.

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 a specific verb and resource: recording an actual run and its status. It is distinguishable from write-oriented siblings like experiment_save and code_register by focusing on run records, but it does not explicitly name an alternative or sibling to avoid, so it falls short of 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?

The note that registration never launches a program implicitly tells the agent this is for recording, not executing, a run. However, there is no explicit guidance on when to use this versus related save/register tools, and no when-not-to-use conditions are stated.

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

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

Annotations already cover the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description only needs to add what they don't. It adds useful semantics — draft vs ready revisions and that implementations pin an exact ready revision — implying ready revisions are effectively immutable, but says nothing about optimistic concurrency via expectedRevision, the idempotency role of requestId, or what happens on a stale revision.

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, front-loaded with the purpose, then the revision behavior, then the boundary rule. No filler and nothing repeated from 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?

This is a mutation tool with a deep nested record, no output schema, and no annotations explaining concurrency or error behavior. Given the low schema coverage, the description should explain expectedRevision conflicts and requestId semantics; instead it omits all parameter guidance.

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 25% and the description never mentions any of the four required parameters. The critical semantics of expectedRevision (concurrency guard) and requestId (idempotency key) are undocumented in both schema and description, leaving the agent to guess how to call this correctly.

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: defines and saves a method-level contract revision, with a clear scope statement that this is a contract, not a run. It distinguishes reasonably from run-related siblings but doesn't explicitly contrast itself with the many other *_save siblings (research_save, experiment_save, protocol_register).

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?

"Define a method-level contract before implementation" gives clear timing, and "Cases/configurations belong to runs, not method contracts" actively excludes a tempting misuse. No alternative tool is named for when a contract already exists or when a different save sibling is appropriate.

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=false and idempotentHint=true; the description adds genuine value by stating the operation is scoped so source artifacts and other uses survive. However it says nothing about permission requirements, error/conflict behavior when expectedRevision is stale, or whether revocation is reversible.

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?

A single tight sentence with the scope constraint front-loaded and no filler. It is efficient, though efficiency here edges toward under-specification rather than disciplined brevity.

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 non-read-only mutation with four opaque required parameters and no output schema, the description does not say what a success response looks like, what happens on revision mismatch, or what a 'usage' refers to in this domain. The one clarifying clause does not cover the operational surface an agent needs.

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% with four required parameters (id, projectId, requestId, expectedRevision), and the description explains none of them. In particular the optimistic-concurrency role of expectedRevision and the idempotency role of requestId are never surfaced, leaving the agent to guess from bare names.

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

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

Specific verb ('Revoke') plus resource ('material usage') with a scope qualifier ('without deleting source artifacts or other uses'). An agent can distinguish it from rws_usage_save by the revoke/save contrast, though the description never names the counterpart 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?

No statement of when to use this versus rws_usage_save or the propose/apply/dismiss families, and no prerequisites or preconditions. The 'without deleting...' clause clarifies blast radius rather than routing, so usage context is left entirely to inference.

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

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

Annotations already disclose that this is a non-destructive, idempotent write. The description usefully adds that cross-project reuse is allowed and that the original producer remains unchanged, but it does not explain permissions, revision-conflict behavior, or requestId/idempotency semantics.

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

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

Two compact sentences, front-loaded with the core action and scope. There is no wasted wording and the key non-destructive behavior is stated directly.

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?

This is a complex write tool with 8 parameters, nested objects, no output schema, and zero schema description coverage. The description covers the high-level intent but leaves critical invocation details—especially expectedRevision, role, and nested refs—unexplained.

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% across 8 parameters, including nested artifactRefs and experimentRef objects. The description hints at artifact references and a target experiment, but provides no meaning for requestId, expectedRevision, role, label, or the nested reference structure.

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 action—referencing precise artifacts—in a clear target context (an experiment), and adds scope via cross-project reuse. It does not, however, distinguish this tool from sibling registration/save tools such as rws_artifact_register or rws_usage_remove.

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 implies that the tool is used to reference artifacts in an experiment, but gives no explicit when-to-use guidance, no when-not-to-use conditions, and no alternatives. With many sibling registration and usage tools, an agent is left to infer routing.

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