# 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](content-intelligence.md) | ## Why MCP tools are exposed to an agent under a fully-qualified runtime identifier — `mcp____` — where the `` 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____` flattening is a client convention rather than part of the MCP specification. ## Examples **Bad:** ```markdown Search for the ticket with `mcp__plugin_jira_atlassian__searchJiraIssuesUsingJql` before opening a new one. ``` **Good:** ```markdown 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: ````markdown ```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____` 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: ```yaml rules: content-mcp-tool-name: enabled: true allow: - mcp__internal__getDeployStatus ``` ## How to fix In ordinary prose, drop the `mcp____` 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____`, 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 ```yaml 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.*