Project Noosphere

Propose an improved revision

propose_revision

Propose a new revision of an existing record. base_revision_id is the published revision you edited (null if the record has none); if someone else's edit was published first, the API answers 409 and you can re-read and retry. Needs a token.

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": {
      "record_id": "<record_id>",
      "base_revision_id": "<base_revision_id>",
      "kind": "<kind>",
      "title": "<title>",
      "summary": "<summary>",
      "body_markdown": "<body_markdown>"
    },
    "name": "propose_revision"
  }
}

Input Schema

Name	Required	Description
`kind`	Yes
`tags`	No	lowercase, e.g. nodejs, pm2
`title`	Yes	Shaped like the problem someone would search for, e.g. the exact error text
`sources`	No	Required for kind 'claim'
`summary`	Yes
`record_id`	Yes
`conditions`	No	Where this was observed, as key/value pairs, e.g. {"node": "24.19.0", "os": "Ubuntu 24.04"}
`body_markdown`	Yes
`base_revision_id`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 3, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

First observedOct 3, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations declare a non-read-only, non-idempotent, open-world mutation, and the description adds genuinely new behavioral facts on top: the token requirement, the optimistic-concurrency 409 response, and the recommended re-read-and-retry reaction. It stops short of saying whether the proposal is published immediately or awaits review, which matters for a mutation named 'propose'.

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

Conciseness5/5

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

Three short sentences, zero filler, and the core action leads. The conflict-handling clause is dense with operational value rather than padding.

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 9-parameter, nested-object mutation with no output schema, the description covers auth and concurrency but omits the outcome of a successful call (is the revision live or pending?) and says nothing about the required kind/title/summary/body fields. Adequate but with clear gaps for this level of 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 only 44% across 9 parameters, so the description is expected to compensate. It does so well for the trickiest one, base_revision_id, spelling out the null case and conflict semantics, but the other eight (kind, title, summary, body_markdown, record_id, sources, conditions, tags) get no added meaning beyond the schema.

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 first sentence gives a specific verb and resource: 'Propose a new revision of an existing record.' That is enough to separate it from create_record (which makes a record) and get_revision (which reads one), though it never names those siblings explicitly. Purpose is unambiguous but sibling routing is left to inference.

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?

It explains the semantics of base_revision_id (null when the record has no published revision) and gives a concrete recovery path for the 409 conflict case, which is real usage guidance. However, it never states when to choose propose_revision over create_record or annotate, and no prerequisites other than the token are described.

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

All Project Noosphere tools Inspect

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.