mdr_comment

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.