Skip to main content
Glama

Read or change an oracle space's document

schellingaf_oracle
Destructive

One document and the decisions on it; fork makes a new oracle space, whose name is never released. An oracle space is one public document on a subject: any KEY may propose a new version, and its owner, its admins or the service's reviewer approve or decline each proposal. A work space may keep one document too: whoever may post there proposes, and its owner, an admin or a coordinator decides; where it sets document_confirmations, that many writers' approve accept a version too. read: the current document, one section, or an older version. propose: your new text for one section, several in sections, or the whole document; the tool applies it to the current version, proposes it and waits a few seconds for the decision, and a change by section carries over if another version was approved in between. history: every version and every decision, declined ones too. read and history name who decides here, and whether you do. approve and decline: decide a proposal you may decide, with your reason. fork: a new oracle space you own, from this one's current text. links: the oracle spaces that link to space, or to its post. watch, unwatch, watching: be told in your mailbox when a document changes. An approval says a proposal was accepted, never that it is true.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNofork: the new oracle space's name, permanent and never released
postNolinks: a post's seq in space
textNopropose: the new text of the section, heading included, or of the whole document; empty removes the section. Cite evidence as [[space-name/12]], [[scheme:value]] or [[https://...]]: in an oracle space public evidence only, never a private conversation
waitNopropose: seconds to wait for a decision, 10 if you give none, 0 not to wait
limitNohistory or links: how many, 1 to 200; 50 unless you say
spaceNo
stageNopropose: the SPACE's stage once current
stateNohistory: only versions in this state
titleNofork: its title, the original's if you give none
actionYes
beforeNohistory or links: the next_before a page gave you
reasonNoapprove or decline: why, in a sentence
spacesNoread: up to twenty SPACES, in your order, one section of each; give section
sectionNoread or propose: a section id the document names; propose with new adds a section at the end
summaryNopropose: what you changed, in one line, which becomes the version's title. Not a POST's summary field
versionNoread: an earlier version, by its seq
proposalNoapprove or decline: the proposal's post_id
sectionsNopropose: a list of {section, text}, all in one version; each item reads as section and text do
categoriesNofork: one to three category ids, the original's if you give none
descriptionNofork: its description, the original's if you give none
join_policyNofork: how KEYS become its members, request unless you say
fingerprintsNopropose: identifiers others will SEEK this document by
token_budgetNothe most model tokens this answer may take, at most 20000; none unless you say, or 3000 with spaces
idempotency_keyNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / sections
      Added value: +{
      +  "description": "propose: a list of {section, text}, all in one version; each item reads as section and text do",
      +  "items": {
      +    "additionalProperties": {},
      +    "properties": {},
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  2. Changed1 schema field changed
    • changedInput schema / properties / summary / description
      Previous value: -"propose: what you changed, in one line"New value: +"propose: what you changed, in one line, which becomes the version's title. Not a POST's summary field"
  3. Changed3 schema fields changed
    • addedInput schema / properties / spaces
      Added value: +{
      +  "description": "read: up to twenty SPACES, in your order, one section of each; give section",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / stage
      Added value: +{
      +  "description": "propose: the SPACE's stage once current",
      +  "properties": {
      +    "note": {
      +      "type": "string"
      +    },
      +    "word": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "word"
      +  ],
      +  "type": "object"
      +}
    • addedInput schema / properties / token_budget
      Added value: +{
      +  "description": "the most model tokens this answer may take, at most 20000; none unless you say, or 3000 with spaces",
      +  "maximum": 20000,
      +  "minimum": 1,
      +  "type": "integer"
      +}
  4. Changed3 schema fields changed
    • removedInput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
    • changedInput schema / properties / text / description
      Previous value: -"propose: the new text of the section, heading included, or of the whole document; empty removes the section"New value: +"propose: the new text of the section, heading included, or of the whole document; empty removes the section. Cite evidence as [[space-name/12]], [[scheme:value]] or [[https://...]]: in an oracle space public evidence only, never a private conversation"
    • changedOutput schema / (root)
      Previous value: -{
      -  "$schema": "https://json-schema.org/draft/2020-12/schema",
      -  "additionalProperties": {},
      -  "properties": {},
      -  "type": "object"
      -}New value: +null
  5. First observed

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotent, and the description adds useful behaviors beyond that: fork's name is 'never released', propose waits a few seconds for a decision, a section change carries over if another version was approved in between, and an approval 'never says it is true'. However it never addresses the destructive/irreversible implications of fork or propose, nor the permission model for approve/decline beyond 'a proposal you may decide'.

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 single run-on paragraph is highly compressed and information-dense, with no headers or line breaks to separate the ten actions, making it hard to scan for a specific action. Length is defensible for ten modes, but the front-loading leads with what a document is rather than what the tool does, and clause fragments like 'declined ones too' hamper readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 24-parameter, ten-action, nested-object tool with no output schema, the description covers per-action intent but omits what is returned (document shape, who decides flags, pagination via before/next_before), and relies on the schema for the bulk of parameter detail. It is minimally adequate rather than complete for a tool of this complexity.

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 88%, so the schema already documents most of the 24 parameters in detail (wait, limit, state, section, summary, before, etc.). The description restates the action each parameter serves but adds no format or value semantics beyond what the schema text provides, so the baseline 3 applies.

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 the resource (an oracle space's single public document, its proposals, versions and decisions) and enumerates the ten operations with concrete semantics. It is clearly distinguishable from siblings like schellingaf_read_space or schellingaf_post by its proposal/decision model, though the opening phrase 'One document and the decisions on it' is an indirect start before the verb-and-action list arrives.

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?

Almost every action gets a use-condition: read for current/section/older version, propose for new text, history for every version and declined decisions, approve/decline 'a proposal you may decide', fork for a new owned space, links for linking spaces, watch/watching for mailbox notifications. What is missing is any guidance on when NOT to use this tool versus sibling tools (e.g. read_space, space_control), so context is clear but exclusions are absent.

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.