midPoint MCP Server

Overview Schema Source Related Servers Discussions Admin

Claim work item

claim_work_item

Takes ownership of an open approval work item offered to your group so you can approve or reject it; checks that it is available and not already held before claiming.

Instructions

Claim an open approval work item offered to a group you belong to (offered: true in list_work_items), so it becomes yours to approve or reject with decide_work_item; the rest of the group can no longer claim it. Before writing anything it reads the case as you and refuses an item that is closed, already held by someone (you included), or not offered to you. release_work_item gives it back. The claim executes as you, and the result says whether midPoint now shows the item as yours. userName and roleName are the midPoint names (the unique name attribute, such as a login, not display names) of the objects the OIDs point to, as list and get results give them; the call is refused when they don't match, so the person confirming it reads the right names. Respects the write gate. When you write to a person, name people, roles and requests by their display names rather than OIDs.

Input Schema

Name	Required	Description
`caseOid`	Yes	OID of the case (caseOid from list_work_items)
`roleName`	Yes	midPoint name of the role (or other object) the request adds or removes; empty only when midPoint doesn't show you its name
`userName`	Yes	midPoint name (login) of the person the request is for; empty only when midPoint doesn't show you their name
`workItemId`	Yes	id of the work item within the case (id from list_work_items)

Output Schema

Name	Required	Description
`body`	No	the JSON body of the midPoint REST request, when it has one
`case`	No	the case name
`tool`	Yes	the tool that produced this result
`acting`	Yes	who midPoint executed this call as
`dryRun`	Yes
`method`	Yes
`object`	No	the focus the case changes
`result`	No
`server`	Yes	write gate, features and versions of this server
`target`	No	what was requested
`applied`	Yes
`caseOid`	Yes
`subject`	Yes	the identity midPoint executed the call as (or, in a dry run, would)
`summary`	Yes
`endpoint`	Yes
`confirmed`	Yes	true when the case read back after the call shows the change: a claimed item held by you alone, or a released item held by nobody (or no longer shown to you)
`offeredTo`	Yes	the group the item is offered to, or was claimed from
`workItemId`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 6, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and delivers: it discloses a pre-write read of the case, the exclusivity semantics (the rest of the group can no longer claim it), the refusal conditions, that the claim executes under the caller's identity, and that the result reports whether midPoint now shows the item as yours. It also mentions the write gate, which is the permission model an agent needs to anticipate failures.

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

Conciseness3/5

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

The purpose and precondition are front-loaded, but the body is one dense run-on paragraph mixing claim semantics, refusal rules, identity, return behavior, and a global style rule. The trailing display-name instruction is both stylistically out of place and semantically conflicting, so it does not earn its place in this tool's definition.

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

Completeness4/5

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

For a 4-required-parameter mutation with an output schema, the description covers preconditions, exclusivity, failure modes, and the fact that the response confirms ownership, which is enough for correct invocation. The only real defect is the contradictory name-format guidance, which could cause an agent to pass a display name and get refused.

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

Parameters4/5

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

Schema coverage is 100%, but the description still adds meaning: userName/roleName must be midPoint unique names (logins) of the objects the OIDs point to, and the call is refused on mismatch, which explains why they are required for a claim keyed by OIDs. The final sentence, however, tells the agent to use display names 'rather than OIDs', which sits in tension with the login-not-display-name rule stated two sentences earlier and muddies an otherwise clear confirmation-safety contract.

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 states a specific verb and resource ('Claim an open approval work item offered to a group you belong to') and immediately names the downstream sibling ('decide_work_item') and the undo path ('release_work_item'). An agent can distinguish this from list_work_items and decide_work_item without opening any schema.

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?

It gives an explicit precondition ('offered: true in list_work_items'), names the alternatives for the next and reverse steps, and enumerates exactly when the call will be refused (closed, already held by someone including you, or not offered to you). This is when/when-not guidance with routing, not inference.

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