[Bug]: MCP tool `md` has no description due to missing docstring

[mratsim]

crawl4ai version

0.7.7

Expected Behavior

A description for the md tool intended at LLMs.

Current Behavior

The md tool has no description

_list_tools function is pulling descriptions via inspect.getdoc() which pulls the documentation string

crawl4ai/deploy/docker/mcp_bridge.py

Lines 114 to 124 in 3a07c59

	# MCP handlers
	@mcp.list_tools()
	async def _list_tools() -> List[t.Tool]:
	out = []
	for k, (proxy, orig_fn) in tools.items():
	desc = getattr(orig_fn, "__mcp_description__", None) or inspect.getdoc(orig_fn) or ""
	schema = getattr(orig_fn, "__mcp_schema__", None) or _schema(_body_model(orig_fn))
	out.append(
	t.Tool(name=k, description=desc, inputSchema=schema)
	)
	return out

but there is no docstring for it

crawl4ai/deploy/docker/server.py

Lines 303 to 325 in 3a07c59

	@app.post("/md")
	@limiter.limit(config["rate_limiting"]["default_limit"])
	@mcp_tool("md")
	async def get_markdown(
	request: Request,
	body: MarkdownRequest,
	_td: Dict = Depends(token_dep),
	):
	if not body.url.startswith(("http://", "https://")) and not body.url.startswith(("raw:", "raw://")):
	raise HTTPException(
	400, "Invalid URL format. Must start with http://, https://, or for raw HTML (raw:, raw://)")
	markdown = await handle_markdown_request(
	body.url, body.f, body.q, body.c, config, body.provider,
	body.temperature, body.base_url
	)
	return JSONResponse({
	"url": body.url,
	"filter": body.f,
	"query": body.q,
	"cache": body.c,
	"markdown": markdown,
	"success": True
	})

Is this reproducible?

Yes

Inputs Causing the Bug

Steps to Reproduce

Code snippets

OS

docker.io/unclecode/crawl4ai:0.7.7

Python version

docker.io/unclecode/crawl4ai:0.7.7

Browser

No response

Browser version

No response

Error logs & Screenshots (if applicable)

No response

[Ahmed-Tawfik94]

Root Cause Analysis Summary

The issue is exactly as described in the GitHub issue. Here's what I found:

 

File: server.py:303-325

@app.post("/md")
  @limiter.limit(config["rate_limiting"]["default_limit"])
  @mcp_tool("md")
  async def get_markdown(
      request: Request,
      body: MarkdownRequest,
      _td: Dict = Depends(token_dep),
  ):
      # NO DOCSTRING HERE! ← This is the problem
      if not body.url.startswith(("http://", "https://")) and not body.url.startswith(("raw:", "raw://")):
          ...

File: mcp_bridge.py:116-124

    @mcp.list_tools()
    async def _list_tools() -> List[t.Tool]:
        out = []
        for k, (proxy, orig_fn) in tools.items():
            desc   = getattr(orig_fn, "__mcp_description__", None) or inspect.getdoc(orig_fn) or ""
            schema = getattr(orig_fn, "__mcp_schema__", None) or _schema(_body_model(orig_fn))
            out.append(
                t.Tool(name=k, description=desc, inputSchema=schema)
            )
        return out

Why This Matters

When an LLM or MCP client calls list_tools(), it receives:

    {
      "name": "md",
      "description": "",  // ← Empty! LLMs can't understand what this tool does
      "inputSchema": {...}
    }
    

This degrades the UX significantly because:

1. LLMs rely on descriptions to decide which tool to use
2. Developers browsing the MCP schema see no guidance
3. Auto-generated documentation will be incomplete

Recommended Fix

The fix proposed in the issue is correct. Add a docstring to the get_markdown function:

    @app.post("/md")
    @limiter.limit(config["rate_limiting"]["default_limit"])
    @mcp_tool("md")
    async def get_markdown(
        request: Request,
        body: MarkdownRequest,
        _td: Dict = Depends(token_dep),
    ):
        """
        Convert a web page into Markdown format.
    
        Supports multiple extraction modes:
        - fit (default): Readability-based extraction for clean content
        - raw: Direct DOM to Markdown conversion
        - bm25: BM25 relevance ranking with optional query
        - llm: LLM-based summarization with optional query
    
        Use this tool when you need clean, readable text from web pages.
        """
        ...
    

[cjangrist]

any update? mcp tools as they are are impossible for SOTA models to figure out how to use, they spend 3-5 loops just trying to get the arguments right