PCD (Portable Context Deck)

Update PCD Skill

update_pcd_skill

Revise an existing skill’s instructions, discovery guidance or ownership; supports targeted patches. Use create_pcd_skill for a new method.

Input Schema

TableJSON Schema

Name	Required	Description
`echo`	No	action='patch' only — opt-in post-write self-verification. When true, the response adds echo: [{ slug, header, level, hash, markdown }] with the post-write rendered section per touched node (paragraph ops echo their parent section); removals return { slug, removed: true }; rename_section returns the new slug + renamed_from. Default absent: response unchanged. Rejected on other actions.
`name`	No	Rename the skill. Lowercase, underscores/hyphens, max 48 chars, must start with letter or number. Uniqueness re-checked per (container, deck) and per (container, shared).
`action`	No	'write' (default) — full-body replace + field edits, today's behaviour. 'describe' — pre-flight: returns the skill's section_tree (slugs + per-section hashes + addressing) for composing a patch; stub skills (no body) return section_tree: null. 'validate': pre-send check — name format/cap (48), description shape, signal_emission — WITHOUT writing or reading the row; returns { valid, missing_required[], over_cap: [{field, len, cap}], not_checked? }. 'patch' — targeted section/paragraph edits via patches[] without resending the whole body; skills declare no section_schema, so only op guards apply (slugs, hashes, HEADER_IN_CONTENT, duplicate-slug, rename_section frame-free).
`shared`	No	Toggle shared visibility. When flipped to true, name uniqueness is re-checked across all shared skills in the container.
`patches`	No	Patch ops for action='patch' — same vocabulary and addressing as write_knowledge action='patch': replace_section / replace_section_intro / append_section / insert_section_after / remove_section / rename_section / replace_paragraph / append_paragraph / insert_paragraph_after / prepend_paragraph / remove_paragraph. Compose against the section_tree from action='describe'; content is BODY-ONLY (HEADER_IN_CONTENT); expected_hash per op for optimistic concurrency. Pass as JSON array; a JSON-encoded string is also accepted.
`contract`	No	Help mode — return the complete contract with no operation performed.
`skill_id`	Yes	Skill UUID — required.
`deck_handle`	No	Reassign the skill to another deck in the SAME container by load handle. Target must be a container-context or specialized-context deck; name uniqueness is re-checked against the target deck. Works with action='write' (the default).
`description`	No	Replace the description object when provided. Must include summary + when_to_use. data_refs[].ref_name is a declared binding resolved against the skill's EFFECTIVE deck in order: own data_refs, own file_map, container-context data_refs. Container file_map never flows; shadowed declared names return a warning. triggers[] declares the PCD tool names after which this skill should surface as a one-line hint; see create_pcd_skill for the semantics.
`raw_markdown`	No	Replace the skill body (markdown) when provided.
`signal_emission`	No	Replace the skill's signal_emission when provided; pass null to clear it. See create_pcd_skill for the shape.
`expected_chapter_hash`	No	Optional whole-body concurrency guard for action='patch' — the raw_chapter_hash from action='describe'; mismatch rejects before any op runs.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 7, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

changedInput schema / properties / contract / description

Previous value: -"Help mode — pass true to receive this tool's full _meta.contract (all variants) with NO operation performed."New value: +"Help mode — return the complete contract with no operation performed."

addedInput schema / properties / description / properties / status

Added value: +{
+  "description": "Omit for active. Retired skills are hidden from discovery and hints; named reads return reference-only retirement guidance. Versioned with the description.",
+  "enum": [
+    "active",
+    "retired"
+  ],
+  "type": "string"
+}

First observedSep 7, 2026

TDQS

A4.9/5.0

Behavior5/5

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

The description discloses substantial behavior: full-body replacement, targeted patching, pre-flight describe, non-writing validate, concurrency guards, uniqueness re-checks, and section removal operations. There is no contradiction with the readOnlyHint and destructiveHint 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 long but appropriately structured and dense with relevant detail. Every parameter description adds meaningful guidance, and the nested objects are explained clearly without irrelevant filler.

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

Completeness4/5

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

The description covers return shapes for describe, validate, echo, and contract modes, which is helpful given there is no output schema. It is slightly less explicit about the success output for the default write action, but overall it provides enough context for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema coverage, the descriptions add significant semantic detail for each parameter, including action-specific behavior, patch op vocabulary, deck-handle constraints, description resolution order, signal-emission shape, and concurrency hashes. This goes well beyond the raw 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?

The title and description clearly state that this tool updates an existing PCD skill, and explicitly directs users to create_pcd_skill for new skills. This distinguishes it from the sibling create and run tools.

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?

The description clearly indicates when to use this tool versus creating a new skill, and the action parameter explains distinct usage modes like describe, validate, patch, and write. This provides strong contextual guidance for tool selection.

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

All PCD (Portable Context Deck) tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?