mcp_template_doc

Use this template to create one wiki page per DynamicsCrm.DevKit MCP tool.

File naming rule:

mcp_<exact_tool_name>.md

Examples:

mcp_whoami.md
mcp_manage_ribbon.md

The <exact_tool_name> value must come from the MCP tool metadata, not from the C# class name.

Required Source Of Truth

The source of truth for tool documentation is the real MCP server metadata returned by tools/list from the running server.

Do not manually rewrite, summarize, or reconstruct the tool description from source code when generating docs. Source code can be used to locate the implementation file, category, behavior notes, and examples, but the final "MCP Tool Description (Exact)" section must copy tool.description exactly from tools/list.

Preferred extraction order:

1. Run the current DevKit MCP server with all tools loaded.
2. Call MCP tools/list against that running server.
3. Call MCP resources/list and resources/templates/list against that running server.
4. Save the full tools/list, resources/list, and resources/templates/list responses as local JSON artifacts for verification.
5. Generate each documentation file from those JSON files.
6. Use source files only to verify category, implementation path, output shape, warnings, examples, resource relationships, and edge cases.

If the AI environment already exposes the DevKit MCP tools directly, the active tool definitions can be used as the real MCP metadata only when they are known to be loaded from the same current build. Otherwise, run the server and call tools/list.

If tools/list cannot be obtained, stop and ask before generating the 33 tool docs.

If a tool references MCP resources, the resource metadata must come from resources/list or resources/templates/list from the same running server. Do not invent resource names from source code alone.

Expected Tool Count

For the current v5 MCP server, --category advanced or default all should expose 33 tools.

Before writing tool docs, verify:

devkit mcp --tools

Then verify the exported tools/list JSON contains exactly 33 tool objects:

$json = Get-Content -Raw .\tools-list.json | ConvertFrom-Json
$json.tools.Count

Do not create the final set unless the count is exactly 33, unless the user explicitly confirms that the tool count changed.

Description Extraction Rules

For each tool:

1. Use tool.name as the exact tool name.
2. Use tool.title as the exact MCP title when present.
3. Use tool.description as the exact tool description.
4. Preserve punctuation, capitalization, line breaks, bullet spacing, and Unicode characters from tool.description.
5. Do not fix grammar, normalize dashes/arrows, wrap text manually, or translate the description.
6. If tool.description is missing or empty in tools/list, write exactly:

(No description returned by tools/list.)

7. Parameter descriptions must come from tool.inputSchema.properties.<parameter>.description exactly.
8. Required parameters must come from tool.inputSchema.required.
9. Default values must come from the schema when present. If the schema does not include a default, write -.

Resource Extraction Rules

Some tools rely on MCP resources such as docs://... instruction documents or schema://... schemas.

For each generated tool page:

1. Call resources/list and resources/templates/list on the same running MCP server used for tools/list.
2. Preserve each resource's exact name, title, uri or uriTemplate, mimeType, and description from the MCP metadata.
3. Identify related resources by matching resource URIs or names mentioned in:
   • tool.description
   • parameter descriptions
   • implementation source comments or constants
   • user-facing guidance in resource descriptions
4. A resource is related only when the tool should read it before or while using that tool. Do not list every resource on every tool page.
5. If the relation is inferred from source code rather than directly mentioned in tool.description, write Inferred from source in the reason column.
6. Do not paste full resource contents into every tool page unless the user explicitly asks. Link/list the resource metadata and summarize when to read it.
7. If the tool has no related resources, write exactly:

This tool does not require any MCP resources.

Current resource source files for cross-checking:

DynamicsCrm.DevKit.Cli/Mcp/Resources/InstructionResources.cs
DynamicsCrm.DevKit.Cli/Mcp/Resources/SchemaResources.cs

Known current resource URI patterns:

docs://...
schema://...

Token Count Estimate Rules

Each tool page must include an estimated token count for that tool.

Count this payload:

The single minified JSON object for this tool as returned by tools/list.

Include at least these fields if they exist:

{
  "name": "...",
  "title": "...",
  "description": "...",
  "inputSchema": {}
}

Do not count the whole wiki page. Do not count the entire tools/list response. Count only the one tool metadata object.

Do not include resource bodies in the tool token count. If resource token counts are needed later, document them separately as resource token counts, not as the tool token count.

Preferred tokenizer:

o200k_base

Example Python counting script:

import json
from pathlib import Path

import tiktoken

tools = json.loads(Path("tools-list.json").read_text(encoding="utf-8"))["tools"]
tool = next(t for t in tools if t["name"] == "whoami")
payload = json.dumps(tool, ensure_ascii=False, separators=(",", ":"))
encoding = tiktoken.get_encoding("o200k_base")
print(len(encoding.encode(payload)))

