poml-mcp/spec/POML_CONVENTIONS.md

MCP server that enhances user prompts using POML-style structure

# POML Conventions for MCP Server

Source of truth: <https://github.com/microsoft/poml>

This server structures prompts and translations into a consistent POML skeleton so agents and LLMs can interoperate. The minimal, stable subset we rely on is:

- `poml`
- `task` (with `className="instruction"`)
- `output-format` (with `className="instruction"`) with `list` and `item`
- `cp` (with `caption="Style"` and `captionSerialized="style"`)
- `cp` (with `caption="Include"` and `captionSerialized="include"`)
- `cp` (with `caption="Constraints"` and `captionSerialized="constraints"`)

We use ordered or unordered lists as needed (`list` with optional `listStyle`), and keep content plaintext unless a `code` block is explicitly required.

## Design notes

- The server generates a portable POML template for each request or translation. This template is sufficient for downstream rendering or direct execution.
- The names Style, Include, and Constraints are intentional to keep prompts predictable across tools.
- Default guardrails (constraints) emphasize clarity and explicitness, avoiding hallucinations.

## Example

```xml
<poml>
  <task className="instruction">Create a high-quality response for the following request: …</task>
  <output-format className="instruction">
    <list>
      <item>Title</item>
      <item>Introduction (purpose/context)</item>
      <item>Main Content (well-structured sections)</item>
      <item>Examples (if relevant)</item>
      <item>Conclusion (summary + next steps)</item>
    </list>
  </output-format>
  <cp className="instruction" caption="Style" captionSerialized="style">
    <list>
      <item>Clarity: concise, concrete, unambiguous</item>
      <item>Structure: use headings, lists, tables where helpful</item>
    </list>
  </cp>
  <cp className="instruction" caption="Include" captionSerialized="include">
    <list>
      <item>As required by the task</item>
    </list>
  </cp>
  <cp className="instruction" caption="Constraints" captionSerialized="constraints">
    <list>
      <item>Cite assumptions and ask for missing info succinctly</item>
      <item>Avoid hallucinations; say 'not available' for missing data</item>
    </list>
  </cp>
</poml>
```

## Upstream tracking

- Changes in microsoft/poml can be reviewed periodically (via CI schedule) and reflected here.
- This server intentionally sticks to a stable subset; expansions should remain backward compatible.