mdshare

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

The description adds valuable behavioral context beyond annotations. Annotations indicate destructiveHint=true and idempotentHint=false, but the description elaborates on operational details: 'Each find string must be unique unless replace_all is set' (a constraint), 'If the document is in this MCP server's local store, 'key' is optional' (an authentication nuance), and efficiency claims. It doesn't contradict annotations (which correctly mark it as destructive and non-idempotent for a patch operation), and enriches understanding with practical rules.

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 appropriately sized and front-loaded, with every sentence earning its place. It starts with the core purpose, then adds efficiency comparison, operational rules, key optionality, and file preference—all in a logical flow without redundancy. Each clause provides distinct value, making it concise yet comprehensive.

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 (5 parameters, destructive, non-idempotent) and lack of output schema, the description is largely complete. It covers purpose, guidelines, behavioral nuances, and parameter preferences. However, it doesn't detail the return value or error cases (e.g., what happens if find strings aren't unique), which would be helpful since there's no output schema. Still, it provides strong context for safe and effective use.

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 all parameters thoroughly. The description adds some semantic context: it clarifies when 'key' is optional based on document location, and explains the preference for 'file_path' over 'operations' for disk-stored batches. However, it doesn't provide significant additional meaning beyond what's in the schema descriptions (e.g., schema already says 'PREFERRED' for file_path). Baseline 3 is appropriate as the schema does the heavy lifting.

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: 'Apply find/replace operations to a document without rewriting the full content.' It specifies the exact operation (find/replace), distinguishes it from sibling 'update_document' by noting it's 'more efficient... for small edits to large documents,' and mentions the resource (document). This is specific, includes a verb+resource, and differentiates from alternatives.

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 guidance on when to use this tool versus alternatives. It states: 'More efficient than update_document for small edits to large documents,' directly comparing to a sibling tool. It also gives context-specific rules: 'PREFER file_path over operations for batches of operations stored in a JSON file on disk' and 'If both file_path and operations are provided, file_path wins,' offering clear usage preferences and exclusions.

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