Skip to content

markitdown-mcp: Enhance tool to improve AI agent discoverability for file conversion tasks #1424

@otteydw

Description

@otteydw

Problem

My AI agent is not selecting the convert_to_markdown tool when requesting file conversion to markdown format. Instead, it attempts to write Python code to perform the conversion manually, even when the markitdown MCP tool is available.

This is a simple prompt like "Please convert ~/path/to/filename.xslx to markdown."

It does successfully use the tool if I prod it with "Use the convert_to_markdown tool to convert ~/path/to/filename.xslx to markdown." but that amount of prodding shouldn't be necessary.

Current State

The current docstring is minimal and doesn't clearly indicate the tool's purpose for AI decision-making:

"""Convert a resource described by an http:, https:, file: or data: URI to markdown"""

Suggested Enhanced Docstring

This altered docstring was given to me by an AI. I tested using this version and the tool was chosen automatically for the same prompt, along with other prompts that just asked the AI to give me certain data from the same excel file.

"""Convert files and documents to markdown format from various sources.

This tool handles file conversion and document conversion to markdown from multiple formats
including PDFs, Word documents, PowerPoint presentations, Excel files, images, and more.
Use this tool when users request converting, transforming, or processing files to markdown.

Supports http:, https:, file:, and data: URIs for both local and remote file conversion.
This is the recommended approach for any markdown conversion tasks rather than writing custom code.
"""

This is just an example - other docstrings would surely work. The important note is that additional context within the docstring will assist the AI in knowing what the tool is truly capable of.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions