Server Quality Checklist

Tool Scores

• mdr_commentA
  4.7/5.0
  Behavior5/5

  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.

  Conciseness4/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• mdr_waitA
  4.7/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• mdr_askA
  4.8/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• mdr_request_reviewA
  4.8/5.0
  Behavior5/5

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

  With zero annotations, the description carries the full behavioral burden and excels: it discloses the blocking/polling behavior (call again with the same sessionId), the permission restriction on other tools, the rationale (unsubmitted @comment markers), and the post-condition (only address listed comments, ignore other markers). This is precisely the operational context annotations would normally provide.

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

  Conciseness4/5

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

  Well-sequenced: purpose, trigger phrasings, session mechanics, critical restriction, then post-condition. Every sentence is informative, but it is a dense wall of text and the 'ignore unsubmitted markers' point is reinforced multiple times; minor tightening would not hurt.

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

  Completeness5/5

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

  Despite having no output schema, the description defines the result vocabulary ('batch', 'done', 'not finished') and instructs on each outcome. For an interactive polling tool with a subtle safety restriction, everything required to call it correctly — init, continuation, waiting behavior, and post-batch handling — is present.

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

  Parameters4/5

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

  Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the relationship between filePaths and sessionId ('pass the sessionId from the previous result (without filePaths)') and the polling semantics — information that no per-property schema description conveys.

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

  Purpose5/5

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

  States a specific verb + resource ('Open markdown files in mdr (md-redline)') and the intent: the USER reviews and leaves comments while the agent waits. It distinguishes itself from siblings by framing 'The user is the reviewer here; you wait and then address what they write,' making clear this is not the tool for the agent to comment or ask on its own.

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

  Usage Guidelines5/5

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

  Explicitly gives the selection condition ('Use this whenever the user wants to read, review, or comment on a doc themselves') reinforced with concrete trigger phrasings. It also provides scenario mechanics (filePaths for new sessions, sessionId for continuation and re-polling) and an exclusion in the IMPORTANT block: other tools must not act 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.