Accept all cookies
Cookie settings
×

We use cookies to improve your experience on our site. By using our site, you are agreeing to the collection and use of data as described in our Privacy Policy.

Cookie Settings×

Table of contents

toc link
Add secure integrations to your products and AI agents with ease via Merge.
Get a demo
Just for you
8 best practices for building secure and reliable AI agents
Model Context Protocol (MCP) tools: what you need to know

MCP tool schema: what it is, how it works, and examples

Jon Gitlin
Senior Content Marketing Manager
at Merge

Before your AI agents can invoke tools successfully, they need to understand the parameters, or arguments, that need to pass into the tools.

Otherwise, the tool will return an error.

For example, if you’re trying to call Asana’s <code class="blog_inline-code">get_user</code> tool and you don’t include a required argument like a user name, you can receive the following response:

Error during execution of 'asana_connector.tools.user_tools.get_current_user': Failed to get current user
1 validation error for User name
  Field required [type=missing, input_value={'gid': '1211364474763721', 'resource_type': 'workspace'}, input_type=dict]

To help you avoid this type of error, we’ll break down everything you need to know about MCP tool schema, from how you can construct calls with arguments to real-world examples.

What is MCP tool schema?

It’s a JSON object that outlines the required and optional arguments for a tool. This helps AI agents identify the appropriate ways to invoke tools.

Each tool schema includes the following fields:

  • The tool's name. For example, <code class="blog_inline-code">get_user</code>
  • A description in plain text that explains what the tool does
  • InputSchema, which defines the structure and type of data the tool accepts, such as an object or a string
  • Whether a given data type is required or not

Putting this all together, here’s how it can be structured:

{
"name": "tool_name_here",
"description": "Describe what this tool does and list key parameters.",
"input_schema": {
"type": "object",
"properties": {
"param1": { "type": "string", "description": "Required parameter." },
"param2": { "type": "integer", "description": "Optional parameter." }
},
"required": ["param1"]
}
}

Related: What is an MCP connector?

How to use MCP tool schema 

Once you understand a tool’s MCP schema, your agent can structure your tool call via JSON.

For example, if you know a user ID is required and you want to retrieve a user’s full name and email address, your agent can use the following JSON as part of its request:

{
  "tool": "get_user",
  "arguments": {
    "user_id": "1203984756123456",
    "fields": ["name", "email"]
  }
}

Note: MCP tool descriptions and names are the other core elements of an MCP tool. They can help your AI agents determine the best tool to invoke, so they’re used before the agent leverages a tool’s schema. 

Examples of MCP tool schemas

Here are just a few MCP tool schemas from Merge Agent Handler’s MCP servers.

GitHub’s tool schema for fetching issues

The project management platform for developers can use the tool schema below for its <code class="blog_inline-code">get_issue</code> tool.

{
  "name": "get_issue",
  "description": "Get a single issue by number from a specific repository. Returns detailed issue information including comments, labels, and assignees",
  "inputSchema": {
    "type": "object",
    "required": [
      "input"
    ],
    "properties": {
      "input": {
        "type": "object",
        "title": "GetIssueInput",
        "required": [
          "owner",
          "repo",
          "issue_number"
        ],
        "properties": {
          "repo": {
            "type": "string",
            "description": "Repository name"
          },
          "owner": {
            "type": "string",
            "description": "Repository owner"
          },
          "issue_number": {
            "type": "integer",
            "description": "Issue number"
          }
        },
        "additionalProperties": false
      }
    },
    "additionalProperties": false
  }
}

This schema confirms that the arguments need to use an input that’s an object. 

You’ll need to nest the owner, repo, and issue number within the input. In addition, the owner and repo be provided via string format, while the issue number needs to be an integer.

Slack’s tool schema for creating a channel 

The business communications platform can use the tool schema below for its <code class="blog_inline-code">create_channel</code> tool to help agents create a specific channel.

{
  "name": "create_channel",
  "description": "Create a new channel",
  "inputSchema": {
    "type": "object",
    "required": [
      "input"
    ],
    "properties": {
      "input": {
        "type": "object",
        "title": "ChannelInput",
        "required": [
          "name",
          "is_private",
          "team_id"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Channel name"
          },
          "team_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Team ID"
          },
          "is_private": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "Whether to create a private channel"
          }
        },
        "additionalProperties": false
      }
    },
    "additionalProperties": false
  }
}

Like the previous example, this tool’s arguments need to be wrapped inside an input object. Within that object, you’ll need to confirm the team the channel should belong to (as a string), the channel name you want to use (as a string), and whether the channel should be private or public (as a boolean). 

Greenhouse’s tool schema for moving applications to another stage

Greenhouse can help agents move candidates to different stages in the ATS platform by providing the following schema for its <code class="blog_inline-code">move_applications</code> tool.

{
  "name": "move_application",
  "description": "Move an application from one stage to another",
  "inputSchema": {
    "type": "object",
    "required": [
      "application_id",
      "input"
    ],
    "properties": {
      "input": {
        "type": "string",
        "default": "Field(..., description='Stage movement parameters (MUST include on_behalf_of)')"
      },
      "application_id": {
        "type": "integer",
        "default": "Field(..., description='Unique identifier for the application')"
      }
    },
    "additionalProperties": false
  }
}

The only required arguments are the application ID and an input argument that includes the parameter, “<code class="blog_inline-code">on_behalf_of</code>” (to clarify who’s asking the agent to move the application to a different stage). In addition, the former argument should be an integer while the latter should be a string.

{{this-blog-only-cta}}

Jon Gitlin
Senior Content Marketing Manager
@Merge

Jon Gitlin is the Managing Editor of Merge's blog. He has several years of experience in the integration and automation space; before Merge, he worked at Workato, an integration platform as a service (iPaaS) solution, where he also managed the company's blog. In his free time he loves to watch soccer matches, go on long runs in parks, and explore local restaurants.

Read more

MCP tool descriptions: overview, examples, and best practices

AI

How AI agents can use APIs successfully

AI

How Merge empowers its engineers to leverage AI effectively

Company

Subscribe to the Merge Blog

Get stories from Merge straight to your inbox

Subscribe

Access 1000s of enterprise-grade tools via Merge Agent Handler

Merge Agent Handler's tools use rich, actionable schemas, clear names, and optimized descriptions. Sign up for free to test any tool implementation.

Sign up for free

Get our best content every week

Our weekly newsletter provides the best practices you need to build high performing product integrations.

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
But Merge isn’t just a Unified 
API product. Merge is an integration platform to also manage customer integrations.  gradient text
But Merge isn’t just a Unified 
API product. Merge is an integration platform to also manage customer integrations.  gradient text
But Merge isn’t just a Unified 
API product. Merge is an integration platform to also manage customer integrations.  gradient text
But Merge isn’t just a Unified 
API product. Merge is an integration platform to also manage customer integrations.  gradient text