Mipiti MCP Server

Overview Schema Source Related Servers Discussions Admin

Refine Control

refine_control

Refine a control's description with AI-gated control-objective sufficiency check, rejecting changes that reduce protection for mapped objectives and returning per-objective reasoning.

Instructions

Refine a control's description with AI-gated CO sufficiency check.

Two modes:

Provide description: proposes a new description directly.
Provide codebase_findings: the platform proposes a description based on existing code that may already satisfy the control.
Both can be provided: the platform evaluates the proposed description with the codebase findings as context.

The AI evaluates whether the mitigation group still collectively satisfies all mapped control objectives. If rejected, returns {accepted: false, reason, per_co} with per-CO reasoning.

A refinement is rejected when the proposed description would reduce the protection the control currently states for an objective it is mapped to; per_co names each objective and explains why. This is a decision, not a transient error — re-wording the same narrowing will not pass it, and it applies however well-motivated the narrowing is. A control is a requirement that must be met to cover its objectives, so evidence that the system does not currently meet it means the control is UNMET, never that the control should ask for less.

Side effect on accepted refinements: every assertion attached to this control is superseded — their claims were authored against the prior description and are not guaranteed to align with the new one. The response includes superseded_assertions: <count> so the caller knows how many. Re-submit any assertion that still applies under the new description; superseded rows remain in history with superseded_by="control_refined:...".

Input Schema

TableJSON Schema

Name	Required	Description
`model_id`	Yes	ID of the threat model.
`control_id`	Yes	ID of the control to refine (e.g., "CTRL-03").
`description`	No	Proposed new control description (optional if codebase_findings provided).
`justification`	No	Why this refinement is appropriate (10 to 2000 characters).
`server_version`	Yes
`codebase_findings`	No	Description of existing code that may already satisfy this control's objective (optional). When provided without description, the platform proposes a description.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.77.1Sep 16, 2026

changedInput schema / properties / justification / description

Previous value: -"Why this refinement is appropriate (min 10 chars)."New value: +"Why this refinement is appropriate (10 to 2000\ncharacters)."

First observedv0.57.0Jul 8, 2026

TDQS

A4.7/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 behavioral burden and meets it. It discloses the rejection contract (accepted: false, reason, per_co), explains that rejection is a deliberate decision rather than a retryable error, and warns that accepted refinements supersede all attached assertions with a count and history marker.

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 long but tightly organized with a summary line, bulleted modes, and a bolded side-effect section. Every paragraph earns its place by covering invocation, decision semantics, or irreversible consequences, and the most important nuance is front-loaded.

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 high-complexity tool with no annotations, the description covers the full decision flow, rejection criteria, output envelope, and side effects. Since an output schema exists, omitting a full return-value breakdown is acceptable, and nothing needed to call the tool correctly is missing.

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 high at 83%, so the baseline is 3, and the description adds meaningful semantics by explaining the roles of description and codebase_findings and how both together are evaluated. It does not need to repeat schema details for model_id, server_version, or justification because those are already documented or standard.

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 precise verb-resource pairing: "Refine a control's description with AI-gated CO sufficiency check." This distinguishes it from sibling tools like update_control_status or remap_control, which change status or mappings rather than the description under a sufficiency gate.

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

Usage Guidelines4/5

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

It clearly enumerates the two invocation modes and the combined mode, telling an agent exactly when to provide description versus codebase_findings. It does not explicitly contrast sibling tools, so there is no direct when-not-to-use guidance, but the mode breakdown is strong context.

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

Deploy Server