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

Annotations only declare that this is a non-read-only, non-destructive, closed-world write. The description goes further by disclosing the persistence behavior (survives update_source revisions), the local-versus-remote file access constraint, and the return payload (stored name and served url). It stops short of covering overwrite semantics or any size/error limits.

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

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

Four dense sentences, front-loaded with purpose and followed by the key parameter rule, the one-time-attach rule, the transport-specific alternative, and the return value. Nothing is padding, and the local/remote distinction is stated in the order an agent would need it.

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 mutation tool with no output schema, the description covers the return value, the persistence contract, and transport-specific parameter requirements, which is close to everything an agent needs. The remaining gap is re-attach/overwrite behavior for an already-backed `name`.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine meaning: `name` is the exact `<img>` src the draft uses and acts as the match key, with concrete format examples ('/assets/x.png', 'fig/y.svg'), and it explains the `path` versus `content_b64` tradeoff by deployment mode. That is meaning beyond the schema's own field descriptions.

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

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

The description opens with a specific verb and resource: 'Attach an image to a review so the viewer serves and renders it.' It names the downstream effect (rendering in the viewer) and, combined with sibling names like list_assets and update_source, an agent can immediately tell this is the write-side counterpart to asset listing.

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 clear operating guidance: attach once because the asset survives every update_source revision, use `path` on the local stdio server to avoid pulling bytes through the conversation, and use `content_b64` on a remote server that cannot read local files. It does not say what happens if the same `name` is attached twice, which is the main when-to-call edge case left open.

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-read-only, non-destructive, closed-world write, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the anchor highlights every occurrence of the phrase in the viewer, attribution follows `role`, and the result becomes a normal thread that can be replied to or resolved. It stops short of saying whether duplicate anchors or non-matching phrases are rejected.

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 front-loaded sentences: purpose first, then the two anchoring parameters, then the post-creation consequence. Parentheticals carry useful asides rather than filler, though the closing sentence about replying/resolving edges toward extra prose that could be trimmed.

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

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

For a 4-parameter write tool with no output schema, the description covers purpose, anchoring semantics, attribution, and the resulting thread lifecycle, which is enough to call it correctly. The one gap is that it never says what comes back (e.g., a comment id), which matters because get_comment and reply_to_comment presumably need one.

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

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

Schema coverage is 100%, so every parameter is already documented, which sets the baseline at 3. The description does add real meaning on top — 'exact phrase from the source', the highlight-wherever-it-occurs behavior, and the omit-for-doc-level rule — but it does not clarify what happens when `quoted_text` does not match the source.

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 ('Author a NEW comment on a document') plus its defining scope: anchored to a quoted phrase versus a document-level note. The emphasis on 'NEW' implicitly separates it from reply_to_comment, so an agent can pick it out of the sibling list without opening a schema.

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

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

It gives clear situational guidance — use this to leave review feedback at a specific spot as a reviewer — and spells out the branch condition: omit `quoted_text` for a document-level note. What it lacks is an explicit hand-off naming reply_to_comment or create_review as the alternative when the agent is not starting a new thread.

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

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

Annotations only declare that this is a non-read-only, non-destructive, closed-world write. The description adds genuinely load-bearing behavior beyond that: kind is immutable, a latex-enabled server rejects non-latex creates, and re-creating in another format produces a new id/url with comments and history lost.

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

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

Purpose and return values are front-loaded, and the rendering guidance is dense but useful. However, the kind-immutability caveat appears twice (once mid-paragraph, once in the closing sentence) and largely restates the schema's own warning, which is mild redundancy in an otherwise tight block.

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?

Despite seven parameters, one required, and no output schema, the description covers return values, both document modes, rendering capabilities, and irreversible-state caveats. An agent has everything it needs to call this correctly and to warn its user before an irreversible choice.

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

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

