Server Quality Checklist

Tool Scores

• list_commentsA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety and idempotency. The description adds useful context about the optional 'key' parameter based on document location, but doesn't disclose additional behavioral traits like pagination, rate limits, or error conditions. No contradiction with annotations exists.

  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?

  The description is two concise sentences with zero waste. The first sentence front-loads the core purpose, and the second efficiently explains the optional parameter condition. Every sentence earns its place by adding necessary context.

  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 moderate complexity (list operation with 2 parameters), rich annotations (covering read-only, non-destructive, idempotent), and full schema coverage, the description is mostly complete. It clarifies the optional key condition, which is helpful. However, without an output schema, it doesn't describe return values (e.g., comment format), leaving a minor gap.

  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%, so the schema fully documents both parameters. The description adds marginal value by clarifying the condition under which 'key' is optional, but doesn't provide additional syntax, format, or semantic details beyond what the schema already states. Baseline 3 is appropriate given high schema coverage.

  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 clearly states the specific action ('List all comments') and resource ('on a document'), with additional details about what's included ('including replies and resolution status'). It distinguishes from siblings like 'post_comment' (create) and 'resolve_comment' (modify) by focusing on retrieval only.

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

  Usage Guidelines4/5

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

  The description provides clear context about when the 'key' parameter is optional ('if the document is in this MCP server's local store'), which helps guide usage. However, it doesn't explicitly state when to use this tool versus alternatives like 'post_comment' or 'resolve_comment', nor does it mention any exclusions or prerequisites beyond the optional key.

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

• list_linksA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare read-only, non-destructive, and idempotent behavior. The description adds valuable context beyond annotations: it specifies the admin access requirement (a permission constraint) and clarifies conditional parameter behavior based on document location. No contradictions with annotations exist.

  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?

  Two sentences, zero waste. The first sentence states purpose and output details; the second adds critical usage constraints. Every word earns its place, and information is front-loaded appropriately.

  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 moderate complexity (listing with admin requirements), rich annotations (safety profile covered), and 100% schema coverage, the description is nearly complete. It lacks output format details (no output schema exists), but covers purpose, constraints, and parameter conditions adequately for a read-only tool.

  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%, so the schema fully documents both parameters. The description adds minor context about the 'key' parameter's optionality condition, but does not provide additional semantic meaning beyond what the schema already states. Baseline 3 is appropriate when schema does the heavy lifting.

  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 clearly states the specific action ('List all share links') and resource ('for a document'), including the scope of information returned (status, permission, label). It distinguishes from siblings like 'generate_link' (creates) and 'revoke_link' (modifies) by focusing on listing existing links.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use it ('Requires admin access') and clarifies a conditional parameter rule ('key' is optional if document is local). However, it does not explicitly state when NOT to use it or name alternatives like 'get_admin_url' for different admin tasks.

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

• post_commentA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate this is a non-readOnly, non-destructive, non-idempotent operation. The description adds valuable context beyond annotations: it explains the conditional optionality of the 'key' parameter based on document storage location, which is crucial behavioral information not captured in 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?

  The description is perfectly concise with three sentences that each earn their place: first states core functionality, second adds optional features, third provides important conditional parameter guidance. No wasted words, well-structured and front-loaded.

  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 a mutation tool with good annotations and full schema coverage, the description provides adequate context about the tool's behavior and parameter conditions. However, without an output schema, it doesn't describe what the tool returns (e.g., comment ID, success status), leaving a minor gap in completeness.

  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?

  With 100% schema description coverage, the schema already documents all 6 parameters thoroughly. The description adds minimal value beyond the schema by mentioning the conditional optionality of 'key', but doesn't provide additional semantic context for other parameters like 'anchor_text' or 'parent_id'.

  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 clearly states the specific action ('Post a comment') and resource ('on a document'), with additional functionality ('optionally anchored to specific text' and 'reply to an existing comment'). It distinguishes from siblings like 'list_comments' (read-only) and 'resolve_comment' (different action).

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use the tool (posting comments with optional anchoring/replying) and includes a specific conditional about the 'key' parameter. However, it doesn't explicitly state when NOT to use it or name alternatives (e.g., when to use 'resolve_comment' instead).

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

• resolve_commentA
  4.2/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations: it specifies permission requirements ('edit or admin permission') and explains the server's limitation ('can't look up the parent document'), which annotations don't cover. Annotations indicate it's destructive and idempotent, and the description doesn't contradict these. However, it doesn't mention potential side effects like notifications or audit trails.

  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?

  The description is extremely concise (two sentences) and front-loaded with the core purpose. Every sentence adds critical information: the first states the action, and the second explains permission and parameter requirements efficiently, with zero wasted words.

  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 a destructive tool with no output schema, the description is reasonably complete: it covers purpose, permissions, and parameter rationale. However, it doesn't describe the return value or error conditions, which would be helpful given the mutation nature. The annotations help by indicating destructiveness and idempotency.

  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?

  With 100% schema description coverage, the input schema already documents all parameters well. The description adds some context for the 'key' parameter (explaining why it's required), but doesn't provide additional meaning for 'comment_id' or 'resolved' beyond what the schema states. This meets the baseline for high schema coverage.

  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 clearly states the specific action ('Resolve or unresolve a comment') and resource ('comment'), distinguishing it from siblings like 'post_comment' or 'list_comments'. It precisely defines the verb and object without ambiguity.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use it ('Requires edit or admin permission') and explains why the 'key' parameter is needed, but it doesn't explicitly state when not to use it or name alternatives (e.g., vs. 'post_comment' for creating comments). This gives good guidance but lacks sibling differentiation.

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

• upload_markdownA
  4.3/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations: it explains that admin credentials are stored locally and not returned, describes performance implications (file_path is 'dramatically faster' for large files), and specifies the default permission level. Annotations cover basic safety (non-destructive, non-idempotent), but the description enhances this with practical details.

  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 appropriately sized and front-loaded with the core purpose. Each sentence adds value: the first states the action and outcome, the second explains link permissions and admin credential handling, and the third provides performance guidance. No wasted sentences, though it could be slightly more streamlined.

  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 complexity (upload with performance considerations) and lack of output schema, the description does well to explain the response content (share link details) and behavioral nuances. It covers key aspects like credential storage, performance trade-offs, and sibling tool relationships, though it doesn't detail error cases or exact response format.

  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?

  With 100% schema description coverage, the schema already documents all parameters thoroughly. The description reinforces the file_path vs content preference and mentions the default share_permission, but adds minimal new semantic information beyond what's in the schema. This meets the baseline for high schema coverage.

  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 clearly states the specific action ('upload markdown to mdshare') and the outcome ('receive a shareable link'), distinguishing it from siblings like generate_link or list_links by focusing on file/content upload rather than link generation or listing. It explicitly mentions the resource (markdown) and the platform (mdshare).

  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?

  The description provides explicit guidance on when to use this tool vs alternatives: it directs to 'call get_admin_url' if the user asks for admin URLs, and distinguishes from siblings by its upload function. It also includes clear parameter usage rules (PREFER file_path over content for files on disk).

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

• get_versionsA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety and idempotency. The description adds valuable context about the optionality of 'key' based on document location, which isn't captured in annotations. It doesn't describe return format or pagination, but with good annotations, this is sufficient.

  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?

  Two sentences, zero waste. The first sentence states the purpose and scope, the second provides critical usage guidance. Every word earns its place, and the structure is front-loaded with the core functionality.

  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 a read-only, non-destructive tool with full schema coverage and no output schema, the description is nearly complete. It covers purpose, usage, and key behavioral nuance. The only minor gap is lack of detail on return format (e.g., what 'edit history' structure looks like), but annotations provide safety context.

  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%, so the schema fully documents both parameters. The description adds semantic context about 'key' being optional for local documents, but this is already implied in the schema's description. No additional parameter meaning is provided beyond what the schema offers.

  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 clearly states the specific action ('Get the edit history') and resource ('of a document'), with detailed scope ('who edited, when, and via what'). It distinguishes from siblings like 'read_document' (which reads content) or 'list_my_documents' (which lists documents).

  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 provides when-to-use guidance: 'If the document is in this MCP server's local store, 'key' is optional.' This tells the agent when the key parameter can be omitted, which is crucial for correct invocation. No explicit alternatives are mentioned, but the guidance is complete for this tool's context.

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

• patch_documentA
  4.4/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• register_documentA
  4.4/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations: it explains the tool verifies URLs against the live API, stores them in a specific file path (~/.mdshare-mcp/documents.json), and rejects non-admin URLs. Annotations already indicate it's not read-only, not destructive, and idempotent, so the description doesn't need to repeat those safety aspects. No contradiction with annotations exists.

  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?

  The description is efficiently structured with two sentences: the first states the core purpose and process, and the second provides important constraints and bulk usage guidance. Every sentence adds value without redundancy, and key information is front-loaded.

  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 moderate complexity (persistent storage, API verification), the description covers the essential behavior, constraints, and usage context well. However, without an output schema, it doesn't explain what the tool returns (e.g., success/failure status, stored metadata), leaving a minor gap in completeness.

  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?

  The description provides the parameter format ('admin URL of the form https://mdshare.live/d/{id}?key=adm_...') and validation rules ('Only accepts admin URLs — view/comment/edit share links will be rejected'), which adds meaning beyond the schema's basic description. However, with 100% schema description coverage, the baseline is 3, and this extra context justifies maintaining that score rather than elevating it significantly.

  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 clearly states the specific action ('register'), resource ('mdshare admin URL'), and purpose ('so it can be resumed without re-pasting the key every time'). It distinguishes this tool from siblings by specifying it's for registering existing URLs rather than generating new ones (like generate_link) or retrieving them (like get_admin_url).

  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?

  The description provides explicit guidance on when to use this tool ('Register an mdshare admin URL you already have saved') and when not to ('Only accepts admin URLs — view/comment/edit share links will be rejected'). It also names an alternative approach for bulk operations ('use the LLM's built-in file reading and search tools... then call this tool once per URL'), though it doesn't explicitly mention sibling tools as alternatives.

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

• get_admin_urlA
  4.5/5.0
  Behavior4/5

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

  Annotations indicate read-only, non-destructive, and idempotent behavior, which the description does not contradict. The description adds critical context beyond annotations: the admin URL 'grants full control and is equivalent to a password,' and it should 'never be surfaced to the user unless directly requested,' providing important security and usage insights.

  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?

  The description is front-loaded with the purpose, followed by critical usage guidelines in a structured manner. Every sentence adds essential information—security warnings and explicit usage rules—with zero waste, making it highly efficient and well-organized.

  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?

  Given the tool's complexity (security-sensitive operation), the description provides complete context: purpose, security implications ('equivalent to a password'), and strict usage guidelines. With annotations covering safety and no output schema needed for a simple retrieval, the description adequately addresses all necessary aspects for an AI agent.

  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%, so the schema fully documents the 'document_id' parameter. The description adds minimal semantic value beyond the schema, only implying that the document must be previously uploaded, which is already suggested by the schema's reference to 'upload_markdown response.' Baseline 3 is appropriate as the schema handles parameter documentation.

  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 clearly states the specific action ('Retrieve the admin URL') and resource ('for a document previously uploaded via this MCP server'), distinguishing it from siblings like 'generate_link' or 'list_links' by focusing on administrative control rather than sharing or listing.

  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 guidelines are provided: call only when user explicitly asks for the admin URL (e.g., 'give me the admin URL'), and do not call for normal upload, share, or collaboration flows. This clearly distinguishes when to use this tool versus alternatives like 'generate_link' for sharing.

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

• generate_linkA
  4.6/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations: it discloses the admin access requirement (not covered by annotations) and clarifies conditional parameter behavior for 'key'. Annotations indicate it's non-readOnly, non-destructive, and non-idempotent, but the description supplements this with practical usage constraints. No contradiction with annotations exists.

  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?

  The description is highly concise and front-loaded: the first sentence states the core purpose, and the second adds crucial usage details (admin access and key optionality). Every sentence earns its place with no wasted words, making it easy for an agent to parse quickly.

  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 moderate complexity (4 parameters, no output schema), the description is nearly complete: it covers purpose, access requirements, and key parameter nuance. However, it doesn't specify what the generated link looks like or potential error conditions (e.g., invalid document_id), leaving minor gaps. Annotations help by indicating non-destructive behavior.

  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?

  With 100% schema description coverage, the baseline is 3. The description adds meaningful semantics by explaining the conditional optionality of 'key' ('optional if the document is in this MCP server's local store'), which isn't in the schema. However, it doesn't elaborate on other parameters like 'permission' or 'label' beyond what the schema provides, keeping it slightly above baseline.

  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 clearly states the specific action ('generate a share link') and resource ('for a document'), distinguishing it from siblings like 'list_links' (which lists existing links) or 'revoke_link' (which removes links). It specifies the purpose is to create a link with permissions, making the tool's function unambiguous.

  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?

  The description provides explicit usage guidance: it states 'Requires admin access' as a prerequisite and clarifies when the 'key' parameter is optional ('if the document is in this MCP server's local store'). This helps differentiate it from tools like 'get_admin_url' or 'read_document' by specifying access requirements and conditional parameter usage.

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

• revoke_linkA
  4.6/5.0
  Behavior4/5

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

  Annotations already indicate destructive and idempotent operations, but the description adds valuable context: it specifies admin access requirements and clarifies conditional parameter usage ('key' optional for local documents), enhancing behavioral understanding beyond 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?

  The description is front-loaded with the core action and outcome, followed by prerequisites and conditional logic in three concise sentences, with no wasted words—each sentence adds essential information.

  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 a destructive tool with no output schema, the description covers purpose, usage, permissions, and parameter conditions well, but could slightly enhance completeness by mentioning potential error cases or confirming idempotency (though hinted in annotations).

  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?

  With 100% schema description coverage, the baseline is 3, but the description adds semantic context by explaining the relationship between 'document_id' and 'key' (used for admin key lookup) and when 'key' is optional, providing practical usage insights beyond schema definitions.

  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 clearly states the verb ('revoke') and resource ('share link'), specifies the outcome ('making it permanently inactive'), and distinguishes it from siblings like 'list_links' (used to find tokens) and 'generate_link' (its opposite).

  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 explicitly states when to use this tool ('Use list_links first to find the token') and when not to use it ('Requires admin access'), and implies alternatives by referencing sibling tools like 'list_links' for preparation.

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

• update_documentA
  4.6/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond what annotations provide. While annotations indicate destructive (true) and non-idempotent (false) operations, the description clarifies this is a 'full replace' operation, explains permission requirements, specifies parameter precedence rules ('file_path wins'), and mentions version history implications compared to patch_document. No contradiction with annotations exists.

  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?

  The description is efficiently structured with front-loaded key information (purpose and permission requirements), followed by parameter guidance and alternative tool recommendation. Every sentence adds value without redundancy, making it easy for an agent to parse and apply.

  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 a destructive mutation tool with rich annotations but no output schema, the description provides strong contextual completeness. It covers purpose, permissions, parameter usage, alternatives, and behavioral implications. The only minor gap is lack of explicit information about return values or error conditions, but this is mitigated by the comprehensive parameter guidance.

  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?

  With 100% schema description coverage, the baseline is 3, but the description adds meaningful context about parameter usage: it explains when 'key' is optional, provides guidance on choosing between 'file_path' and 'content' based on file location and size, and clarifies the 'author' parameter's purpose for attribution. This goes beyond the schema's technical descriptions.

  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 clearly states the tool's purpose with specific verb ('update'), resource ('existing mdshare document'), and scope ('full replace'). It distinguishes from sibling tools like 'patch_document' by specifying this is a full replacement rather than incremental editing.

  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?

  The description provides explicit guidance on when to use this tool vs alternatives: 'PREFER file_path over content for files already on disk' and 'For small edits to large documents, consider patch_document instead.' It also specifies permission requirements ('Requires edit or admin permission') and contextual conditions for optional parameters.

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

• list_my_documentsA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety and idempotency. The description adds valuable behavioral context beyond annotations: it specifies the scope limitation (only documents created by this MCP server), clarifies what happens on fresh installs or cleared stores (returns empty array), and notes what is excluded from results (admin credentials, web UI/API documents).

  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?

  The description is efficiently structured with three sentences that each serve a distinct purpose: stating the tool's function, specifying return values and exclusions, and clarifying scope and edge cases. There is no redundant information, and it is front-loaded with the core purpose.

  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?

  Given the tool's simplicity (0 parameters, no output schema) and rich annotations, the description provides complete context. It explains the tool's purpose, usage guidelines, behavioral details (scope, exclusions, edge cases), and return value semantics. No additional information is needed for an agent to understand and invoke this tool correctly.

  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?

  With 0 parameters and 100% schema description coverage, the baseline would be 4. The description appropriately explains there are no parameters needed for this operation, which aligns with the empty input schema. No additional parameter semantics are required or provided.

  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 clearly states the specific action ('List documents you've previously uploaded via this MCP server on this machine') and distinguishes it from siblings by specifying it only includes documents created by this MCP server, not via web UI or other clients. It explicitly names the returned fields and excludes admin credentials.

  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?

  The description provides explicit guidance on when to use this tool ('to help the user find and resume older documents without re-pasting admin URLs') and when not to use it ('Does NOT include documents created via the mdshare web UI or via direct API calls from other clients'). It also implicitly suggests alternatives like upload_markdown for new documents.

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

• read_documentA
  4.7/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations: it explains the performance implications of using output_path vs inline reading, specifies the approximate size threshold (~10KB) for optimization, and describes how response format changes when output_path is provided. While annotations cover safety (readOnlyHint=true, destructiveHint=false, idempotentHint=true), the description provides practical implementation details that help the agent make better decisions.

  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?

  The description is efficiently structured with three focused sentences: the core purpose, conditional parameter behavior, and performance optimization guidance. Every sentence adds value without redundancy, and critical information (like the performance recommendation) is appropriately front-loaded.

  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?

  Given the tool's moderate complexity, comprehensive annotations (readOnlyHint, destructiveHint, idempotentHint), and 100% schema coverage, the description provides excellent contextual completeness. It covers purpose, usage guidance, performance considerations, and parameter semantics without needing to explain return values (which are adequately described in the text).

  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?

  With 100% schema description coverage, the baseline is 3. The description adds meaningful context: it explains when 'key' is optional (for locally stored documents), clarifies that different key types are accepted (admin, edit, comment, or view), and provides the performance rationale for using 'output_path' with the ~10KB threshold. This goes beyond the schema's parameter descriptions.

  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 clearly states the specific action ('Read a markdown document from mdshare') and resource ('document'), distinguishing it from siblings like 'upload_markdown' or 'patch_document'. It explicitly mentions the return value ('Returns the content') and context-specific behavior for locally stored documents.

  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?

  The description provides explicit guidance on when to use alternatives: it states 'PREFER output_path over inline reading for large documents' and explains the performance trade-off. It also clarifies when the 'key' parameter is optional based on document storage location, offering clear context for parameter usage.

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