Skip to content
IsoKron

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.

Source: Anthropic: Writing effective tools for agents

How to fix it

Rename to say what it is, for example issue_id or user_email.

  1. Rename generic names (id, user, data, value, payload, input).
  2. Put the object and format in the name: issue_id, user_email, due_date.
  3. Keep the same name for the same thing across tools.

TypeScript SDK

TypeScript
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

Python
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.

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