With only 43% schema description coverage, the description carries real weight: it explains kind's semantics and irreversibility, clarifies that markdown holds raw LaTeX under kind=latex, and says project/session/source_path record draft provenance for the dashboard. title and template are left to the schema, and template is already richly documented there, so the gap is minor.

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 and resource ('Create a review from markdown') and even names what it returns (the id and the review and feedback urls). The two modes (markdown vs latex) are clearly laid out, so an agent can distinguish this from list_reviews/get_review/update_source without opening any schema.

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

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

Gives concrete decision rules: use kind="latex" when the body has \documentclass/\begin{document} or a .tex source_path, use ```mermaid for flows/decision trees/state machines, and attach images with attach_asset. It doesn't discuss when to create a new review versus updating an existing one via update_source, which is the one relevant alternative left unaddressed.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses that the whole thread goes with the comment (a cascade not visible in the schema) and that the action is irreversible. It stops short of saying whether replies by other users are included or what the response contains, but the key risk is disclosed.

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

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

Two sentences, no filler. The irreversibility warning is front-loaded before the alternative routing, which is the correct priority order for a destructive tool.

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

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

For a two-required-parameter destructive tool with no output schema, everything an agent needs is present: what is destroyed, that it cannot be undone, and which sibling to pick instead. Annotations handle the safety hints and the schema handles the identifier formats.

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

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

Schema description coverage is 100%, and the schema already clarifies that document_id is the review id and comment_id follows the cXXXXXXXXXX format. The description adds no further parameter-level meaning, which is acceptable given the schema already carries that burden.

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

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

States a specific verb and resource ('Permanently deletes a comment and its whole thread') and immediately scopes the blast radius to the entire thread. This distinguishes it cleanly from resolve_comment and the other comment siblings without needing the schema.

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

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

Gives an explicit when-to-use ('remove a comment created by mistake') plus the named alternative and its contrasting behavior ('resolve_comment marks a real comment addressed and keeps it in the Resolved panel'). The agent can choose between the two destructive-looking options on intent alone.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The phrase "and its data" adds a small amount of context about cascade effects, but does not say whether deletion is permanent, undoable, or whether attached assets/comments go with it. With annotations carrying the mutation semantics, a 3 is appropriate.

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 short sentence, front-loaded with the verb and resource, with no filler. It is arguably too terse rather than bloated, so conciseness is not the weakness.

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

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

For a destructive mutation with no output schema and no annotations explaining return behavior, the description should say what happens after deletion (return value, cascade scope, irreversibility). It leaves all of that unstated, so an agent cannot predict the effect of the call beyond "something gets deleted".

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

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

Schema coverage is 100% and the single parameter is documented as "the opaque review id", so the schema does the heavy lifting. The description adds nothing beyond that, which is the expected baseline when schema coverage is complete.

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 ("Delete a review") and its scope ("and its data"), clearly distinguishable from list_reviews, create_review, get_review, and delete_comment among the 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?

No guidance on when to use this versus update_review-like alternatives, no prerequisites, and no warning about when deletion is inappropriate. The agent must infer that it takes an opaque id from a prior get_review or list_reviews call.

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 (readOnlyHint=true, openWorldHint=false), so the bar is lower, and the description still adds real value by disclosing the return shape: every reply plus status_history transitions. With no output schema, that payload hint is the main source of return-value information, though it doesn't mention ordering, pagination, or behavior when the comment is deleted.

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, front-loaded with the verb and scope, with the parenthetical used efficiently to enumerate the returned content. Nothing redundant, nothing padded.

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

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

For a two-parameter read tool with full schema coverage and explicit read-only annotations, this is close to complete; the description supplies the return contents that would otherwise be missing without an output schema. Only minor gaps remain, such as error or empty-thread 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 100% and both parameters are documented in-schema with id formats, so the baseline of 3 applies. The description adds no further meaning about document_id versus comment_id or their relationship beyond what the schema already states.

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?

"Fetch one comment thread in full" names a specific verb and resource and scopes it to a single thread, which implicitly contrasts with the list_comments sibling. It stops short of naming the alternative tool explicitly, so an agent still has to infer the boundary from the sibling list.

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 "one comment thread in full" suggests this is the single-thread read as opposed to a listing. There is no explicit when-to-use, no exclusion (e.g. when to prefer get_feedback or get_status), and no stated prerequisite that both ids must already be known.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real value by describing what comes back (structured notes with a comment projection plus rendered markdown). It does not say what happens when a review has no feedback yet, or whether output size is bounded, which keeps it off 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 tight sentences with the core capability front-loaded and the routing hint second. Minor waste in "now including" (temporal versioning cruft) and "projection of the comments," which is jargon a caller must interpret.

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

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

For a single-parameter read tool with no output schema and annotations already covering safety, the description covers purpose, return shape, and the key alternative. Slight gap on empty-state behavior and on how markdown content should be consumed, but nothing that would cause a mis-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?

Only one parameter, and schema coverage is 100% with "the opaque review id" already documented in the schema. The description adds no format or sourcing detail for the id, so the schema carries the full burden and baseline 3 applies.

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

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

States a specific verb and resource ("Get a review's human feedback") and immediately qualifies the scope: structured notes plus a rendered markdown block, not raw comment threads. That scope statement is what separates it from the comment-oriented siblings, so an agent can identify the tool without opening the schema.

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

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

Explicitly routes the agent elsewhere when the intent differs: "For the full threads use list_comments." This names the exact overlapping alternative and the condition that selects it, which is the main ambiguity a caller would face among list_comments/get_comment/reply_to_comment.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false; the description goes beyond them by stating the failure mode (404 when git history is disabled) and clarifying the scope of read-only ("no push, no branching"). It also explains the shape of the returned history, which the annotations cannot convey.

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

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

Three short sentences, front-loaded with the return value, followed by the availability constraint and the safety note. Every clause carries information an agent needs; nothing is padding.

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

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

With no output schema, the description must explain the return value, and it does (a git clone URL with one commit per round plus a live tip, usable by standard git tooling). It also covers availability and the 404 failure mode. Only minor details, such as whether the URL embeds credentials or expires, are unstated.

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?

There is a single parameter with 100% schema description coverage ("the opaque review id"), so the schema already carries the semantics. The description adds nothing about the id — such as whether it accepts a short id or slug — so the baseline 3 applies.

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

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

"Returns a git clone URL for a review's history" names a specific verb (returns) and a specific resource (a git clone URL), and the follow-on clause explains exactly what that URL points at (one commit per past round plus a live tip). An agent can distinguish this from get_history or get_source without opening a schema, though no sibling is named explicitly.

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

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

It gives a real precondition — the server must have git-tracked history enabled, otherwise the call returns 404 — which tells the agent when the tool will succeed. It does not, however, point to alternatives such as get_history or get_source for agents that want the review's rounds without cloning, leaving the routing choice 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the single-round mode returns a past draft plus received feedback, which is useful given there is no output schema, but says nothing about what the list mode returns (round identifiers, summaries, ordering) or about pagination.

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 clauses, front-loaded with the default behavior and then the parameterized variant. No filler and no redundancy with the title.

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

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

For a two-mode read tool with no output schema, the single-round return is described but the list-mode return is not, leaving an agent guessing what a 'past round' entry contains. Adequate but with a clear gap in the more commonly used default mode.

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

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

Schema coverage is 100% and the schema already states 'round number; omit for the list', so the schema carries most of the load. The description adds the outcome of supplying `round`, but nothing about valid ranges, default round, or what `id` must refer to beyond the schema's 'opaque review id'.

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

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

States a specific verb and resource ('List a review's past rounds') and adds a second mode ('with `round`, fetch one past draft plus the feedback it received'). The 'past rounds' framing distinguishes it from get_review/list_reviews, though no sibling is named 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?

Gives clear mode-selection guidance: omit `round` for the list, supply it for a single past draft plus its feedback. It does not explicitly point to an alternative tool (e.g. get_feedback for current feedback), 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?

The annotations already declare readOnlyHint=true and openWorldHint=false, so the description adds almost no behavioral context beyond the operation name. It does not mention error behavior for an unknown id, access requirements, or whether the response is a full review versus a metadata subset.

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 short sentence with no wasted words and is front-loaded with the action and resource. Brevity is not itself a problem here, even though more detail would improve 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 one-parameter read tool with annotations covering safety, the description is minimally adequate. However, without an output schema, it leaves the returned 'metadata' undefined and does not help an agent distinguish this tool from other review-related getters.

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

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

Schema description coverage is 100%, and the single id parameter is already documented as 'the opaque review id.' The description adds no parameter meaning or format guidance beyond what the schema provides, so the high-coverage baseline of 3 applies.

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

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

The description states a specific verb and resource: get one review's metadata. This distinguishes it from list_reviews by singular scope, but it does not differentiate it from other get_* tools such as get_feedback, get_status, or get_history, and 'metadata' is somewhat vague.

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 when-to-use guidance beyond the implied retrieval by id. The description does not say when to choose get_review over list_reviews or the other get_* siblings, nor does it state prerequisites or exclusions.

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

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

Beyond the readOnlyHint annotation, the description explains that the default return is the raw document verbatim and that with_revision=true returns a JSON envelope with source and revision. It also discloses the important concurrency behavior that the revision is issued atomically with this read and pairs with update_source's expected_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?

The description is front-loaded with purpose and usage, then moves cleanly into default behavior and the with_revision alternative. Despite the dense concurrency detail, every sentence contributes operational information and there is no extraneous material.

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

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

With no output schema present, the description adequately explains both return modes: raw verbatim source by default and a JSON envelope with source plus revision when requested. It also supplies the critical cross-tool concurrency context needed to use the revision token correctly with update_source.

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

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

Schema coverage is 100%, so the schema already documents both parameters in detail. The description still adds meaningful semantics beyond the schema by explaining the atomic issuance of the revision token and warning against using a separate get_status poll as the token source for guarded saves.

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

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

The description states a specific verb and resource: get a review's current source, defined as the editable draft in markdown or raw LaTeX for kind=latex reviews. It clearly distinguishes source retrieval from related operations such as get_feedback, get_status, and update_source, so an agent can identify the right tool without inspecting sibling schemas.

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

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

The description gives explicit usage conditions: read the source before applying feedback when the draft is not in memory, such as a resumed session. It also distinguishes the default raw-document mode from with_revision=true and explicitly says to use this tool, not a separate get_status poll, as the revision token source for guarded saves.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description goes well beyond that. It discloses cost ('cheap'), the exact fields carried, the meaning of each source_updated_by value ('reviewer' vs the default 'agent'), and a specific correctness hazard about sourcing revisions. That is meaningful behavioral context an agent cannot get from the structured fields.

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

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

The key traits are front-loaded ('Cheap poll:') and nearly every clause carries new information about return values or the revision trap. The parenthetical issue references (#288, #289) are noise for an agent, and the nested quoting makes one sentence long and dense, which is the only real drag on structure.

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

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

There is no output schema, so the description must describe what comes back — and it does, enumerating the timestamps, revision, can_edit, and source_updated_by, plus how to interpret the latter. For a one-parameter read tool, an agent has everything needed to call it and to act on the response 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?

With a single required parameter at 100% schema description coverage ('the opaque review id'), the schema already carries the semantics and the baseline is 3. The description adds no syntax or format detail about the id beyond what the schema states, so it neither compensates further nor is required to.

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 framing — a 'cheap poll' returning source_updated, feedback_updated, and comments_updated timestamps for a review — which is a concrete verb-plus-resource statement. It implicitly separates itself from get_review (full object) and get_source (text payload) by scoping itself to timestamps plus a couple of small flags. An agent can tell which sibling to reach for without opening any schema.

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

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

It names an explicit alternative and the condition that selects it: for a guarded update_source, take the revision from get_source(with_revision=true), 'never from this poll.' It also gives a conditional action rule — if source_updated_by is 'reviewer', re-read the source before saving — which is when-to-use guidance with a concrete trigger. Both a when and a when-not are present.

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

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

Annotations only declare the generic non-read-only, non-destructive profile; the description adds the concrete state machine (turn=reviewer, state=done vs state=blocked), the resulting banner copy the human sees, and a hard availability limit on latex reviews. This is meaningful effect-level context an agent cannot get 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 is front-loaded and every sentence carries new information (state meaning, workflow ordering, exclusion). The first sentence is dense with two parenthetical banner variants, which slightly slows parsing but is not padding.

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 3-parameter tool with full schema coverage, no output schema, and existing annotations, the description covers workflow position, state effects, error/precondition (latex reviews), and follow-up behavior. Only minor gaps remain, such as what the tool returns on success.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds outcome semantics: it explains what each state produces in the reviewer's banner and that `message` surfaces there, going beyond the schema's terser phrasing. It does not add format constraints on `message` length beyond the schema's 'one-line'.

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 ('Hand the turn back to the reviewer') and immediately defines the mechanism ('Sets turn=reviewer on the review'), which distinguishes it from siblings like update_source, reply_to_comment, and resolve_comment that also touch a review.

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

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

It gives explicit sequencing ('Use it after update_source and the replies or resolves on the comments you addressed'), an alternative branch for blocked cases paired with a comment reply, and an explicit exclusion ('Reopening a comment is a reviewer action... Not available on a kind=latex review').

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the response shape (name, stored name, served url, bytes, ctype), but says nothing about ordering, pagination, or behavior when no assets are attached. With annotations carrying the safety bar, a 3 fits.

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 zero preamble waste; the parenthetical field list is dense but earns its place by substituting for a missing output schema. Slightly terse, but nothing is redundant.

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

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

With no output schema, the field enumeration fills the main information gap for a simple one-parameter read tool. Missing only minor operational detail such as ordering or behavior on an empty asset set.

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

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

Schema coverage is 100% and the single id parameter is documented as "the opaque review id". The description reinforces that assets belong to a review, matching that parameter, but adds no format or constraint detail beyond the schema. Baseline 3 is appropriate.

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

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

The description names a specific verb and resource ("List a review's attached assets") and enumerates the returned fields, so an agent knows exactly what it gets back. It doesn't explicitly distinguish itself from the write-side sibling attach_asset, but the read semantics are clear.

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 when-to-use guidance and no mention of alternatives such as attach_asset or get_review. The agent must infer that this is the read counterpart used before or after attaching assets.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered by structured data. The description adds the default status of 'open', which is genuinely useful behavior context, but says nothing about ordering, pagination, or whether replies are included in results. With annotations carrying the main burden, this is adequate but thin.

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 with the purpose and filter front-loaded and no filler. The second sentence shifts from listing to workflow advice, which is mildly tangential for a list operation but still compact and readable.

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 simple two-parameter read tool with full schema coverage, no nested objects, and no output schema, so the description needn't explain return values. Purpose, scope, and the filter default are all covered; only ordering and reply-inclusion behavior are left undefined.

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

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

Schema description coverage is 100%, so baseline 3 applies. The description merely restates the enum values and default that the schema already documents ('open (default), resolved, reopened or all'), adding no syntax or interpretation guidance beyond it.

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

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

The description states a specific verb and resource ('List comments on a document') and names the filtering dimension, so it is clearly distinguishable from siblings like create_comment or get_comment. It stops short of explicitly contrasting itself with those siblings, which keeps it at a 4 rather than 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?

It gives a clear context (list comments on a document, default filter open) and hints at the follow-up workflow by mentioning replying to and resolving comments. However, it never names the sibling tools reply_to_comment or resolve_comment, and it gives no when-not-to-use guidance, so the routing 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds information the annotations do not: the returned shape (status with its awaiting/feedback/resolved values, note counts, revision), which is meaningful because no output schema exists.

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

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

One sentence, front-loaded with the action and immediately followed by the returned fields. No filler wording or redundancy.

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

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

For a zero-parameter, no-output-schema read tool, the description plus annotations give an agent enough to call it and interpret the result. The remaining gap is scope behavior: whether results are paginated, ordered, or truncated for large review sets is unstated.

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 and there are no argument semantics to explain. The description correctly avoids inventing filters or options that don't exist in the empty 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?

"List every review" gives a specific verb and resource, and the word "every" implicitly separates it from get_review, which returns a single review. It stops short of naming that sibling explicitly, so the differentiation is inferred rather than stated.

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

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

The enumeration framing implies when to reach for this tool (browsing all reviews) rather than get_review, but there is no explicit when-to-use or when-not-to-use guidance. With 20 siblings including get_review and get_status, a single routing sentence would have added real value.

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

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

Annotations only declare readOnly=false, destructive=false, openWorld=false; the description adds lease ownership semantics, the 409 conflict condition and correct response, the non-effect on turn state, and the UI consequence ('Agent is working…' vs stale stopped hint). That is substantive behavior an agent cannot infer from the structured fields.

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

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

Front-loaded with the action, then discovery, cadence, failure handling, and the latex exclusion in descending order of importance. Every clause carries operational information; nothing restates the title or schema verbatim.

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 lease/heartbeat tool with no output schema and only generic annotations, the description covers acquisition, renewal cadence, conflict handling, failure mode, side effects, and one platform exclusion. An agent has everything needed to call it correctly and to recover from the 409 case.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by clarifying that `owner` must be YOUR session id and by explaining the cross-owner conflict outcome that makes the parameter's value matter. `message` is only implied ('status shown in the banner'), so it stops short of 5.

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

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

States a specific verb+resource ('Claim or renew your lease on a review') plus what it is not ('Does NOT change whose turn it is'), which distinguishes it from siblings like hand_back and get_status. It also names the sibling tools used for discovery, so the agent can place it in the workflow without opening schemas.

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

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

Explicit lifecycle guidance: poll list_reviews / get_status for reviews with turn=='agent', call this immediately, then periodically while working. It also gives a when-not ('Not available on a kind=latex review') and prescribes the recovery action on 409 (back off and skip).

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 and destructiveHint=false, so the write-but-safe profile is covered; the description's added value is the non-obvious fact that posting a reply does not change the comment's resolved state. It says nothing about permissions, whether the reply triggers notifications, or whether the created reply is returned (no output schema exists), leaving real behavioral blanks 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?

Two sentences, no filler, and the critical non-resolution constraint is front-loaded in caps before the usage guidance. Every clause earns its place.

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

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

For a simple three-required-parameter write with full schema coverage, the description covers purpose, the key state-caveat, and when to choose it. Only the return behavior and any permission requirements are unaddressed, which is a minor omission at this complexity level.

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

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

Schema coverage is 100% with all three required parameters documented, so the schema already carries parameter meaning; the description adds no format or constraint detail (e.g., reply length, whether text supports markdown). Baseline 3 is appropriate.

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

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

"Add a reply to a comment WITHOUT resolving it" gives a specific verb (add reply), the resource (comment), and an explicit scope boundary (no resolution) that separates it from resolve_comment in the sibling list. An agent can distinguish it without reading any schema.

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

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

It states concretely when to use it (comment is a question, needs discussion, or a response before deciding) and gives a condition for the alternative behavior ("resolve only once the issue is actually addressed"). The alternative is described behaviorally but the sibling tool name resolve_comment is never cited explicitly, which is the only gap.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses the concrete side effect: the comment leaves the active document and moves to the Resolved panel. It also explains reversibility asymmetries — the agent can never reopen, but a reviewer can — and that the justification note is appended to the thread and attributed to the agent.

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 action and precondition are front-loaded, and the optional-parameter semantics come next before the workflow detail. The closing sentence on reopening is slightly long and could be tightened, but no sentence 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 three-parameter mutation with no output schema, the description covers the side effect, the later state the agent will observe, and the follow-up discovery path via list_comments. It does not address edge cases such as resolving an already-resolved comment, a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond 'optional note explaining the resolution': it explains where the note goes (appended to the thread), who it is attributed to (the agent), what happens if omitted (silent resolve), and why it is recommended (reduces back-and-forth since the reviewer can reopen).

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 pair ('Mark a comment resolved') and adds a precondition ('once you've actually addressed it') that scopes the action. It implicitly separates itself from delete_comment and reply_to_comment by describing a state transition to the Resolved panel rather than removal or a threaded response.

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 clear usage context: resolve only after addressing the comment, and it names list_comments (status reopened/open) as the follow-up path once a reviewer reopens. It does not explicitly contrast with sibling alternatives like delete_comment or reply_to_comment, so the routing guidance is contextual rather than comparative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description goes further by disclosing that no network/service call occurs, that the data reflects only the running process, and what a hash mismatch implies (stale process, requires client reconnect). That staleness semantic is behavior an agent could not infer from annotations or schema.

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

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

Three sentences, front-loaded with the return payload, then the isolation caveat, then the operational workflow. No sentence is redundant and the CLI invocation is concrete rather than filler.

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

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

With no output schema, the description compensates by naming every returned field, and it covers the interpretive question (what tools_hash means, who can act on it) that an agent would otherwise be unable to answer. Nothing needed to call or interpret this tool is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is no argument semantics to clarify. The enumerated field list is really about return content rather than inputs, but with no output schema it usefully previews what comes back.

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 ('Reports this running MCP server's name, version, protocol_version, tools_hash, tool_count and tool_names') and immediately bounds the scope ('describes only the running process and makes no call to the service'). No sibling tool in the list returns process metadata, so it is trivially distinguishable from all 20 alternatives.

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

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

Explicitly assigns the tool to 'A human or CI' and names the concrete workflow (compare tools_hash against `python3 mcp_server.py --print-version` on disk, reconnect the client if they differ). It also states the negative case — an MCP-only agent has no on-disk value, so it cannot perform the check — which is unusually honest when-not-to-use guidance.

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

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

Beyond the destructiveHint=true annotation, the description discloses concrete behavior: a history round is snapshotted, the human's page is live-reloaded, LaTeX drafts are recompiled to PDF server-side, and stale writes fail with 409 while writing nothing. It also explains why the write is destructive — an unconditional or stale push can silently overwrite the human's concurrent edits.

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

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

Front-loaded with purpose and effects, then the concurrency guard, then the failure mode — a logical order for an agent. It is dense but every clause carries operational meaning, with only mild redundancy from repeating the 409/never-resend rule that also appears 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?

For a destructive write with no output schema, the definition covers what changes, what side effects occur, what can be destroyed (human edits), how conflicts surface, and how to recover — everything needed to invoke it correctly. Nothing material is left to inference.

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

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

Schema coverage is 100% and the expected_revision description already restates the 409/retry guidance, so much of the parameter text is duplication. However, the description adds a genuine non-obvious semantic the schema does not: for a kind=latex review the 'markdown' parameter actually carries raw LaTeX (a single .tex document), which the bare schema entry ('the new draft') would obscure.

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 ('Push a revised draft') and immediately explains the downstream effects (history snapshot, live reload of the human's page). It also differentiates the two rendering paths (markdown review vs kind=latex raw .tex recompiled to PDF) and references create_review for the rendering behavior, so an agent can distinguish it from siblings like create_review or hand_back.

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

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

Explicitly prescribes the safe workflow: read via get_source(with_revision=true), pass that revision as expected_revision, and on HTTP 409 re-read, re-apply, and retry. It also names the alternative mode ('Omitting expected_revision is an unconditional write') and warns against the wrong action (resending the earlier draft).

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