feat(docs[_ext]): Add {toolref} role — code-linked tool refs without badge

why: {ref} renders as plain text (Sphinx hardcodes nodes.inline in
build_reference_node). {tool} renders as code+badge. Needed a middle
ground: code-formatted linked tool names without badges for dense
contexts like tables and inline prose.
what:
- Add {toolref} role: resolves same labels as {tool}, renders as
  <code> inside <a>, no safety badge
- Reuse _tool_ref_placeholder with show_badge=False
- Update prompting.md tables and heuristics to use {toolref}

Author: tony

docs/_ext/fastmcp_autodoc.py

@@ -869,15 +869,22 @@ def _add_section_badges(
 
 
 class _tool_ref_placeholder(nodes.General, nodes.Inline, nodes.Element):
-    """Placeholder node for ``{tool}`` role, resolved at doctree-resolved."""
+    """Placeholder node for ``{tool}`` and ``{toolref}`` roles.
+
+    Resolved at ``doctree-resolved`` by ``_resolve_tool_refs``.
+    The ``show_badge`` attribute controls whether the safety badge is appended.
+    """
 
 
 def _resolve_tool_refs(
     app: Sphinx,
     doctree: nodes.document,
     fromdocname: str,
 ) -> None:
-    """Resolve ``{tool}`` placeholders into links with safety badges.
+    """Resolve ``{tool}`` and ``{toolref}`` placeholders into links.
+
+    ``{tool}`` renders as ``code`` + safety badge.
+    ``{toolref}`` renders as ``code`` only (no badge).
 
     Runs at ``doctree-resolved`` — after all labels are registered and
     standard ``{ref}`` resolution is done.
@@ -888,6 +895,7 @@ def _resolve_tool_refs(
 
     for node in list(doctree.findall(_tool_ref_placeholder)):
         target = node.get("reftarget", "")
+        show_badge = node.get("show_badge", True)
         label_info = domain.labels.get(target)
         if label_info is None:
             node.replace_self(nodes.literal("", target.replace("-", "_")))
@@ -908,10 +916,11 @@ def _resolve_tool_refs(
 
         newnode += nodes.literal("", tool_name)
 
-        tool_info = tool_data.get(tool_name)
-        if tool_info:
-            newnode += nodes.Text(" ")
-            newnode += _safety_badge(tool_info.safety)
+        if show_badge:
+            tool_info = tool_data.get(tool_name)
+            if tool_info:
+                newnode += nodes.Text(" ")
+                newnode += _safety_badge(tool_info.safety)
 
         node.replace_self(newnode)
 
@@ -930,7 +939,26 @@ def _tool_role(
     Creates a placeholder node resolved later by ``_resolve_tool_refs``.
     """
     target = text.strip().replace("_", "-")
-    node = _tool_ref_placeholder(rawtext, reftarget=target)
+    node = _tool_ref_placeholder(rawtext, reftarget=target, show_badge=True)
+    return [node], []
+
+
+def _toolref_role(
+    name: str,
+    rawtext: str,
+    text: str,
+    lineno: int,
+    inliner: object,
+    options: dict[str, object] | None = None,
+    content: list[str] | None = None,
+) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+    """Inline role ``:toolref:`capture-pane``` → code-linked tool name, no badge.
+
+    Like ``{tool}`` but without the safety badge. Use in dense contexts
+    (tables, inline prose) where badges would be too heavy.
+    """
+    target = text.strip().replace("_", "-")
+    node = _tool_ref_placeholder(rawtext, reftarget=target, show_badge=False)
     return [node], []
 
 
@@ -958,6 +986,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.connect("doctree-resolved", _add_section_badges)
     app.connect("doctree-resolved", _resolve_tool_refs)
     app.add_role("tool", _tool_role)
+    app.add_role("toolref", _toolref_role)
     app.add_role("badge", _badge_role)
     app.add_directive("fastmcp-tool", FastMCPToolDirective)
     app.add_directive("fastmcp-tool-input", FastMCPToolInputDirective)

docs/topics/prompting.md

@@ -34,12 +34,12 @@ These natural-language prompts reliably trigger the right tool sequences:
 
 | Prompt | Agent interprets as |
 |--------|-------------------|
-| "Run `pytest` in my build pane and show results" | {tool}`send-keys` → {tool}`wait-for-text` → {tool}`capture-pane` |
-| "Start the dev server and wait until it's ready" | {tool}`send-keys` → {tool}`wait-for-text` (for "listening on") |
-| "Check if any pane has errors" | {tool}`search-panes` with pattern "error" |
-| "Set up a workspace with editor, server, and tests" | {tool}`create-session` → {tool}`split-window` (x2) → {tool}`set-pane-title` (x3) |
-| "What's running in my tmux sessions?" | {tool}`list-sessions` → {tool}`list-panes` → {tool}`capture-pane` |
-| "Kill the old workspace session" | {tool}`kill-session` (after confirming target) |
+| "Run `pytest` in my build pane and show results" | {toolref}`send-keys` → {toolref}`wait-for-text` → {toolref}`capture-pane` |
+| "Start the dev server and wait until it's ready" | {toolref}`send-keys` → {toolref}`wait-for-text` (for "listening on") |
+| "Check if any pane has errors" | {toolref}`search-panes` with pattern "error" |
+| "Set up a workspace with editor, server, and tests" | {toolref}`create-session` → {toolref}`split-window` (x2) → {toolref}`set-pane-title` (x3) |
+| "What's running in my tmux sessions?" | {toolref}`list-sessions` → {toolref}`list-panes` → {toolref}`capture-pane` |
+| "Kill the old workspace session" | {toolref}`kill-session` (after confirming target) |
 
 ## Anti-patterns to avoid
 
@@ -85,8 +85,8 @@ that depend on it.
 
 When an agent is unsure which tool to use, these rules help:
 
-1. **Discovery first**: Call {tool}`list-sessions` or {tool}`list-panes` before acting on specific targets
+1. **Discovery first**: Call {toolref}`list-sessions` or {toolref}`list-panes` before acting on specific targets
 2. **Prefer IDs**: Once you have a `pane_id`, use it for all subsequent calls — it never changes during the pane's lifetime
-3. **Wait, don't poll**: Use {tool}`wait-for-text` instead of repeatedly calling {tool}`capture-pane` in a loop
-4. **Content vs. metadata**: If looking for text *in* a terminal, use {tool}`search-panes`. If looking for pane *properties* (name, PID, path), use {tool}`list-panes` or {tool}`get-pane-info`
+3. **Wait, don't poll**: Use {toolref}`wait-for-text` instead of repeatedly calling {toolref}`capture-pane` in a loop
+4. **Content vs. metadata**: If looking for text *in* a terminal, use {toolref}`search-panes`. If looking for pane *properties* (name, PID, path), use {toolref}`list-panes` or {toolref}`get-pane-info`
 5. **Destructive tools are opt-in**: Never kill sessions, windows, or panes unless the user explicitly asks