Skip to main content
Glama

Read a space

read_space
Read-onlyIdempotent

Retrieve a study space’s status summary, topic facts, deadlines, lessons, and prep details, or list all files when needed to inspect progress and plan next study actions.

Instructions

Read one space: its description, how many files are in each status (pending, extracting, ready, failed, needs-whisper) and the files that could not be read, the topics of its knowledge graph with their fact counts, its deadlines (kind, date, time, done, and the files each covers), its lessons, and today's local date and time. A prep (a space made to get ready for one interview, assessment or test) also has its prep sheet: what the learner is preparing for, its day, what it is like, the topics with their ids and how each is going, what a mock is and the mocks taken. With files: true it lists every file instead (id, kind, status, size, path on disk). To find something inside the files, use search_space_files.

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": {
      "space_id": "<space_id>"
    },
    "name": "read_space"
  }
}

Input Schema

NameRequiredDescriptionDefault
filesNoList every file with its id (needed for file_ids). Default false.
space_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.6.1

TDQS

A4/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real value by detailing the returned payload, especially that 'files: true' swaps the summary for a raw file list (id, kind, status, size, path) — meaningful because there is no output schema. It omits error behavior for an unknown space_id and any permission requirements, which keeps it from a 5.

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 first sentence front-loads the verb, but it is a very long enumerated clause with nested parentheticals (deadline fields, prep sheet contents) that is hard to scan when deciding whether this is the right tool. Every element is plausibly relevant, yet the dense packaging costs clarity compared with a short summary followed by a mode list.

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?

With no output schema, the description carries the burden of describing returns and does so thoroughly for both the summary mode and the file-listing mode, including the prep-only fields. The remaining gaps — failure behavior for missing spaces and permission prerequisites — are minor for a read-only tool.

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 coverage is 50%: 'files' is documented in the schema, but 'space_id' has no description at all. The description compensates for 'files' by explaining its effect and that ids are needed for file_ids, and implies space_id selects the single space, but adds no format detail for space_id. Adequate but not full compensation for the coverage gap.

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?

Opens with a specific verb+resource ('Read one space') and then enumerates exactly what comes back: status counts, unreadable files, knowledge-graph topics with fact counts, deadlines, lessons, local date/time, prep sheet, plus the alternate file-listing mode. It explicitly separates itself from search_space_files, so an agent can choose between the two without opening a schema.

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?

Gives a concrete routing rule: 'To find something inside the files, use search_space_files', and explains the one alternate mode ('With files: true it lists every file instead'). It does not cover when to prefer list_spaces or update_space, but the primary alternative for content lookup is named with its condition.

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