If tiktoken is not available, use an approximation and label it as approximate:

$json = Get-Content -Raw .\tools-list.json | ConvertFrom-Json
$tool = $json.tools | Where-Object name -eq 'whoami'
$payload = $tool | ConvertTo-Json -Depth 100 -Compress
[math]::Ceiling($payload.Length / 4)

Document the method in the page:

Estimated token count: ~123 tokens (tools/list tool JSON, o200k_base, measured 2026-06-18)

or:

Estimated token count: ~123 tokens (tools/list tool JSON, char_count/4 fallback, measured 2026-06-18)

Source Cross-Check Rules

Use these files to cross-check implementation details:

DynamicsCrm.DevKit.Cli/Mcp/McpServerHost.cs
DynamicsCrm.DevKit.Cli/Mcp/Tools/<ToolClass>.cs
DynamicsCrm.DevKit.Cli/Mcp/Tools/Models/*.cs
DynamicsCrm.DevKit.Cli/Mcp/Tools/Helper/*.cs
DynamicsCrm.DevKit.Cli/Mcp/Resources/*.cs

McpServerHost.ToolCategoryMap determines category:

basic
standard
advanced

The tool implementation class has [McpServerToolType]. The public tool method has [McpServerTool(Name = "...")].

Use source code to verify:

• Category.
• Implementation file.
• Safety warnings.
• Mutating vs read-only behavior.
• Output model name and notable structured fields.
• Related MCP resources.
• Practical examples.

Do not use source code as the final description source unless the user explicitly approves a fallback.

Per-Tool Page Skeleton

Copy this skeleton into each generated mcp_<tool_name>.md file and replace every placeholder.

## Summary

| Field | Value |
|---|---|
| Tool name | `<tool.name>` |
| MCP title | `<tool.title or "-">` |
| Category | `<basic/standard/advanced>` |
| Implementation | `<relative/source/path.cs>` |
| Estimated token count | `~<N> tokens (<method>, measured <YYYY-MM-DD>)` |
| Last verified | `<YYYY-MM-DD>` |

## MCP Tool Description (Exact)

```text
<copy tool.description exactly from tools/list>
```

## Parameters

| Name | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `<param>` | `<schema type>` | `<Yes/No>` | `<default or "-">` | `<exact parameter description from tools/list>` |

If the tool has no parameters, write:

```text
This tool has no input parameters.
```

## Input Schema

```json
<formatted tool.inputSchema copied from tools/list without changing values>
```

## Related MCP Resources

| Resource | URI / URI template | MIME type | Reason |
|---|---|---|---|
| `<resource.name>` | `<resource.uri or resource.uriTemplate>` | `<resource.mimeType>` | `<why this tool should read it>` |

If the tool has no related resources, write:

```text
This tool does not require any MCP resources.
```

## When To Use

- <Practical use case from the exact description and implementation behavior.>
- <Add only useful, user-facing guidance.>

## Notes

- <Safety behavior, destructive behavior, auth requirements, limits, paging, fuzzy matching, or publish behavior.>
- <Use source code for this section when needed.>

## Example

```json
{
  "<parameter>": "<value>"
}
```

## Output

Describe the normal output shape in concise terms. Mention important structured result fields when the implementation returns a named result model.

## Prompt Examples

- "Show me how to use `<tool.name>` to <practical scenario>."
- "Use `<tool.name>` to <practical scenario>."
- "Check <target> with `<tool.name>` and summarize what I should do next."

Generation Checklist

Before finishing the 33 generated tool docs:

1. Confirm DynamicsCrm.DevKit.Wiki/mcp contains mcp_template_doc.md.
2. Confirm exactly 33 generated docs exist besides the template:

Get-ChildItem .\DynamicsCrm.DevKit.Wiki\mcp\mcp_*.md |
  Where-Object Name -ne 'mcp_template_doc.md' |
  Measure-Object

3. Confirm every generated filename is mcp_<tool.name>.md.
4. Confirm every page has an "MCP Tool Description (Exact)" section copied from tools/list.
5. Confirm every page has an estimated token count and records the counting method.
6. Confirm no generated page uses paraphrased descriptions in the exact description section.
7. Confirm source paths and categories match McpServerHost.ToolCategoryMap.
8. Confirm every page has a "Related MCP Resources" section.
9. Confirm listed resources exist in resources/list or resources/templates/list from the same server run.
10. Confirm every generated page has a "Prompt Examples" section with at least three practical English prompts.
11. Confirm resource contents are not copied wholesale into tool pages unless explicitly requested.

Template Change Policy

If future MCP metadata changes, update this template first when the documentation structure or extraction method needs to change. Do not silently generate docs with a different structure.