Skip to main content
Glama
Sign In

Archipelago

by io.github.AlexReiner98
OverviewDiscussionsAdmin

change

Destructive

The only way to change the map: a list of ops with a reason. A create’s ref lets later ops link to it, and a title or note in the same change names what it makes as {ref}. Give the source the facts came from. To add to a note or change a passage, send append or replace, not the whole body. An update of only the id says it is still true. A plan or findings are items with a view, not one note. A published finding (type finding) is one line: its title the claim as a sentence, value the fact with its unit, confidence, as_of; its note how it was found, three lines at most. Checked as a whole, then applied or held as a proposal for a human, by policy. A refused change is kept for a few minutes under a name the refusal gives: send retry and fixes (the ops that were wrong, by number), not all of it again. Closing a decision or hypothesis is held for the human, unless the workspace applies agents’ changes: then a decision must carry props.outcome and props.rationale, and is put to the owner later (attention, to_confirm). Each op is { op, ...its fields }: create (ref?, type, title, body?, status?, owner?, visibility?, confidence?, props?, source?); update (id, title?, body?, append?, replace?, status?, owner?, visibility?, confidence?, props?); link (type, from, to, props?, confidence?, source?); unlink (relation); archive (id); forget (id, reasons?); restore (id); merge (keep, drop); define_type (type). query actions with action change says each field.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "change"
  }
}

Input Schema

NameRequiredDescriptionDefault
opsNoWhat to change. Needed, except with retry.
runNoThe run id from session_start, or the session id.
holdNotrue to wait for the human even where agents’ changes apply as made.
actorNoWho you are, for the log.
fixesNoWith retry: the ops that replace those that were wrong.
retryNoThe name the refusal gave. Send only retry and fixes.
reasonNoWhy, as the activity log shows it. Needed, except with retry.
sourceNoWhere these facts came from.
drawingNoSent by the page alone.
authorityNoOn whose authority. Left out, your own judgment; settling a decision or hypothesis needs it said.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already flag destructive=true and non-read-only, so the safety profile is covered; the description adds genuinely non-obvious behavior: refused changes are held 'for a few minutes' under a retry name, some ops are 'held as a proposal for a human, by policy', closing decisions/hypotheses is held unless the workspace applies agent changes, and authority must be declared when settling. It does not explain what forget/archive/merge actually destroy or whether they are reversible, which is the one gap the annotations can't cover.

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?

Purpose is front-loaded, but the body is a dense run-on with no line breaks, mixing retry protocol, policy rules, and a full op grammar in one block. Almost every sentence carries information, yet the packed clauses ('A plan or findings are items with a view, not one note') force re-reading. Structuring the op list and the retry/hold rules as separate segments would cost nothing and gain much.

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 a 10-parameter, nested, destructive tool with no output schema, the description covers the hard parts: op grammar, ref chaining, retry/fixes flow, hold semantics, and authority requirements. Remaining gaps are the return shape (nothing says what a successful change yields, e.g. assigned ids) and partial-failure/ordering behavior. `drawing` is left to the schema's own note.

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

Parameters5/5

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

The schema types `ops` only as an array of free-form objects with no op-level fields, so the description is the sole source of op structure and it delivers it field-by-field for all nine op types. It also adds semantics beyond structure — 'a create's ref lets later ops link to it', 'a title or note ... names what it makes as {ref}', authority defaulting to your own judgment — and covers retry/fixes/reason beyond the schema's own text.

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 opening sentence names a specific verb and resource ('The only way to change the map') and enumerates the mutation ops (create, update, link, unlink, archive, forget, restore, merge, define_type), so the agent knows this is the batch-write path. The closing line routes reads to the sibling query tool ('query actions with action change says each field'). It falls short of 5 only because 'the map' and 'items with a view' are undefined in-house jargon that a fresh agent must infer.

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 concrete when-to guidance for several recurring cases: 'send append or replace, not the whole body', 'An update of only the id says it is still true', 'send retry and fixes ... not all of it again', and the policy branch for closing a decision or hypothesis. The alternative for reading is named (query). What's missing is a clean statement of when to prefer capture/revise/settle over change for the same intent.

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

All Archipelago toolsInspect
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.

Resources