content-mcp-tool-name

Detect fully-qualified MCP tool names in portable prose that should use the short tool name

Severity	warning (disabled)
Autofix	auto
Since	v0.20.0
Category	Content Intelligence

Why

MCP tools are exposed to an agent under a fully-qualified runtime identifier — mcp__<server>__<tool> — where the <server> half comes from how the server is installed and named. Portable prose can therefore break when another reader uses a different server name.

Fully-qualified names are also valid and necessary in many places: project instructions tied to a known server, permissions, tool lists, plugin namespaces, and documentation that explains runtime syntax. This rule is opt-in so those common uses stay quiet. Enable it only for portable prose whose audience may register the server under different names.

Brevity is a secondary benefit. Fully-qualified names are long, low-signal strings that spend an agent's context window, usually without telling it anything the short name does not.

The mcp__<server>__<tool> flattening is a client convention rather than part of the MCP specification.

Examples

Bad:

Search for the ticket with `mcp__plugin_jira_atlassian__searchJiraIssuesUsingJql`
before opening a new one.

Good:

Search for the ticket with `searchJiraIssuesUsingJql` before opening a new
one.

When not to flag

Leave the rule disabled when exact runtime names are intentional, such as a known project server, a plugin namespace, a tool catalog, or a comparison of client naming conventions.

Fenced and indented code blocks are never scanned. Configuration examples genuinely require the fully-qualified name — a permissions array in settings.json, an .mcp.json snippet, an allowed-tools list — so keep those inside a fenced block:

```json
{ "permissions": { "allow": ["mcp__plugin_jira_atlassian__searchJiraIssuesUsingJql"] } }
```

Frontmatter is out of scope for the same reason: a command's allowed-tools: and an agent's tools: list both take the fully-qualified identifier, and only body content is scanned.

Names embedded in URLs and file paths are skipped when the guard can see the embedding: a name preceded by a path separator or a dot, a name inside a URL (scheme, query, or fragment), and a name followed by a filename extension are not flagged, and neither are names in link text or names split across a multi-line code span. Only the mcp__<server>__ prefix is ever stripped, so a tool whose own name contains __ keeps every segment of its name.

ToolSearch selectors such as select:mcp__server__tool, wildcard grants such as mcp__server__memory_*, and path continuations are also left unchanged. They are executable selector or path syntax rather than portable prose names.

For anything else that must keep its prefix, list the full identifier under the allow option:

rules:
  content-mcp-tool-name:
    enabled: true
    allow:
      - mcp__internal__getDeployStatus

How to fix

In ordinary prose, drop the mcp__<server>__ prefix and keep the short tool name. skillsaw fix --suggest applies that rewrite — it shortens the name in place, leaving the surrounding line and the file's line count unchanged. The fix is SUGGEST-tier rather than SAFE because the right replacement is a judgment call, which is yours to make in review:

• When the short name is generic (create, search, screenshot), name the server in prose instead — "the XcodeBuildMCP screenshot MCP tool" — so the reader keeps the referent the prefix carried.
• When the prose must communicate a runtime identifier — instructions for an allowed-tools or permissions entry — the short name is not valid there: write the placeholder form mcp__<your-server>__<tool>, or move the concrete example into a fenced block.

A violation in a body decoded out of a non-markdown host — a JSON hook prompt, a folded (>) YAML scalar — is reported without an automatic fix; apply the same rewrites by hand.

A short name that itself looks fully qualified, such as mcp__gateway__mcp__jira__getIssue, is also diagnostic-only: repeated automatic shortening could remove part of the actual tool name. Rewrite the prose manually or put the full identifier in allow when the spelling is intentional.

Configuration

rules:
  content-mcp-tool-name:
    enabled: false  # true | false | auto
    severity: warning

Parameter	Description	Default
allow	Fully-qualified MCP tool names to leave unflagged	[]

Run skillsaw explain content-mcp-tool-name to see this documentation and the rule's effective configuration in your terminal.