Chapter 15: Complete MCP Tools Reference

Chapter Status: ✅ Rebuilt from tools/list on pmat 3.32.0

Last updated: 2026-08-25 PMAT version: pmat 3.32.0 MCP protocol: 2024-11-05

⚠️ Historical warning, as of pmat 3.32.0 (2026-08-25). The previous edition of this chapter documented 36 MCP tools. Thirty-one of them do not exist.

That edition described pmat 2.213.1, was marked ✅ 100% Working (8/8 examples), and claimed “All tools tested and verified”. Asking the running server what it serves — tools/list, the one authoritative question — returns 19 tools, of which only five (analyze_complexity, analyze_dead_code, analyze_satd, generate_context, scaffold_project) appeared in that list. Calling any of the other thirty-one gets you:

{"code":-32602,"message":"Resource not found: Tool 'analyze_duplicates' not found"}

Two more claims in that edition were the opposite of the truth:

• The transport matrix was false. It advertised HTTP, WebSocket and SSE modes with ✅ Claude Desktop: Supported on every row. --transport web-socket and --transport http-sse exit 2 with “not yet implemented”, and there is no Claude Desktop support for either because neither binds a socket.
• There is no “background daemon” mode. pmat agent is not in the build you get from cargo install pmat.

The real transports — stdio and streamable HTTP — are documented in Chapter 3.4: MCP Transports, which is current and verified. This chapter no longer duplicates it; it is the tool reference, and the tool list below is read out of the server rather than written down.

The Problem

An MCP tool reference has one job: tell you what you can call and what to pass it. It is also the single easiest kind of documentation to get wrong, because a tool list is invisible — nothing fails to compile when a tool is renamed, and a chapter that invents analyze_maintainability_index reads exactly like one that does not.

The fix is not to write the list more carefully. It is to ask the server. Every tool name, argument name, type and requirement in this chapter came out of a live tools/list response from pmat 3.32.0, and you can reproduce the whole list in one command.

Asking the server yourself

The tool list is one JSON-RPC call. Over stdio:

{ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"book","version":"1"}}}';
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'; } \
  | pmat --mode mcp

The initialize response, executed:

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"paiml-mcp-agent-toolkit","version":"3.32.0"}}}

To see just the names:

{ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"b","version":"1"}}}';
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'; } \
  | pmat --mode mcp | tail -1 | jq -r '.result.tools[].name'

If that list differs from the table below, believe the server: your pmat is a different version, and this chapter is stale.

For how to connect — stdio versus streamable HTTP, registration with Claude Code, tokens, headers — see Chapter 3.4, or run:

pmat mcp connect

The 19 tools

Three things to notice, because they are the common trip-ups:

• paths is an array, and it is required on most tools. A bare string is a validation error, and so is omitting it — see Error shapes below.
• Three tools take project_path (a single string) instead — analyze_hardcoded_paths, analyze_reachability and analyze_vacuous_tests. They want a project root, not a file list.
• The pmat_* four are the index/search surface: pmat_query_code, pmat_get_function, pmat_find_similar and pmat_index_stats. They are the MCP equivalent of pmat query, and they are the tools an agent should reach for first when exploring an unfamiliar codebase.

Argument reference

analyze_big_o

Classify the Big-O time complexity of functions in the given paths.

analyze_complexity

Analyze cyclomatic and cognitive complexity for source files.

analyze_dag

Generate a project dependency graph (call graph, import graph, inheritance, or full dependency DAG).

analyze_dead_code

Find unreachable or unused code (functions, types, or modules).

analyze_deep_context

Run the full deep-context analysis pipeline (AST, complexity, churn, dead code) over the given paths.

analyze_hardcoded_paths

Find machine-specific absolute paths baked into source (a user’s home, a nix store hash, a build root) — correct where they were written, inert everywhere else.

analyze_reachability

Report tracked .rs files that no compilation unit reaches — orphaned modules that compile to nothing and whose tests never run.

analyze_satd

Detect self-admitted technical debt (TODO, FIXME, HACK markers) in source code.

analyze_vacuous_tests

Find #[test] functions that cannot fail — no assertion, an assertion over constants, or a body that silently returns when a fixture is missing.

generate_context

Generate project context (file tree + optional dependency graph) for LLM/agent consumption.

git_operation

Query git working-tree status for the given repository path.

pdmt_deterministic_todos

Generate deterministic, quality-enforced todo lists from a list of requirements.

pmat_find_similar

Find functions similar to a reference function. Useful for finding related code, potential duplicates, or implementations of similar patterns.

pmat_get_function

Get detailed information about a specific function by its ID. Returns full function metadata including source code, quality metrics, and SATD markers.

pmat_index_stats

Get statistics about the code index including function counts, quality distribution, and index health.

pmat_query_code

Search code functions by natural language query with TDG quality filtering. Returns semantically ranked results with complexity, fault patterns, and call graph context.

quality_gate

