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

No annotations are provided, so the description carries the full burden and does so well. It discloses that the tool returns immediately, that the sessionId remains the same, that the reviewer's tab opens the new files, and that ended sessions cannot accept more files. These behavioral details go beyond a simple 'add' 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?

The description is five sentences with no wasted words. It front-loads the core operation, then gives usage triggers, compatibility, behavior, and limitations in a logical, efficient progression.

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 tool with no annotations and no output schema, the description is complete: it explains what the tool does, when to use it, what side effects occur, and what the agent should do when the session has ended. No critical information is missing.

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

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

Schema description coverage is 100%, so the schema already documents both sessionId and filePaths. The description adds only mild reinforcement ('same sessionId as before') but no substantive new parameter meaning. 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 states a clear action ('Add markdown files to a review session') and specifies the resource and constraint ('already open in mdr... without starting a new one'). It also distinguishes itself by noting compatibility with sessions from mdr_request_review and mdr_comment, so an agent can tell it apart from its 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?

The description gives explicit use cases: 'when the reviewer asks for another file mid-review' and 'when you need to comment on a file the session does not cover yet.' It also provides an exclusion and alternative: 'A session that has ended cannot take more files: start a new review instead.'

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

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

With no annotations provided, the description carries the full disclosure burden and delivers: three distinct return modes (all answered, partial replies on Done/Finish review, empty-handed on other session ends), a side-effect warning that replies land in marker threads on disk with the instruction to re-read files before concluding the user didn't answer, and the one-pending-ask-per-session concurrency constraint with its recovery path.

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?

Every sentence earns its place: purpose, return semantics, disk side-effect warning, usage criteria, then concurrency/error recovery. The opening sentence front-loads the primary purpose, and the longer second paragraph is justified by the subtle pending-ask recovery flow it documents.

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

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

For an async, user-interactive tool with no annotations and no output schema, the description covers purpose, all return cases, side effects, concurrency, and error recovery — remarkably complete. The main gap is that the reply payload shape is never specified ('returns with the reply text' / 'whatever partial replies exist' leaves the structure to inference), which an agent needs to know to consume the result reliably.

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

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

Schema coverage is only 50%, so the description must compensate. It adds the anchoring concept behind filePath/anchor and the sessionId reuse-and-retry flow ('pass this same sessionId plus a replies: payload targeting that commentId'). However, contextAfter and contextBefore remain undocumented in both the schema and the description, leaving some parameter meaning to inference.

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

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

The description opens with a specific verb-resource pairing: 'Ask the user one or more questions anchored to specific text in a file inside an active review session.' It further explains the inline-marker mechanism, which clearly differentiates it from siblings like mdr_comment (posting replies) and mdr_request_review (starting a review handoff).

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 usage criteria are given: 'Use this when a comment is unclear, or when you hit a planning fork while editing,' plus a decision heuristic: 'Prefer asking over guessing when the right answer would meaningfully change your edit.' It also covers the exclusion case — if a previous mdr_ask is pending, route through mdr_comment with a replies payload targeting that commentId instead of opening a second session.

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 no annotations provided, the description carries the full behavioral burden and delivers richly: it discloses the empty-file baseline for new files, the folder-must-exist prerequisite, the max 64-file limit, the too-late failure mode, and the keep-earlier-baseline dedup behavior. 'Returns immediately' also sets correct expectations of a non-blocking call. No important behavioral trait is left to inference.

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 critical timing instruction is front-loaded as the first clause, and nearly every sentence carries decision-relevant information. It runs slightly long and repeats one schema fact ('At most 64 files per call' mirrors maxItems: 64), which keeps it just short of a 5.

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 tool with no output schema and no annotations, the description covers the call decision thoroughly: when to call, what it does, edge cases, constraints, and the follow-on workflow. The only gap is that the return value is described only as 'Returns immediately,' leaving the agent to guess how errors or failures would be reported.

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%, with both agentName (including 64-char truncation) and filePaths (absolute paths, files about to edit) already fully documented. The description adds only marginal nuance — files to be created are saved empty and their folder must already exist — but mostly restates schema content. 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?

States a specific action ('saves a copy of each file') against a specific resource (markdown files) with a clear purpose: so the reviewer's diff shows exactly what changed. The opening clause 'Call this BEFORE you edit markdown files' positions it as a pre-edit snapshot step, and the workflow reference to mdr_request_review distinguishes it from review-stage siblings. The name, timing, and action align without ambiguity.

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

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

Gives explicit when-to-use ('BEFORE you edit markdown files the user will later review in mdr') and explicit when-not-to-use ('Do not call it after you have already edited a file'), plus a concrete workflow sequence. It does not explicitly name alternatives for other scenarios, but the when/when-not guidance plus the workflow reference to mdr_request_review makes the call decision practically unambiguous.

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 no annotations provided, the description carries the full burden and succeeds. It discloses non-blocking execution ('Returns IMMEDIATELY'), the required two-tool flow with mdr_wait, mdr_wait's rejection of user-origin sessions, banner and invisible-feedback consequences, the anchoring to rendered text with fallback behavior, and the author attribution requirement. This is rich behavioral context well beyond the basic 'post a comment' 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?

