Skip to main content
Glama

PCD (Portable Context Deck)

by ai.portablecontext.mcp
OverviewDiscussionsAdmin

Read Topology

read_topology
Read-only

Read current work, a particular work item, or historical trails.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoPaging — max entries to return (default 20, max 100). Ignored unless trail is set.
trailNoTrail paging (topology 3.0) — when set, returns { container_id, trail, entries, has_more } from the did trail (the client-written narrative: ts, text, work_ref?, by?) or the ops audit (worker-only: ts, action, ref?, detail?). Newest-first; pair with before/limit to walk deeper — retention is keep-everything, so the full history is reachable.
beforeNoPaging — ISO timestamp; only entries with ts < before are returned. Pair with limit. Ignored unless trail is set.
contractNoHelp mode — return the complete contract with no operation performed.
work_itemNoWork-item paging — when set, finds the work item by `what` across all four groups (active/paused/blocked/done) and returns { container_id, work_item: { group, item } } with the full item including state/next, all annotations, refs, and group-specific fields. Use to revive a paused thread when boot trim hid the item's full context. Returns an error if no item with the given `what` exists. Mutually exclusive with trail.
projectionNoRead grain (topology 3.0). 'full' (default): the complete state row (work + scalars — work items carry state/next) plus the did tail (12) and ops tail (10) from their tables, newest-first. 'summary': the hot multi-window handoff read — work headers with per-group counts + the did tail, no ops. Ignored when trail or work_item is set (those keep their own focused shapes).
container_idYesContainer ID — without trail or work_item, returns { projection, state } (see projection). worker_meta is not returned (platform-internal).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • 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."
  2. First observed

TDQS

A4.3/5.0
Behavior4/5

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

The description consistently reflects the read-only annotation by describing operations as returning data and explicitly stating that help mode performs no operation. It also discloses edge behavior like errors when no work item exists and ignored parameters, providing good transparency without contradicting the readOnlyHint.

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?

The description is dense but each sentence carries functional value, covering modes, paging, projections, and error conditions without irrelevant filler. While lengthy, the structure groups related parameters and keeps the information organized, making it efficient for an agent to parse.

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?

Although there is no output schema, the description provides return shapes for each mode, mentions defaults and paging behavior, and notes error cases. This gives an agent enough context to understand what to expect and how to use the tool correctly, though exact field details of the returned state are not fully specified.

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?

All seven parameters are described in the schema, and the description adds meaningful behavior beyond the raw schema, such as defaults, mutual exclusivity, and the purpose of work_item for reviving paused threads. It does not simply restate the schema; it explains when each parameter matters.

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 the tool's purpose with a specific verb ('Read') and clearly distinguishes the three resource types it can read: current work, a particular work item, or historical trails. This makes the tool's scope immediately understandable and differentiates it from sibling tools that write or manage topology.

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?

The description gives practical guidance for when to use each mode, such as using work_item to revive a paused thread when boot trim hid context, and explains mutual exclusions and ignored parameters. It does not explicitly compare against sibling tools, but the mode-specific instructions are sufficient for typical 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) toolsInspect
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