mdr_ask

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.