# 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. Last verified against Anthropic: Writing effective tools for agents on 2026-11-18.

## 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](https://www.anthropic.com/engineering/writing-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

```ts
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"
```

## 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](https://isokron.ai/mcp-check/checks/schema-param-description)
- [Tool names that say what the tool does](https://isokron.ai/mcp-check/checks/openai-name-opaque)
- [Constrained arguments list their allowed values](https://isokron.ai/mcp-check/checks/schema-enum-missing)
- [MCP tool descriptions](https://isokron.ai/mcp-check/checks/descriptions)

Counts toward: Schema and description quality.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
