Tool Man Pages
Reference
Everything an MCP tool prints is read by a model, not by a person, and it is the only documentation that model has. This page pins down the man page a tool contributes and the wording rules the bundled tools follow.
What man renders
The man tool builds a page per tool. The first sections are generated from the tool's own definition, and the prose the tool returns from getManPage() is appended verbatim after them.
| Section | Comes from |
|---|---|
| NAME | The advertised tool name, then getSummary(), falling back to the first sentence of the definition's description |
| SYNOPSIS | The input schema, required parameters first: each parameter is name=<type>, optional ones wrapped in square brackets |
| OPTIONS | One entry per parameter, its name with a parenthetical naming its type and whether it is required, and its description indented below |
| DESCRIPTION | The description of getToolDefinition(), when it is not blank |
| The rest | getManPage(), appended as written |
The page for man itself begins as follows.
NAME
man - Show documentation for the available MCP tools.
SYNOPSIS
man [tool=<string>]
OPTIONS
tool (string, optional)
Name of the tool or reference page to show. Omit for the categorized catalog.Called with no argument, man prints the catalog instead. The catalog opens with Available tools and reference pages - use `man <name>` for full documentation:, then one blank line before each category. Each entry is two spaces, the tool id, - and the summary, and both the categories and their entries are sorted. The catalog lists the wiki's effective tool set, so it matches what the endpoint registered: per-wiki toggles apply, reach-gated tools appear only with reach, and a guest caller sees no write tool. It also serves the standalone reference pages man xwiki-syntax and man awm, under a Reference category.
What a tool writes
| Member | Holds | Shipped on every call |
|---|---|---|
| getToolDefinition() description | What the tool is for, in a few sentences | Yes |
| Parameter descriptions | What one argument means, with its default and its bounds | Yes |
| getSummary() | A single short sentence, the catalog tagline | Yes |
| getCategory() | The catalog group, e.g. "Search & Navigation" | Yes |
| getManPage() | The long-form prose: NOTES, EXAMPLES, SEE ALSO | No, only when man is called |
The split is a budget decision. The tool definition is sent to the model on every request, so it stays lean; the man page is fetched only when the model asks for it, so it can afford to teach.
Wording rules
- The component hint is the stable tool id. It is what the configuration stores, and it must match what the logs and the catalog print, which is the advertised McpSchema.Tool.name(). It is renamed like any other public identifier: not lightly.
- A tool description never repeats its parameter descriptions. They ship in the same payload, and the duplication is paid on every request.
- A parameter description states its default and its bounds explicitly, in the form "(default 20, max 100)". A model cannot read the code to find out.
- An error message says what was refused, states that nothing was saved where that is in doubt, and names the corrective next action. An error a model cannot act on costs a retry loop.
- The
Error:prefix marks a malformed parameter only. A state outcome, such as a document that does not exist or a right the user lacks, carries no prefix. - EXAMPLES shows real calls with real argument values. It is the section models copy from.
- SEE ALSO names the neighbouring tools and what each is for, so adding or renaming a tool means updating the chains of its neighbours.
Echoing wiki content
Tool output is a line grammar the model trusts. A raw echo of a page title, a filename or a reference is a line-forgery vector: a stored value carrying a newline can add a line the model reads as the server's own, and one carrying a bidirectional override can render its characters reordered. Pass every echo of wiki-authored or agent-supplied text through MCPToolSupport.stripLineBreaks before writing it into a line.
The same guard covers log lines. Since 0.11, every agent-supplied value and every root-cause message placed in a WARN line is stripped, so a crafted reference cannot forge a log entry either. MCPTextGuards wraps this and caps one fragment at 200 characters, but it is package-private: a tool outside the server module composes MCPToolSupport.stripLineBreaks(ExceptionUtils.getRootCauseMessage(e)) itself.
FAQ
Does a tool have to provide a man page?
No. getManPage() defaults to null, and the generated NAME and SYNOPSIS sections are still rendered, plus OPTIONS when the tool has parameters and DESCRIPTION when its description is not blank. A tool with parameters worth explaining should provide one anyway.
Can the man page vary per wiki?
Yes. It is an ordinary method call, so a tool whose behaviour depends on cross-wiki reach returns the variant matching the endpoint, exactly as it does for its advertised schema.
