Itential MCP Server

Official

by itential

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Complete Manual Task

complete_manual_task

Destructive

Completes a single manual task after explicit human approval, letting the waiting workflow job or agent proceed; preview first because completion is irreversible.

Instructions

DESTRUCTIVE: complete a single manual task (work item).

IMPORTANT: completing a manual task is IRREVERSIBLE and cannot be retried. It lets the waiting job or agent session proceed. The platform records the completion against the MCP service account or OAuth client, NOT against the person who asked; there is no per-user authorization, so the human's own entitlements are not checked. ASK THE HUMAN before calling this tool with confirm=True, showing them the preview (task, finish state and warnings) first. Never complete a task the human has not explicitly approved, and never complete tasks in bulk: this tool acts on exactly one work_item_id. Use describe_manual_task to present the task (header, message, body and the button labels) to the human before asking them to decide.

Call it first with confirm=False (the default) to get a preview; no change is made. Call it again with confirm=True only after the human approves.

Valid finish states are the literal strings "success" and "failure" (they are not button labels like "Continue" or "Approve"). "success" is always valid. "failure" is only valid when the task has a failure button (a non-empty btn_failure in describe_manual_task); the platform does not check this itself, and a failure on a success-only task sends the job to an error state. Only ViewData, ViewHTML and InteractiveHTML tasks are supported; form tasks (RenderJsonSchema, viewTemplateResults) must be completed in the Itential UI.

"success" is the task's main button, not necessarily "approve": it is whatever the workflow author labeled it ("Continue", "Approve", "Validate", ...), and on ViewData and ViewHTML tasks it only means "continue", as there is no decision. "failure" is the second button ("Deny", "Reject", "Cancel") and what it does is defined by the workflow or agent author (a job follows its failure transition; an agent may report the task cancelled). Read the human's answer against the button labels from describe_manual_task and map it to success or failure. Never assume success is the default and never decide on the human's behalf.

Input Schema

Name	Required	Description
`confirm`	No	Must be True to actually complete the task. When False (default) nothing changes and a preview is returned. Only set True after the human has explicitly approved the preview.
`variables`	No	Optional variables to submit with the completion. Normally empty for ViewData, ViewHTML and InteractiveHTML tasks.
`finish_state`	Yes	How to finish the task: the literal string 'success' or 'failure'. These are not button labels. 'success' is the task's main button (not necessarily 'approve'); 'failure' is the second button and is only valid when describe_manual_task shows a non-empty btn_failure.
`work_item_id`	Yes	The work item ID of the manual task to complete (the work_item_id from describe_manual_task). Exactly one task.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.15.0Oct 30, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial context the annotations cannot: irreversibility, no retry, the waiting job/session proceeds, and that completion is attributed to the MCP service account/OAuth client rather than the requesting human, with no per-user authorization check. It further discloses a platform gap — failure state is not validated server-side and can push a success-only task into an error state.

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

Conciseness4/5

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

The critical warnings (destructive, irreversible, ask the human) are front-loaded, and nearly every sentence carries operational content. It is long and mildly redundant — the success/failure mapping is explained in two separate paragraphs — but for an irreversible write tool the length is largely earned.

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?

Given a destructive mutation with an output schema present, complete schema coverage and full annotations, the description covers everything an agent needs: prerequisites (human approval, preview), the two-call protocol, state validity rules, unsupported task types, and attribution semantics.

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%, so the baseline is 3; the description earns above that by explaining that finish_state takes literal strings rather than the human-visible button labels, and that 'failure' is only legal when describe_manual_task shows a non-empty btn_failure. It also tells the agent to map the human's answer onto button labels and that variables are normally empty for the supported task types.

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?

Opens with an explicit verb+resource and scope: 'complete a single manual task (work item)', flagged DESTRUCTIVE up front. It explicitly distinguishes itself from the read-only sibling describe_manual_task and states it acts on exactly one work_item_id, so an agent can route correctly without opening either 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?

Gives a full usage protocol: call with confirm=False for a preview, then confirm=True only after human approval; use describe_manual_task to present the task; never bulk-complete. It also names an explicit exclusion — form tasks (RenderJsonSchema, viewTemplateResults) must be completed in the Itential UI instead.

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

Deploy Server