mdmagic-mcp-server

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds value by specifying the exact response contents (credit breakdown, plan name, status) and indicating that proactive calls are encouraged. It does not contradict annotations, and while it doesn't mention rate limits or auth, the simple read-only nature plus annotation coverage justify a score above 3.

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 concise and well-structured: a single sentence states the core functionality, followed by a bulleted list of when to call it. Every sentence provides actionable guidance, with no filler or redundancy.

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 no-parameter, read-only tool with no output schema, the description fully covers what the agent needs to know: what data is returned and when to use it. It includes proactive use cases and warns about borderline balances, making it complete for its simplicity.

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?

The tool has zero parameters, so schema coverage is effectively 100%. The description doesn't need to explain parameters, and the baseline for 0-parameter tools is 4. It uses that space to clarify the returned information instead, which is appropriate.

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 function: checking the user's MDMagic credit balance, including subscription credits, purchased credits, plan name, and status. It distinguishes itself from sibling tools (e.g., convert_document, estimate_conversion_cost) by focusing on balance retrieval, making the purpose unambiguous.

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 proactive usage scenarios: when the user asks about credits, after a conversion, or before processing a large document. It also notes an alternative (convert_document returns the balance directly), giving the agent clear guidance on when to invoke this tool versus relying on other tools.

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

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

The description discloses critical behavioral traits beyond annotations: how each output format manifests ('docx' single file, 'all' ZIP), filename derivation/pitfalls, error recovery steps, and the structured response fields (downloadUrl, creditsUsed, etc.). It also warns about newline sensitivity which is non-obvious. No contradiction with annotations.

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 every numbered point earns its place. It is clearly organized with numbered guidance sections, front-loaded purpose, and critical warnings highlighted. There is no filler or redundancy; each sentence delivers either essential usage guidance or critical behavioral context.

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 an 8-parameter tool with no output schema, the description covers all facets: output formats, user interaction, filename handling, error recovery, response fields, page sizes/orientation, and the critical newline constraint. It is fully complete for an agent to invoke correctly in diverse scenarios.

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 100%, so the baseline is 3. The description substantially enriches parameter understanding: it explains the content newline requirement in depth, clarifies fileName usage with user-attached files, warns not to guess templateName, and explains outputFormat 'all' returns a ZIP. This goes well beyond schema descriptions.

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+resource statement: 'Convert markdown to a professionally formatted document using an MDMagic template.' It clearly differentiates from siblings by focusing on the conversion action and the MDMagic template context, while also detailing concrete output format behavior.

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?

Provides explicit usage instructions: asks user when ambiguous, directs to list_all_templates on template-not-found errors, contraindicates fallback to code execution, and advises preserving newlines. The guidance is actionable and contextually grounded in real failure modes.

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

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

Annotations already declare read-only and idempotent. The description adds value by disclosing the output structure (word count, page calculation, credit breakdown) and the pre-flight intent, going beyond annotation basics. No contradiction.

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?

Two sentences, front-loaded with purpose and output, then clear usage guidance. No filler or repetition.

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?

The description covers return values and when to use the tool, sufficient for an estimation tool. It doesn't address potential nuances like pageSize/orientation impact on cost, but overall it provides a complete picture.

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 100%, so all parameters are already described. The tool description mentions 'format and template type' but does not add meaningful parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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?

Clearly states the tool estimates credit cost for a conversion before running it, with specific output details (word count, page calculation, credit breakdown). This distinguishes it from siblings like convert_document (which executes) and check_credit_balance (which checks balance).

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?

Provides explicit when-to-use guidance: when the user asks 'how much will this cost?' or when a conversion might exceed balance. Names convert_document as the alternative and explains why estimating first is friendlier.

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

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

The description adds behavioral context beyond the annotations by stating that all MDMagic templates support the full 5×2 matrix, which is a useful invariant for the agent to know. It also frames the tool as a confirmation step before conversion. The annotations already declare the tool read-only, idempotent, and non-destructive, so the added context about the uniform variant matrix is valuable but not exhaustive.

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 three sentences, front-loaded with the core purpose. The second and third sentences add specific usage context and a mention of the variant matrix without redundancy. Every sentence contributes meaning, making it concise and well-structured.

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 tool with one parameter, no output schema, and rich annotations, the description is complete. It explains the tool's purpose, when to use it, and the underlying variant matrix. It does not describe the exact return format, but for a simple lookup tool this is not a critical gap given the annotations and the 'Show' verb imply a listing.

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?

