mdr_baseline

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.