Skip to main content
Glama

promote_capture

Move a reviewed Wild Art capture into its correct type—RC, SYN, REV, DC, or ISO—while preserving IDs, content, links, and promotion history.

Instructions

Move a Wild Art (WA) entry to its proper type after review — RC, SYN,
REV, DC, or ISO (3-D isometric grid page).

The capture keeps its #id, text, image, and asserted links; it is
re-parsed as the target type. Its WA history is preserved on the
promoted entry: promoted_from (the WA-NNN ID), wa_reason, and wa_detail.

If the target page ID is already taken in that volume, NOTHING changes:
the conflict is reported and you choose — a different page ID, a
different volume (a page from a new journal), or force=True. Page IDs are
never renumbered automatically.

Args:
    capture_id:     The WA entry's numeric ID (#N).
    target_type:    RC | SYN | REV | DC | ISO.
    target_page_id: The page ID to file it under, e.g. "RC-014". Optional
                    when the page was read with an ID (claimed_page_id)
                    of the target type — that ID is used.
    volume:         Journal volume to file it in (0 = the volume the WA
                    entry already has, else the current writing volume).
    force:          DANGEROUS. Take the page ID even though another
                    capture holds it. The current holder is not deleted —
                    it is moved to Wild Art itself (reason id_conflict,
                    conflicts_with pointing here) — but every @reference
                    to that page ID from now on resolves to THIS capture.
                    Only use it when you are sure the current holder is
                    the misfiled one.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
forceNo
volumeNo
capture_idYes
target_typeYes
target_page_idNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv3.9.0

TDQS

A4.5/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 disclosure burden and does so thoroughly: it says exactly what is preserved (#id, text, image, asserted links), what metadata is carried over (promoted_from, wa_reason, wa_detail), that a page-ID conflict changes NOTHING until the caller decides, that IDs are never auto-renumbered, and the precise side effect of force (holder moved to Wild Art, all @references re-resolve to this capture).

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?

Purpose, conflict behavior, and the force warning are front-loaded before the Args block, and every sentence carries operational information. It is long, but the length is justified by the mutation's complexity; some of the WA-history detail could be trimmed.

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?

An output schema exists, so return formatting need not be described; the description instead covers everything an agent needs to call this safely — conflict handling, ID/volume resolution, and the reference-rewriting consequence of force. Complete for a complex mutation with 0% schema coverage and no annotations.

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?

Schema description coverage is 0%, so the description must compensate, and its Args block defines all five parameters with defaults and exact semantics — capture_id as #N, the target_type enumeration, target_page_id fallback to claimed_page_id, volume's 0 = existing/current-volume rule, and force's danger and side effects. This adds substantial meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource — moving a Wild Art entry to its proper type after review — and enumerates the valid targets (RC, SYN, REV, DC, ISO). It clearly distinguishes the WA-promotion action from generic capture handling, though it never names a sibling tool it should be preferred over.

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?

Context for use is clear: this happens 'after review' on a WA entry, and it explains when target_page_id may be omitted (when the page was read with a claimed_page_id of the target type). force carries an explicit when-to-use caveat ('Only use it when you are sure the current holder is the misfiled one'), but no alternatives from the sibling set are named.

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