The input schema covers 100% of the single parameter, including an example (Executive_Platinum or a UUID). The description does not add parameter-specific details, but the schema is sufficiently descriptive. Per the scoring guideline, high schema coverage yields a baseline of 3, which is appropriate here.

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: 'Show available variants (page sizes and orientations) for a specific template.' It clearly distinguishes itself from siblings by focusing on template variant details rather than listing templates, converting documents, or checking balances. The mention of confirming variants before convert_document runs further clarifies its unique role.

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?

It provides explicit usage triggers: 'Use this when the user asks "does this template come in Legal Landscape?" or "what sizes are available?"' and positions it as a pre-conversion confirmation step. This gives clear when-to-use guidance and implicitly differentiates from convert_document and list_all_templates, which are siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond this by detailing the return fields (name, description, type, category), category counts (Business 5, Creative 6, Professional 2, Technical 2), and the fact that custom templates are always included regardless of filtering. This adds useful behavioral context without contradicting annotations.

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 well-structured: main purpose first, followed by a bulleted list of proactive call scenarios, then a return summary and category counts. Every sentence adds value, and the formatting is scannable for an AI agent. No redundant or filler content.

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 read-only list tool with simple parameters and no output schema, the description is sufficiently complete: it states what it returns, lists the categories, and provides usage context. It does not explain the relationship to sibling tools like list_builtin_templates or get_template_details, but that is not essential for correct invocation of this tool. A small gap is the lack of mention of pagination or ordering, but that is likely unnecessary for a static set of ~15+ templates.

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 100%, and the schema already explains the category enum and its meanings, plus the 'custom templates always included' behavior. The description adds minimal extra parameter insight, only suggesting how to use the filter ('for legal documents → category: Professional'), which is helpful but not necessary. Baseline 3 is appropriate because the schema carries the semantic weight.

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+resource+scope: 'List all 15 built-in MDMagic templates plus any custom templates the user has uploaded.' It clearly distinguishes this from the sibling tools list_builtin_templates and list_custom_templates by combining both. The purpose is unambiguous and actionable.

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?

Provides an explicit proactive call list with four concrete scenarios, such as 'verify it exists before convert_document' and 'a previous convert_document call returned template not found'. This is strong usage guidance. However, it does not mention when to use the sibling tools list_builtin_templates or list_custom_templates instead, so it lacks explicit exclusions/alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false, so the safety profile is covered. The description adds concrete behavioral facts: exactly 15 templates, grouped by category, and exclusion of custom uploads. This exceeds the annotation baseline without contradicting it.

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 three concise sentences plus a compact category list. It front-loads the core purpose and differentiation, and every sentence earns its place—no filler or redundancy.

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 simple read-only list tool, the combination of description, schema, and annotations fully covers what the tool does, when to use it, its parameters, and its safety profile. No output schema exists, but for a template listing the return shape is evident.

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 baseline is 3. The description adds value by listing the categories with counts (Business 5, Creative 6, Professional 2, Technical 2), which enriches the enum parameter with expected result sizes. It does not discuss includeDetails, but the schema already covers it well.

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 uses a specific verb ('List') and a specific resource ('15 built-in MDMagic templates'), then distinguishes itself from sibling list_all_templates by excluding custom uploads. This gives a clear, unambiguous purpose.

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?

