portkey-admin-mcp

migrate_prompt

Idempotent

Idempotently creates or updates a named prompt within a collection for CI/CD and prompt-as-code workflows: creates if missing, versions if content changes, no-ops if unchanged, and supports dry runs.

Instructions

Create or update a prompt in one idempotent step for CI/CD and prompt-as-code flows, unlike create_prompt which always makes a new prompt. Looks up the prompt by name within collection_id: if missing it creates the prompt, if found with different content it adds a new version (nothing is overwritten), and if the content already matches it no-ops; dry_run reports what would happen without changing anything. Stores app/env in template_metadata; get collection_id from list_collections. Returns the action taken (created, updated, or unchanged), dry_run flag, message, prompt id, slug, and version id.

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": {
      "name": "<name>",
      "app": "<app>",
      "env": "<env>",
      "collection_id": "<collection_id>",
      "parameters": "<parameters>",
      "virtual_key": "<virtual_key>"
    },
    "name": "migrate_prompt"
  }
}

Input Schema

Name	Required	Description
`app`	Yes	App identifier (REQUIRED). Use your deployed app name, for example 'hourlink' or 'support-console'.
`env`	Yes	Environment identifier (REQUIRED). Use your environment name, for example 'dev', 'staging', 'prod', or 'qa'.
`name`	Yes	Prompt name to create or find for update
`model`	No	Model identifier
`tools`	No	Tool definitions
`string`	No	Legacy prompt template string with {{variable}} mustache syntax.
`dry_run`	No	When true, only check what action would be taken without making changes
`messages`	No	Structured chat template alias for migrations. Serialized to the legacy string format before the prompt is created or updated.
`functions`	No	Function definitions
`parameters`	Yes	Default values for template variables
`tool_choice`	No	Tool choice strategy
`virtual_key`	Yes	Virtual key slug for model access
`collection_id`	Yes	Collection ID to search in and create under
`is_raw_template`	No	Preserve raw structural-template rendering semantics
`template_metadata`	No	Additional custom metadata
`version_description`	No	Description for this version

Output Schema

Name	Required	Description
`ok`	Yes	Whether the tool call succeeded and returned structured data
`data`	No	Structured success payload when ok is true
`error`	No	Structured error payload when ok is false

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.0.9Oct 26, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedv0.11.5Sep 8, 2026

addedInput schema / properties / is_raw_template

Added value: +{
+  "description": "Preserve raw structural-template rendering semantics",
+  "type": "boolean"
+}

Addedv1.0.1May 7, 2026
RemovedMay 1, 2026
First observedJan 1, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the annotations (idempotent, non-destructive, not read-only), the description discloses exactly how idempotency is achieved: lookup by name within collection_id, create if missing, add a new version if content differs (nothing overwritten), and no-op if content matches. It also explains dry_run behavior and what gets stored in template_metadata, giving rich behavioral context.

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 a single dense paragraph but front-loads the core action and differentiator. Every sentence earns its place: idempotent logic, dry_run, metadata storage, collection_id sourcing, and return values are all necessary for correct invocation.

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 the complexity (16 parameters, nested objects, output schema present), the description covers the critical behavioral details, parameter sourcing, and return-value summary. An agent has everything needed to call it correctly without further documentation.

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; however, the description adds meaning for key parameters: name lookup behavior, dry_run semantics, template_metadata storage, and where to obtain collection_id. It doesn't explain all 16 parameters, but the extra context for the most consequential ones justifies a 4.

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+resource ('Create or update a prompt') and immediately distinguishes it from the sibling create_prompt by explaining that this tool is idempotent. An agent can tell exactly what it does and how it differs from the alternative without inspecting 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 names the intended context ('CI/CD and prompt-as-code flows') and explicitly contrasts with create_prompt, which always makes a new prompt. It also points to list_collections for getting collection_id. While it doesn't spell out when not to use the tool, the alternative is clear enough for correct selection.

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

Deploy Server