mcp-server-polarion

create_document

Create a new Polarion document in a specified space with unique name, title, type, markdown body, and rendering layouts for work items.

Instructions

Create a document in a space.

document_name must be unique in the space — a duplicate name conflicts; check list_documents first. type/status and custom_fields keys are validated on write — resolve ids via list_document_enum_options first.

Set rendering_layout_types to every work item type the document will hold — without a layout their fields do not render in the Polarion UI. Resolve those ids via list_work_item_enum_options; a later update_document must resend every type to keep.

home_page_content is Markdown (greenfield only), converted to sanitized HTML. Markdown tables get native Polarion styling; a paragraph starting 'Table:' directly after a table becomes a numbered caption widget. Post-create edits round-trip raw HTML via get_document(include_home_page_content_html=True) and update_document; add work items via move_work_item_to_document.

Input Schema

TableJSON Schema

Name	Required	Description
`type`	Yes	Document type (e.g. 'req_specification', 'generic').
`title`	Yes	Human-readable document title.
`status`	No	Initial workflow status (project default if omitted).
`dry_run`	No	Preview payload without writing; guards still query Polarion.
`space_id`	Yes	Space ID ('_default' = default space).
`project_id`	Yes	Polarion project ID.
`auto_suspect`	No	Flag linked work items suspect on change.
`custom_fields`	No	Keyed by Polarion field ID (copy keys from a sibling document); rich-text values as {'type':'text/html','value':...}.
`document_name`	Yes	Document name (e.g. 'MySpecV1'); unique within space_id, appears in the document URL.
`home_page_content`	No	Markdown body; converted to sanitized HTML.
`rendering_layout_types`	No	Work item type IDs the document will hold (e.g. ['softwarerequirement']).
`uses_outline_numbering`	No	Enable auto outline numbers (1, 1.1, ...).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`created`	Yes
`dry_run`	Yes
`document_name`	Yes
`payload_preview`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv2.1.0Sep 24, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already signal non-read-only and non-idempotent behavior, but the description adds substantial behavioral context: duplicate-name conflicts, write-time validation, layout requirements for UI rendering, Markdown-to-HTML conversion, sanitization, table/caption behavior, and raw-HTML round-tripping on later updates. This goes far beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place. It front-loads the core action, then moves from uniqueness constraints to validation to rendering to post-create editing, with no filler or repetition of schema defaults. The length is justified by the complexity of the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter creation tool with an output schema, the description covers the essential preconditions, side effects, and cross-tool workflows. It explains what must be checked before calling, what happens on validation, how rendering is affected, and how to amend content later. Nothing critical for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema description coverage is 100%, the description adds critical meaning beyond the schema: document_name uniqueness, validation of type/status and custom_fields, the rendering consequence of rendering_layout_types, and rich Markdown behavior for home_page_content. These are not derivable from the input schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Create a document in a space.' It clearly separates creation from update, copy, and attachment tools among siblings, and the body reinforces the unique responsibility by contrasting with update_document and move_work_item_to_document.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit preconditions and sequencing: check list_documents first for duplicate names, resolve enum ids via list_document_enum_options and list_work_item_enum_options, and use update_document for subsequent edits. It even notes that rendering_layout_types must be set on creation, which is critical for correct usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server