The description is long but front-loaded: purpose, trigger, and the key mdr_request_review distinction come first, then critical async/session behavior. Each paragraph carries necessary operational information that an agent must know to call this tool correctly, so the length is justified even though some sentences restate the same core contrast.

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

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

Given the tool's complex two-session flow and the absence of an output schema, the description covers the major operational concerns: immediate return, mdr_wait sequencing, user-origin session restrictions, anchor/rendering behavior, and reply handling via sessionId. Minor gaps exist around enableResolve and the exact return value shape, but they are not likely to cause incorrect invocation.

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

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

Schema coverage is only 40%, so the description's parameter guidance is valuable. It explains the central filePaths vs sessionId choice, states that filePaths opens a new session while sessionId posts into an existing one, and instructs the agent to include author on each comment/reply. However, it leaves enableResolve and the contextBefore/contextAfter fields unexplained, so it does not fully compensate for the schema gaps.

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: 'Post YOUR OWN comments into markdown files for the user to read.' It also explicitly differentiates the tool from mdr_request_review by explaining when 'review' refers to the user's action rather than the agent's, giving clear sibling distinction.

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 criteria are explicit: use when the user asks YOU to review a doc and leave feedback; do not use when the user wants to review themselves. It names the alternative tool (mdr_request_review), gives concrete example phrasings to detect the wrong case, and further distinguishes between the filePaths and sessionId flows with the mdr_wait dependency.

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 discloses critical behavioral traits beyond annotations: the tool blocks the agent from reading/editing files under review while waiting, because the user is actively writing @comment markers. It explains the consequence of ignoring this (surfacing unsubmitted markers) and clarifies that after a 'batch' or 'done' result, the agent may only address comments listed in that result. This is rich, actionable behavioral context.

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 long but every sentence earns its place given the tool's complexity. It front-loads the core purpose and usage, then covers the critical waiting behavior and post-batch constraints. The structure is logical: purpose → when to use → new vs continue → critical warning → post-result rules. Slightly verbose but justified by the need to prevent misuse.

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

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

Given the tool's complexity (3 params, no output schema, no annotations), the description is remarkably complete. It covers when to use, how to start/continue, the critical waiting constraint, what happens after results arrive, and the relationship with mdr_baseline. The only minor gap is the exact meaning of enableResolve, but the schema covers that and the description mentions the resolve workflow.

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 all three parameters. The description adds meaningful context beyond the schema: it explains the relationship between filePaths and sessionId (mutually exclusive usage), and clarifies that sessionId is used to continue after addressing a batch. It also explains the purpose of enableResolve implicitly through the resolve workflow mention, though it doesn't detail the workflow.

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

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

The description clearly states the tool's purpose: open markdown files in mdr for the user to review and comment on, or continue an existing review session. It uses specific verbs ('open', 'review', 'comment') and explicitly distinguishes the user as the reviewer while the agent waits and addresses comments. It also differentiates from siblings by naming mdr_baseline and explaining when to use it.

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

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

The description provides explicit when-to-use guidance, including example phrasings like 'I want to review X in mdr' and 'open X so I can comment'. It clearly states when to pass filePaths (new review) vs sessionId (continue/re-poll), and when to call mdr_baseline before editing. It also gives a critical exclusion: do not use other tools on files under review while waiting.

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 no annotations provided, the description carries the full disclosure burden and does so thoroughly: it states that the call blocks, that the timeout is 90 seconds, that a timeout returns {status:'pending'}, that it may be retried, and that a done status should be followed by reading files for user edits. No contradictions with schema or annotations.

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

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

Three sentences each carry essential information: purpose, timeout/retry behavior, and post-done follow-up. The most important verb is front-loaded and there is no filler or repetition of schema fields.

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 tool with no output schema, the description covers the blocking behavior, both possible return statuses, the retry loop, and the subsequent action of reading files. Nothing an agent needs to invoke and handle this tool correctly is missing.

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

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

Schema description coverage is 100% and already explains sessionId as 'Session ID returned by mdr_comment.' The tool description reinforces using the same sessionId on retry, a small behavioral addition, but not enough to raise the score above the baseline for fully documented parameters.

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

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

The description opens with a specific verb-resource pair: 'Block until the user has finished engaging with an mdr_comment session.' It clearly distinguishes itself from mdr_comment and sibling tools by positioning mdr_wait as the follow-up wait step after feedback batches are posted.

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: 'Call this once after you have posted all your feedback batches via mdr_comment.' It also specifies the retry pattern on timeout ('call mdr_wait again with the same sessionId') and what to do after done, leaving no ambiguity about when to invoke it.

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