Skip to main content
Glama

PCD (Portable Context Deck)

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, warnings? } from the did trail (the client-written narrative: ts, text, work_ref?, by?) or the ops audit (worker-only: ts, action, ref?, detail?), every action included. Newest-first; pair with before/limit to walk deeper — retention is keep-everything, so the full history is reachable. On trail='ops', include_actions / exclude_actions narrow the window.
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 } } (plus warnings when an ops-trail action filter is set without trail='ops') 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. Takes precedence over trail when both are set.
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; the ops tail leaves out the reads (knowledge_read, knowledge_describe, knowledge_validate, reground_called). '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), plus warnings when an ops-trail action filter is set without trail='ops'. worker_meta is not returned (platform-internal).
exclude_actionsNoOps-trail filter: leave out these actions (exact names or a prefix ending in *). With include_actions, the result is include minus exclude. Applies to trail='ops' only; elsewhere it is ignored with a warning.
include_actionsNoOps-trail filter: return only these actions. Each entry is an exact action name or a prefix ending in * (e.g. 'signal_*'). Unknown names are dropped with a warning; if nothing is left, no entries are returned. Applies to trail='ops' only; elsewhere it is ignored with a warning.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / work_item / description
      Previous value: -"Work-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 } } (plus warnings when an ops-trail action filter is set without trail='ops') 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."New value: +"Work-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 } } (plus warnings when an ops-trail action filter is set without trail='ops') 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. Takes precedence over trail when both are set."
  2. Changed6 schema fields changed
    • changedInput schema / properties / container_id / description
      Previous value: -"Container ID — without trail or work_item, returns { projection, state } (see projection). worker_meta is not returned (platform-internal)."New value: +"Container ID — without trail or work_item, returns { projection, state } (see projection), plus warnings when an ops-trail action filter is set without trail='ops'. worker_meta is not returned (platform-internal)."
    • addedInput schema / properties / exclude_actions
      Added value: +{
      +  "description": "Ops-trail filter: leave out these actions (exact names or a prefix ending in *). With include_actions, the result is include minus exclude. Applies to trail='ops' only; elsewhere it is ignored with a warning.",
      +  "items": {
      +    "maxLength": 64,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 25,
      +  "type": "array"
      +}
    • addedInput schema / properties / include_actions
      Added value: +{
      +  "description": "Ops-trail filter: return only these actions. Each entry is an exact action name or a prefix ending in * (e.g. 'signal_*'). Unknown names are dropped with a warning; if nothing is left, no entries are returned. Applies to trail='ops' only; elsewhere it is ignored with a warning.",
      +  "items": {
      +    "maxLength": 64,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 25,
      +  "type": "array"
      +}
    • changedInput schema / properties / projection / description
      Previous value: -"Read 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)."New value: +"Read 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; the ops tail leaves out the reads (knowledge_read, knowledge_describe, knowledge_validate, reground_called). '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)."
    • changedInput schema / properties / trail / description
      Previous value: -"Trail 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."New value: +"Trail paging (topology 3.0) — when set, returns { container_id, trail, entries, has_more, warnings? } from the did trail (the client-written narrative: ts, text, work_ref?, by?) or the ops audit (worker-only: ts, action, ref?, detail?), every action included. Newest-first; pair with before/limit to walk deeper — retention is keep-everything, so the full history is reachable. On trail='ops', include_actions / exclude_actions narrow the window."
    • changedInput schema / properties / work_item / description
      Previous value: -"Work-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."New value: +"Work-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 } } (plus warnings when an ops-trail action filter is set without trail='ops') 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."
  3. 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."
  4. First observed

TDQS

B3.3/5.0
Behavior2/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered, and the description adds nothing behavioral on top of that. Retention guarantees (keep-everything history), the warning behavior for misplaced filters, and the omission of worker_meta are all disclosed in parameter descriptions, not in the prose. The one sentence carries no behavioral context of its own.

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?

A single front-loaded sentence that names the three modes in order of specificity, with zero filler. It is appropriately tight, though it leans so terse that the mode-selection logic is left entirely to the schema.

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?

This is a complex nine-parameter tool with three read modes and no output schema, which would normally demand heavy description support. The extremely rich schema descriptions compensate by spelling out each mode's return shape and paging semantics, so the terse prose is defensible rather than incomplete.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema fully documents all nine parameters, including enums, defaults, precedence, and return shapes. The top-level description adds no parameter meaning beyond the fields, so the baseline 3 is the correct ceiling here.

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 names a specific verb (Read) and enumerates the three distinct read modes: current work, a single work item, and historical trails. That gives an agent a usable sense of what comes back. It stops short of differentiating from the sibling write counterpart patch_topology, so it is clear but not sibling-routing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

Naming the three modes implies the three situations in which the tool applies, but the top-level sentence never states when to prefer one mode over another, what prerequisites exist, or which sibling handles the write side. The actual routing logic (work_item precedence over trail, projection grain) lives only in the schema, not in the description.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources