MCP/Tools Are Not REST API: Here’s a Better Design

Large language models (LLM) without access to current data are almost useless. They need enough data and context to do the right thing, and that’s where tool calling becomes leverage. The rise of MCP has unlocked more possibilities for AI agents to access current information and therefore provide useful results.

Tools are functions or APIs that models or agents can call to perform tasks.

A good practice for tool design is to provide a clear description of what each tool does and when to use it. You’ll find this info in some good resources about tools and function calling, but I’d like to address something else: Tools are not REST APIs.

What do I mean?

A lot of companies now offer MCP for their products and services. Most of the time, it’s just a direct abstraction of their REST or GraphQL API. I don’t mind cases with just a few tools to call; it becomes annoying when an MCP exposes 20 or more tools. Too many tool options make it hard for an agent to decide on the right tool to call. For example:

• 📂 MCP Server: github-mcp-server-official
  • 📜 get_notification_details Get detailed information for a specific GitHub notification…
  • 📜 get_pull_request Get details of a specific pull request in a GitHub repository.
  • 📜 get_pull_request_comments Get comments for a specific pull request.
  • 📜 get_pull_request_diff Get the diff of a pull request.
  • 📜 get_pull_request_files Get the files changed in a specific pull request.
  • 📜 get_pull_request_reviews Get reviews for a specific pull request.
  • 📜 get_pull_request_status Get the status of a specific pull request.
  • 📜 get_secret_scanning_alert Get details of a specific secret scanning alert in a GitHub r…
  • 📜 get_tag Get details about a specific git tag in a GitHub repository
  • 📜 get_workflow_run Get details of a specific workflow run
  • 📜 get_workflow_run_logs Download logs for a specific workflow run (EXPENSIVE: downl…
  • 📜 get_workflow_run_usage Get usage metrics for a workflow run
  • 📜 list_branches List branches in a GitHub repository
  • 📜 list_code_scanning_alerts List code scanning alerts in a GitHub repository.

I recently added the official GitHub MCP server to VS Code; when I opened the Configure Tools dialog, the list was overwhelming. The list you saw is just a fraction of the tools available through that MCP. They’ve improved the UI since then, but there are still a few questions:

• Why can’t some of the get_pull_request_* tools be combined into one? (Same for other similar tools in that MCP.)
• Why aren’t comments and status included in the get_pull_request tool instead of being separate tools?

I think models will find it hard to select the right tools without explicit instructions to use a particular tool. If it’s hard for me or the model to pick the right tool because of information overload, the tools become useless.

I believe a lot of thought went into GitHub’s MCP design, and it may be unfair to single them out. Let’s use a generic example that shows how to avoid designing your tools like a REST API.

Tools for Stock Data

Assuming you want to build an MCP to provide core stock data to an agent, here’s an easy way you’d design the tools:

• get_intraday_stock_data: For retrieving intraday stock data.
• get_daily_stock_data: For retrieving daily stock data.
• get_adjusted_daily_stock_data: For retrieving daily adjusted stock data.
• get_weekly_stock_data: For retrieving weekly stock data.
• get_adjusted_weekly_stock_data: For retrieving weekly adjusted stock data.
• get_monthly_stock_data: For retrieving monthly stock data.
• get_adjusted_monthly_stock_data: For retrieving monthly adjusted stock data.
• get_stock_quote: For retrieving a single stock quote from the Quote Endpoint.

This design follows the typical REST endpoints you’d find with stock data providers.

That’s too many tools for this use case. You can do better: what if you condensed it down to one or two tools?

There you go — from eight tools to two. This works because the parameters for retrieving stock data are similar, and you likely only need a switch statement to choose which internal function or REST endpoint to call.

Wrap Up

REST and GraphQL have specific constraints when it comes to designing APIs. REST, for example, emphasizes hypermedia and scalable web architectures. The constraints for function/tool calling in LLMs are different, which necessitate a different design approach.

You should think about how to simplify the number of tools and their arguments the next time you’re designing or building tools. Having similarly named tools with almost identical arguments or descriptions can make it tricky for models to decide what to call. More importantly, providing too many tools can increase the risk of your model selecting an incorrect or suboptimal tool.

P.S. If you want to read more of my AI-related posts, subscribe to my newsletter which is at the bottom of this page.