Skip to main content
Glama

read_blackboard

Read-onlyIdempotent

Retrieve shared blackboard data for a heads-down run to inspect what tasks, teams, and agents are doing; query sections or filters for status, decisions, claims, files, and events.

Instructions

Read the shared blackboard of this heads-down run: what every task, team and agent is doing. section: summary (default), goal, contract, tasks, task (task_id, default yours), interfaces, decisions, leases, claims, files, diffs, checks, escalations, notes, inbox, budget, agents, teams, events (filters: since_seq, limit, task_id, query = event type prefix), blob (ref: a sha256:… ref from an event; redacted, at most 16 KB), or query: fuzzy matching over tasks, teams, paths and interfaces ("is the nav done?").

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "execution_id": "<execution_id>",
      "agent_token": "<agent_token>"
    },
    "name": "read_blackboard"
  }
}

Input Schema

NameRequiredDescriptionDefault
refNoBlob ref for section blob.
limitNoDefault 50.
queryNoFree text for section query or tasks/files filters; an event type prefix for events.
sectionNoDefault summary (query when only query is given, blob when only ref is).
task_idNoA task (task, checks, diffs, escalations and events filter on it).
since_seqNoevents and notes: only after this seq.
agent_tokenYesThe agent token join_execution returned (once).
execution_idYesThe heads-down run (exe-…).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.0.0

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real operational facts the annotations do not: blobs are redacted and capped at 16 KB, events support since_seq/limit/task_id/query filters, and query is fuzzy. It omits that agent_token is a required credential returned once by join_execution, but the schema carries that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded correctly, but the single run-on sentence stacks all 21 section names into comma soup, making it hard to scan. Much of that enumeration merely repeats the schema enum, and only the parentheticals for task, events, blob and query carry new information.

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?

For an 8-parameter tool with 21 heterogeneous sections and no output schema, the description covers selection, defaults, filters and the blob size/redaction cap adequately; the section names are largely self-describing. What it does not convey is the return shape per section, which leaves some ambiguity, but not enough to cause a mis-call.

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?

With 100% schema coverage the baseline is 3, but the description adds cross-parameter meaning the schema cannot express: the default section is derived from which other parameters are supplied (query-only → query, ref-only → blob), task_id defaults to the caller's own task, and query is repurposed as an event-type prefix under events. The bare section-name list otherwise duplicates the enum.

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?

"Read the shared blackboard of this heads-down run" gives a specific verb and resource, and the enumeration of 21 sections makes the scope concrete. It stops short of naming any sibling (e.g. execution_status or get_collaboration_transcript) as the alternative for execution-level status, so differentiation is inferred rather than stated.

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?

Usage is implied by the framing "what every task, team and agent is doing" and by the documented defaults (summary by default, query when only query is given, blob when only ref is). There is no explicit when-not-to-use statement and no named alternative, so an agent must guess when to prefer another read tool.

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