Argument names are specific
Name arguments unambiguously: issue_id instead of id, user_email instead of user, so the model knows which object and format each one takes.
Check schema-vague-param · Schema and description quality · default severity: advice · rubric 2.1.0
What fails
Names such as id, user, data, value or payload leave the model to guess which object or format is meant, especially across tools.
The rule
In particular, input parameters should be unambiguously named: instead of a parameter named user, try a parameter named user_id.
How to fix it
Rename to say what it is, for example issue_id or user_email.
- Rename generic names (id, user, data, value, payload, input).
- Put the object and format in the name: issue_id, user_email, due_date.
- Keep the same name for the same thing across tools.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'add_comment',
{
title: 'Add comment',
description: 'Add a comment to one issue. Use when the user asks to reply on or note something on an issue.',
inputSchema: z.strictObject({
issue_id: z.string().describe('Issue ID, for example ISS-42'),
comment_body: z.string().describe('Comment text in Markdown'),
}),
annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
},
async ({ issue_id, comment_body }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);Python SDK
from typing import Annotated
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
server = MCPServer("issues")
@server.tool(
title="Add comment",
annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False, openWorldHint=False),
)
def add_comment(
issue_id: Annotated[str, Field(description="Issue ID, for example ISS-42")],
comment_body: Annotated[str, Field(description="Comment text in Markdown")],
) -> str:
"""Add a comment to one issue. Use when the user asks to reply on or note something on an issue."""
return "Done"Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.
Questions
Is a description not enough?
It helps, but the name is what the model writes in the call. A specific name prevents mixing up IDs across tools that all take "id".
Should names match the backend API?
Only if the API’s names are clear. The tool interface is for the model; map names in the handler if needed.
Related checks
- Every argument has a description
- Tool names that say what the tool does
- Constrained arguments list their allowed values
- All checks in MCP tool descriptions
How this check is graded
It counts toward: Schema and description quality. See the rubric.
Last verified against Anthropic: Writing effective tools for agents on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.
Check your tool list: paste your tools/list, nothing is sent anywhere