It explicitly names an alternative ('Same as list_all_templates') and explains the difference ('but excludes the user's custom uploads'), then gives a direct usage directive: 'Use this when the user asks specifically about MDMagic's bundled templates rather than their personal ones.'

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

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

Annotations already cover read-only and idempotent behavior, so the bar is lower. The description adds valuable cross-tool context that custom templates are referenced by UUID, not name, when calling convert_document. This is a behavioral trait beyond the annotations that helps the agent understand the returned data's usage. No contradictions found.

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?

Two tightly written sentences deliver the core purpose, usage guidance, and a key cross-tool fact. Each sentence earns its place with no redundant information.

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 simple list tool with one optional boolean parameter and no output schema, the description provides sufficient context: scope, usage trigger, and how the results relate to convert_document. The UUID reference adds completeness beyond a minimal description.

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?

The only parameter, includeDetails, is fully described in the schema with 100% coverage. The description itself does not add extra parameter-level semantics, so the 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?

The description clearly states the action ('List') and the specific resource ('only the user's custom-uploaded Word templates'), which distinguishes it from siblings like list_builtin_templates and list_all_templates. The scope ('only') and usage examples make the tool's purpose unambiguous.

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 explicitly tells when to use this tool ('Use this when the user asks about their own templates') with concrete examples. It does not name alternative tools directly, but the sibling names and the word 'only' imply the exclusion of built-in or all templates, making the guidance clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: it returns ranked recommendations with rationale, maps purpose to real template names to avoid 'template not found' errors, and is limited to built-in templates. This goes beyond the safety profile encoded 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.

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

The description is concise and well-structured. It opens with a clear imperative sentence, then gives a usage condition, a return description, and a brief 'Why this exists' rationale. Every sentence earns its place, and the content is front-loaded so the core purpose is immediately clear.

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 simple read-only tool with two parameters, no output schema, and strong annotations, the description is fully adequate. It covers the input condition ('describes WHAT the document is'), the scope ('built-in templates'), and the return type ('ranked recommendations with rationale'). The rationale behind the tool's existence further helps an agent decide when to invoke it.

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?

The input schema covers both parameters (purpose and topN) with descriptions and examples, so schema coverage is 100%. The description reinforces the purpose parameter's meaning with additional examples and the 'without naming a template' qualifier, but it adds no extra syntax, formatting, or behavioral details beyond what the schema already provides. Baseline 3 is appropriate.

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 function: 'Suggest the best built-in template(s) for a described purpose.' It specifies the resource (built-in templates) and the action (recommend based on purpose). It also distinguishes itself from sibling tools like list_all_templates and convert_document by addressing the problem of guessing nonexistent template names.

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 an explicit trigger condition: 'Use this when the user describes WHAT the document is... without naming a template.' It explains why this tool exists and indirectly references alternatives via convert_document, but it doesn't explicitly enumerate when-not-to-use cases or name sibling alternatives for those scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context about preferences being set on the account page and the purpose of honoring defaults, but does not detail edge cases like missing defaults or return format.

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 two sentences, front-loads the core purpose, and includes a practical usage note with no wasted words.

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 simple zero-parameter read-only tool with rich annotations, the description fully covers what the tool does and when to use it. No output schema means return details are implied by the tool's purpose, which is adequate here.

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?

The tool has zero parameters and schema coverage is 100%, so there is no parameter documentation burden. The description adds clarity about what the tool returns (preferences) without needing param details.

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?

Description clearly states the tool shows the user's default paper size and orientation preferences, using a specific verb and resource. This distinguishes it from sibling tools like convert_document and template listing tools.

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?

Explicitly explains when to use this tool: when the user hasn't specified pageSize/orientation, and provides the alternative of blindly using A4/Portrait. This gives clear context for selection.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat those. It adds valuable behavioral context: validation is cheap compared to conversion, it returns a green/amber/red status, and it detects specific markdown features. This goes beyond the annotations without contradicting them.

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 front-loaded with the core purpose and follows with well-structured, scannable sections for usage guidelines and return values. Every sentence provides distinct value—no filler, no repetition of schema fields, and the bulleted triggers are tightly written.

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 has no output schema, the description compensates by detailing the return payload (status, detected features, human-readable message). It also covers when to use the tool, what it catches, and why it matters financially, making it fully self-contained for an agent to decide and invoke correctly.

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?

The input schema already has 100% description coverage for both parameters (content and filename), so the baseline is 3. The description does not add any parameter-specific semantics beyond what the schema provides; it focuses on output and usage context instead.

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 'Pre-flight markdown validation BEFORE conversion', clearly identifying the tool's specific verb, resource, and timing. It lists exact failure modes it detects (malformed tables, unclosed code fences, broken task lists, unsupported syntax) and distinguishes it from conversion tools like convert_document.

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?

It explicitly states when to call the tool proactively, with three concrete scenarios ('user is about to convert a long document', 'user reports broken output', 'you generated the markdown yourself'). It also contrasts validation cost with conversion cost, but it does not explicitly mention when NOT to use it or name an alternative tool.

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