vcf-ops-mpb-mcp

Create or update a design item

mpb_upsert_item

Creates or updates requests, objects, relationships, or events in an MPB design by POSTing new items or PUTting existing payloads, so management-pack content can be edited programmatically.

Instructions

Creates (POST) or updates (PUT, payload carries its id) a request, object, relationship or event. Body shapes: requests = HttpRequest; objects = ObjectDefinition; relationships = {existingObjectTypeReferences:[], relationship:{...}}; events = {existingObjectTypeReferences:[], event:{...}}. Start from mpb_get_item itemId:"default" (new) or an existing item, then edit. Note: per-object PUT is known to answer 500 on some builds; if so, re-import the design instead.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "designId": "<designId>",
      "section": "<section>",
      "mode": "<mode>",
      "payload": "<payload>"
    },
    "name": "mpb_upsert_item"
  }
}

Input Schema

Name	Required	Description
`mode`	Yes	create = POST new item, update = PUT existing item
`payload`	Yes
`section`	Yes	Design section: requests, objects, relationships or events
`designId`	Yes	MPB design UUID (see mpb_list_designs)

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Nov 15, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description goes beyond them with an operational caveat: per-object PUT is known to answer 500 on some builds, with a documented fallback of re-importing the design. That is genuine failure-mode context an agent could not get from structured fields; auth and rate-limit behavior remain unstated.

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?

Three sentences, front-loaded with the create/update distinction, then body shapes, then workflow and caveat. Dense but nearly every clause carries information. Minor cost: the comma-spliced body-shape sentence is harder to parse than a short list would be.

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

Completeness3/5

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

For a four-required-parameter mutation tool with no output schema, the definition covers sections, payload shapes, bootstrapping and a known failure mode well. It says nothing about what is returned (created item id, resulting item state) or whether an update replaces or merges the existing item, which matters for a PUT-style operation with no output schema to lean on.

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 75%, and the weakest parameter — payload, a free-form additionalProperties object with no field schema — is exactly what the description compensates for by giving concrete body shapes per section (HttpRequest, ObjectDefinition, the relationships/events wrapper objects). It adds real meaning beyond the schema, though it doesn't enumerate required fields inside those shapes.

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 names a specific verb pair and resource set: 'Creates (POST) or updates (PUT, payload carries its id) a request, object, relationship or event'. It even encodes the HTTP-method distinction between create and update modes, so an agent knows exactly what the tool does without opening the schema.

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 gives an explicit starting-point workflow: use mpb_get_item with itemId:"default" for a new item or an existing item, then edit. That names a sibling and the condition for reaching it. It stops short of stating when NOT to use this tool (e.g. versus a generic API-call path), so it is clear context rather than full routing guidance.

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