Run the pmat quality-gate --checks all suite (complexity, dead code, SATD, entropy, security, duplicates, coverage, documentation sections, provability) plus a TDG score against the given paths. Any check a path could not answer is named in not_measured and, with its reason, in checks.not_run.

quality_proxy

Proxy a file operation (write/edit/append) through the quality gate, optionally auto-fixing violations.

scaffold_project

Produce a high-level project summary scaffold for the given paths.

Verified calls

Every response below was produced by piping the request into pmat --mode mcp against a two-file Rust fixture. Responses are truncated where noted; nothing is edited.

analyze_complexity

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"analyze_complexity","arguments":{"paths":["/path/to/fixture"]}}}

Response — note that the payload arrives as a JSON string inside content[0].text, not as a JSON object; a client has to parse it twice:

{"content":[{"type":"text","text":"{\"status\":\"completed\",\"message\":\"Complexity analysis completed\",\"results\":{\"total_files\":1,\"files_analyzed\":1,\"total_complexity\":7,\"average_complexity\":7,\"violations\":[],\"top_files\":[{\"file\":\"…/src/main.rs\",\"function\":\"classify\",\"cyclomatic_complexity\":5,\"cognitive_complexity\":5,\"line_start\":2,\"line_end\":12}]}}"}],"isError":false}

analyze_satd

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"analyze_satd","arguments":{"paths":["/path/to/fixture"]}}}

Decoded content[0].text:

{"status":"completed","message":"SATD analysis completed","results":{"total_satd":1,"files":[{"file":"…/src/main.rs","satd_count":1,"debts":[{"line":1,"category":"Requirement","severity":"Low","text":"TODO: this is a self-admitted technical debt marker"}]}],"files_discovered":1,"files_analyzed":1,"census_balances":true,"files_unaccounted":0}}

census_balances and files_unaccounted are worth wiring into any agent that uses this tool: they say whether every file the walker discovered was actually read. A count of debts is only meaningful next to a count of files that were looked at.

quality_gate

{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"quality_gate","arguments":{"paths":["/path/to/fixture"]}}}

Decoded content[0].text, truncated:

{"status":"completed","message":"Quality gate check completed (standard mode)","passed":false,"score":90.0,"grade":"A","not_measured":["coverage","sections"],"checks":{"ran":["complexity","dead-code","satd","entropy","security","duplicates","provability"],"not_run":[{"check":"coverage","path":"…","reason":"no coverage report at .pmat/coverage-cache.json or .pmat-metrics/coverage.json, so this gate does not cover coverage"},{"check":"sections","path":"…","reason":"no README.md, so there is nothing for the documentation-sections check to read"}]}}

This is the most useful response shape on the server, and the one to model an agent around: not_measured names every check that could not run, and checks.not_run gives the reason for each. A gate that “passed” while silently skipping coverage is the failure mode this structure exists to prevent — read not_measured before you believe passed.

Error shapes

Two errors account for nearly everything, and both come back as JSON-RPC errors (no result), not as isError results.

Unknown tool — including all thirty-one tools the previous edition documented:

{"jsonrpc":"2.0","id":4,"error":{"code":-32602,"message":"Resource not found: Tool 'analyze_duplicates' not found"}}

Missing required argument:

{"jsonrpc":"2.0","id":6,"error":{"code":-32602,"message":"Validation error: Invalid arguments: missing field `paths`"}}

Wrong type — paths given as a string rather than an array:

{"jsonrpc":"2.0","id":2,"error":{"code":-32602,"message":"Validation error: Invalid arguments: invalid type: string \"/tmp\", expected a sequence"}}

All three are -32602 (invalid params), so a client cannot distinguish “no such tool” from “bad arguments” by code alone — it has to read the message.

Tools earlier editions documented that do not exist

All thirty-one return -32602 ... not found. Where the right column names a CLI command, that command is real and was verified to resolve; where it says nothing, the capability does not exist in pmat 3.32.0 in any form.

Transports: what is real

The previous edition’s capability matrix advertised four server modes. Measured against 3.32.0:

Both real transports are built by the same build_server, so the tool surface cannot drift between them. The details — ports, tokens, the Accept header the streamable transport requires, and the exact claude mcp add line — are in Chapter 3.4 and, for the HTTP endpoint’s measured behaviour, Chapter 18.

Registering with a client

One command prints every registration form, for the port it actually bound:

pmat mcp connect

For Claude Code with the stdio transport, that is:

claude mcp add --scope user pmat -- pmat --mode mcp

There is no pmat mcp-server subcommand and no "args": [] registration — a bare pmat with no subcommand prints help and exits 2 rather than starting a server. See Chapter 64 for the history of that change.

Summary

pmat exposes 19 MCP tools over two real transports, and the authoritative list is tools/list — not this chapter, and not any chapter. The tools divide into analysis (analyze_*), context generation, the quality gate and its write-time proxy, the four-tool code index (pmat_*), and a small scaffolding/git surface.

The previous edition of this chapter is the best argument in the book for asking the server: it documented 36 tools, in confident detail, with request and response schemas for each — and 31 of them had never existed. Every response shape shown above was produced by running the call.