portkey-admin-mcp

migrate_prompt

Idempotent

Creates or updates a prompt by name in a collection, adding a new version when content changes and leaving it unchanged when identical. Supports dry-run checks for CI/CD prompt-as-code workflows.

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.

Input Schema

TableJSON 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

TableJSON 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.

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.9/5.0

Behavior5/5

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description enriches those with exact semantics: creates if missing, adds a new version without overwriting if content differs, no-ops if content already matches, and dry_run changes nothing. It also discloses side-effect context ('Stores app/env in template_metadata') and the return payload. No contradiction with the annotations.

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 dense but economical, packing purpose, sibling distinction, the idempotent state machine, dry-run behavior, metadata storage, collection_id sourcing, and return fields into four sentences. It is front-loaded with the core purpose and avoids redundant schema details.

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 16-parameter tool with an output schema, the description covers the non-obvious selection and invocation details: idempotency semantics, no-overwrite safety, where collection_id comes from, and what action/identifiers are returned. Nothing an agent needs to safely migrate a prompt 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 description coverage is 100%, so the baseline is 3, but the description adds value by clarifying dry_run behavior, explaining that app/env are persisted into template_metadata, and providing a source for collection_id via list_collections. The remaining parameter meanings are adequately handled by the schema.

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?

States a specific verb and resource ('Create or update a prompt') and immediately scopes it as an idempotent step for CI/CD and prompt-as-code flows. It explicitly differentiates itself from create_prompt, so an agent can distinguish it from the closest sibling 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 Guidelines5/5

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

Gives explicit when-to-use context ('for CI/CD and prompt-as-code flows') and names the key alternative with its distinguishing behavior ('unlike create_prompt which always makes a new prompt'). It also tells the caller where to obtain collection_id ('get collection_id from list_collections'), covering the main prerequisite for invoking the tool.

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

Deploy Server