Proposal: Make `output=md` the default for the MCP search tool

Open
#65 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
65/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
api

Research direction

Start at the MCP search tool and trace how the default params.output value is selected and how the md and json response paths are handled. Confirm that omitted output produces Markdown, explicit md remains Markdown, and explicit json retains the current JSON response.

Written by the indexing model from the issue text.

Description

Summary

Change the default response format of the MCP search tool from JSON to Markdown.

When callers omit params.output, the server would use output=md. Callers could retain the current behavior by explicitly passing output=json.

Motivation

The search tool currently returns JSON by default. Our internal tests show that Markdown responses use approximately 50% fewer tokens on average.

Most MCP tool responses are consumed by AI clients and agents rather than parsed directly by application code. Markdown is easier for models to read and avoids spending context tokens on deeply nested JSON syntax.

Existing agents should continue to work in normal use because they receive tool responses as model context and can read Markdown directly.

This change could break clients that assume the default response is JSON and parse it as such. I expect this to be uncommon because MCP tool results are primarily passed to agents. Applications that need a stable, machine-readable response should pass output=json explicitly or use the SerpApi API or an official language SDK.

Proposed behavior

  • search without params.output returns Markdown.
  • search with params.output="md" returns Markdown.
  • search with params.output="json" retains the current JSON response.
Dominant language
Python
Stars
171
Forks
41
Avg merge
6h 37m
Merged PRs (30d)
3

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from serpapi/serpapi-mcp

All issues in serpapi/serpapi-mcp

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.