Wiki source code of Tool Man Pages
Last modified by superadmin on 2026/09/04 19:22
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | 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 {{code}}man{{/code}} page a tool contributes and the wording rules the bundled tools follow. | ||
| 2 | |||
| 3 | == What man renders == | ||
| 4 | |||
| 5 | The {{code}}man{{/code}} tool builds a page per tool. The first sections are generated from the tool's own definition, and the prose the tool returns from {{code}}getManPage(){{/code}} is appended verbatim after them. | ||
| 6 | |||
| 7 | |=Section |=Comes from | ||
| 8 | |{{code}}NAME{{/code}} |The tool id, then {{code}}getSummary(){{/code}}, falling back to the first sentence of the definition's description | ||
| 9 | |{{code}}SYNOPSIS{{/code}} |The input schema: required parameters bare, optional ones in square brackets | ||
| 10 | |{{code}}OPTIONS{{/code}} |One entry per parameter, its name with a parenthetical naming its type and whether it is required, and its description indented below | ||
| 11 | |{{code}}DESCRIPTION{{/code}} |The description of {{code}}getToolDefinition(){{/code}} | ||
| 12 | |The rest |{{code}}getManPage(){{/code}}, appended as written | ||
| 13 | |||
| 14 | Called with no argument, {{code}}man{{/code}} prints the catalog instead: every enabled tool grouped by {{code}}getCategory(){{/code}}, one line each of the tool id and its summary. It also serves the standalone reference pages {{code}}man xwiki-syntax{{/code}} and {{code}}man awm{{/code}}. | ||
| 15 | |||
| 16 | == What a tool writes == | ||
| 17 | |||
| 18 | |=Member |=Holds |=Shipped on every call | ||
| 19 | |{{code}}getToolDefinition(){{/code}} description |What the tool is for, in a few sentences |Yes | ||
| 20 | |Parameter descriptions |What one argument means, with its default and its bounds |Yes | ||
| 21 | |{{code}}getSummary(){{/code}} |A single short sentence, the catalog tagline |Yes | ||
| 22 | |{{code}}getCategory(){{/code}} |The catalog group, e.g. {{code}}"Search & Navigation"{{/code}} |Yes | ||
| 23 | |{{code}}getManPage(){{/code}} |The long-form prose: {{code}}NOTES{{/code}}, {{code}}EXAMPLES{{/code}}, {{code}}SEE ALSO{{/code}} |No, only when man is called | ||
| 24 | |||
| 25 | 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. | ||
| 26 | |||
| 27 | == Wording rules == | ||
| 28 | |||
| 29 | * 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. | ||
| 30 | * A tool description never repeats its parameter descriptions. They ship in the same payload, and the duplication is paid on every request. | ||
| 31 | * A parameter description states its default and its bounds explicitly, in the form {{code}}"(default 20, max 100)"{{/code}}. A model cannot read the code to find out. | ||
| 32 | * 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. | ||
| 33 | * The {{code}}Error: {{/code}} 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. | ||
| 34 | * {{code}}EXAMPLES{{/code}} shows real calls with real argument values. It is the section models copy from. | ||
| 35 | * {{code}}SEE ALSO{{/code}} names the neighbouring tools and what each is for, so adding or renaming a tool means updating the chains of its neighbours. | ||
| 36 | |||
| 37 | == Echoing wiki content == | ||
| 38 | |||
| 39 | 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 {{code}}MCPToolSupport.stripLineBreaks{{/code}} before writing it into a line. |
