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

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.

Explore Merge Agent Handler's GitHub MCP server and available tools.

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}}