Skip to main content
Glama
Sign In
Polarion MCP Server

Polarion MCP Server

by phillipboesger
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Search Work Items

search_work_items
Read-only

Search Polarion work items using structured filters such as project, type, status, assignee, text, and dates; automatically escapes values into a Lucene query and returns concise summaries.

Instructions

Search Work Items using structured filters, escaping values into a Lucene query. Returns {query, results, links?, totalCount?, truncated?} with concise item summaries. Provide projectId to search one project; omit it for the global getAllWorkItems search, which requires global read access. Use this for common filters; use getWorkItems or getAllWorkItems directly for advanced Lucene syntax, custom response fields, or includes.

Input Schema

NameRequiredDescriptionDefault
sortNoValid Work Item field ID; prefix with `-` for descending order. Unknown fields are rejected.
textNoText to match in the Work Item text fields searched by Polarion.
typesNoLimit results to these Work Item type IDs.
filtersNoAdditional exact field/value filters; unknown fields are rejected.
assigneeNoAssignee user ID, not a display name or email address.
statusesNoLimit results to these workflow status IDs.
max_itemsNoMaximum results collected, from 1 to 1000; also used as page size if `page_size` is absent.
page_sizeNoMaximum items returned in the requested page, from 1 to 1000.
projectIdNoOptional project ID; omit to search across projects, subject to global read permissions.
createdAfterNoInclusive date/time lower bound for creation, in a format JavaScript Date.parse accepts.
updatedAfterNoInclusive date/time lower bound for last update, in a format JavaScript Date.parse accepts.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed15 schema fields changedv1.4.4
    • addedInput schema / properties / assignee / description
      Added value: +"Assignee user ID, not a display name or email address."
    • addedInput schema / properties / createdAfter / description
      Added value: +"Inclusive date/time lower bound for creation, in a format JavaScript Date.parse accepts."
    • addedInput schema / properties / filters / description
      Added value: +"Additional exact field/value filters; unknown fields are rejected."
    • addedInput schema / properties / filters / items / properties / field / description
      Added value: +"Valid Work Item field ID, including custom fields available in the project."
    • addedInput schema / properties / filters / items / properties / value / description
      Added value: +"Exact value to match; escaped and quoted before adding to the Lucene query."
    • addedInput schema / properties / max_items / description
      Added value: +"Maximum results collected, from 1 to 1000; also used as page size if `page_size` is absent."
    • addedInput schema / properties / page_size / description
      Added value: +"Maximum items returned in the requested page, from 1 to 1000."
    • addedInput schema / properties / projectId / description
      Added value: +"Optional project ID; omit to search across projects, subject to global read permissions."
    • addedInput schema / properties / sort / description
      Added value: +"Valid Work Item field ID; prefix with `-` for descending order. Unknown fields are rejected."
    • addedInput schema / properties / statuses / description
      Added value: +"Limit results to these workflow status IDs."
    • addedInput schema / properties / statuses / items / description
      Added value: +"Workflow status ID, such as `open`."
    • addedInput schema / properties / text / description
      Added value: +"Text to match in the Work Item text fields searched by Polarion."
    • addedInput schema / properties / types / description
      Added value: +"Limit results to these Work Item type IDs."
    • addedInput schema / properties / types / items / description
      Added value: +"Work Item type ID, such as `requirement`."
    • addedInput schema / properties / updatedAfter / description
      Added value: +"Inclusive date/time lower bound for last update, in a format JavaScript Date.parse accepts."
  2. Addedv1.4.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations only declare readOnlyHint, so the description carries real weight and delivers: it discloses the return shape with optional links/totalCount/truncated fields, that values are escaped and quoted into the Lucene query, and that the global search requires global read access. What it does not clarify is how max_items interacts with page_size across pages, which is the remaining behavioral gap.

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?

Three tight sentences: purpose first, return contract second, scoping and alternatives last. No filler, and each sentence carries information an agent needs to choose and call 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 an 11-parameter search tool with no output schema, the description covers purpose, permission prerequisite, result shape, and the escape hatch to sibling tools. Nothing essential to a correct first call is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter is already documented, including the max_items/page_size relationship and sort prefix syntax. The description adds only the projectId-omission consequence, which largely restates the schema's own wording, so the baseline 3 is appropriate.

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?

States a specific verb and resource ('Search Work Items') plus the mechanism ('structured filters, escaping values into a Lucene query'). It also distinguishes itself from getWorkItems/getAllWorkItems, so an agent can route without opening schemas.

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?

Explicitly says when to use this tool ('common filters') versus the direct alternatives ('advanced Lucene syntax, custom response fields, or includes'). It also gives the scoping rule for projectId: include it for one project, omit it for the global search, with the permission consequence noted.

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

Deploy Server

Other Tools