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 tool id, then getSummary(), falling back to the first sentence of the definition's description |
SYNOPSIS | The input schema: required parameters bare, optional ones 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() |
| The rest | getManPage(), appended as written |
Called with no argument, man prints the catalog instead: every enabled tool grouped by getCategory(), one line each of the tool id and its summary. It also serves the standalone reference pages man xwiki-syntax and man awm.
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 what the logs and the catalog print, so 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. EXAMPLESshows real calls with real argument values. It is the section models copy from.SEE ALSOnames 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.
FAQ
Does a tool have to provide a man page?
No. getManPage() defaults to null, and the generated NAME, SYNOPSIS, OPTIONS and DESCRIPTION sections are still rendered. 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.
