This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
A living map of all your work. From a chat to a structured model that keeps you, your team, and your agents on the same page.
Early: built and used daily by its author; expect rough edges.
AI is speeding up lots of tasks, but more speed is only helpful if you're moving in the right direction. Making a map before you execute helps identify risks and dependencies, and makes it easy to keep track as people and agents work.
One shared map means anyone can pick up the work at any time, from anywhere. Detailed history makes it possible to analyze how projects actually developed, what was missed, and how to improve.
The site is archipelago.tools.
Archipelago is a small unopinionated core, the rest is yours to shape.
People stay in control. Agents do much of the work, and you decide what needs your approval. Every change records the source of authority, and what is applied can be undone. You stay in charge
The log is the truth. Every change is added to one log and never rewritten. Undo, history, live updates and backups all read the same record. docs/log.md
Everything is an item, every item has a type. Every type extends one of seven kinds. Because Archipelago is built around those kinds, what works on the types we ship works just as well on a type you add.
Plugin architecture. Packs are where opinion enters the system. Create a pack with the item types, link types, view styles, and features you need. A type, view or rule of yours works like the ones that ship. Write a pack
One surface for people and agents. You and your agents use the map through the same tools. What an agent is told is kept on the map, where you can read and change it. The agent tools
One way to read. A query is a filter, a walk and a limit, and a view is a query with its layout. You and your agents read the same query.
Related MCP server: Plate MCP
Archipelago is one Node 24 server and a persistent disk, MIT licensed, with everything included. The database is embedded; for a team, keep the maps on a Postgres server instead. If you'd rather not run a server, the Quickstart has it running for you in about five minutes.
git clone https://github.com/AlexReiner98/archipelago.git
cd archipelago
npm install
npm startOpen http://127.0.0.1:3100, go to Workspace and type your name under
Owner. To look around first, npm run demo opens a map of Archipelago itself
on port 3200, its data kept apart.
In the folder of a project you work on, with the server running:
node -e "fetch('http://127.0.0.1:3100/connect/setup.mjs').then(r=>r.text()).then(t=>import('data:text/javascript,'+encodeURIComponent(t)))"It lists the files it will write (.mcp.json, a few hooks, working rules in
CLAUDE.md) and asks first. Add -- --dry-run to only see the list, or
-- --remove to take it out. Then reopen Claude Code in that folder and say:
Put this project in Archipelago, with the three things I am working on as tasks, and tell me what you would do first.
Your tasks appear on the map right away. To take anything back, open
Changes and choose Undo. Any other MCP client works the map at
http://127.0.0.1:3100/mcp.
Host it yourself and Hosting: every setting and limit.
Reference: every screen, tool, view, setting and limit.
Agents held to the map: how an agent is told, checked and reconciled.
Packs: the manifest, key by key, and docs/layouts.md: layouts and the sandbox.
The log: what is stored, and how everything else is read from it.
Glossary: the one word for each idea.
CONTRIBUTING.md to work on Archipelago itself. It is published as it is, with no promise of answers or fixes.
SECURITY.md to report a security problem in private.
Copyright 2026 Aperture Design Tools Inc. MIT License.
Put a question to someone and wait for the answer. Call with the action and its params. Its actions: notify (title, body?, level?, about?); publish_ask (within, reason?). query actions says what each does.
| Name | Required | Description | Default |
|---|---|---|---|
| actor | No | Who you are, for the log. | |
| action | No | ||
| params | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare openWorldHint=false and destructiveHint=false; the description adds that the call waits for an answer, a useful blocking trait. It does not disclose permissions, side effects of notify/publish_ask, or return behavior, but with annotations the bar is lower.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core behavior and action list. The final clause defers to query actions, which is slightly wasteful but not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nested-params tool with no output schema and minimal annotations, the description is incomplete: it omits actor semantics, action selection details, and what the wait returns. It gives enough to start but not enough to invoke confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 33% and action/params have no schema descriptions; the description partially compensates by naming actions and their params (title, body?, level?, about?; within, reason?). It leaves actor undocumented in the description and does not explain the nested params object or required fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Put a question to someone and wait for the answer' and names two actions, but the inclusion of notify and the deferral to query actions makes the core purpose ambiguous. An agent cannot fully tell what ask does versus query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Lists action names but gives no when-to-use/when-not guidance or alternatives among siblings. 'query actions says what each does' pushes discovery elsewhere.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Give work to someone, inside the map or outside it: an owner, a person waited on, a party asked to act. Call with the action and its params. Its actions: claim (resource, holder, for?, reason). query actions says what each does.
| Name | Required | Description | Default |
|---|---|---|---|
| actor | No | Who you are, for the log. | |
| action | No | ||
| params | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare openWorldHint=false and destructiveHint=false; there is no readOnlyHint. The description does not disclose whether assignment mutates state, what side effects 'claim' has, or what permissions are needed, so behavior beyond the annotations remains opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences are front-loaded with the core idea, but phrases like 'inside the map or outside it' and 'a person waited on' are cryptic and do not earn their place. The action-specific detail is useful but only partially delivered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a polymorphic dispatcher with nested params, no output schema, and no readOnlyHint. The description names only one action and defers the rest to 'query actions', leaving the full action list, side effects, and return behavior insufficiently covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%), so the description must compensate. It does partially by naming one action's expected params ('claim (resource, holder, for?, reason)'), but it leaves the 'action' parameter values and most nested params unexplained, relying on a separate 'query actions' call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a recognizable verb and resource ('Give work to someone') and hints at assignable roles (owner, person waited on, party asked to act). However, the scope is abstract ('inside the map or outside it') and it does not clearly distinguish assign from siblings like change, settle, or revise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It says to 'Call with the action and its params' and points to 'query actions' for details, which is a partial usage hint. But it never says when to use assign versus the many sibling tools, nor does it set prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put something on the map: an item and its links, or a record of what happened. Call with the action and its params. Its actions: session_start (title?, task?, surface?, cwd?, remote?, session_id?, branch?, source?); picture_put (result, data, content_type); backup (none); import_audit (connection). query actions says what each does.
| Name | Required | Description | Default |
|---|---|---|---|
| actor | No | Who you are, for the log. | |
| action | No | ||
| params | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish destructiveHint=false and openWorldHint=false, but there is no readOnlyHint and the tool appears to write or record data. The description does not disclose side effects, persistence, permissions, reversibility, or what backup/import_audit actually do beyond listing their parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the general purpose before listing actions. The dense action list is useful, though the final pointer to 'query actions' is awkwardly phrased and slightly disrupts readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a multiplexed action tool with nested params, low schema coverage, and no output schema. The description lists actions and params but omits return behavior, side effects, and enough action semantics to make the tool fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, so the description carries extra burden. It does add meaningful detail by enumerating action values and their nested params, but it does not explain the actor parameter, action typing, or the semantics of params such as result, data, content_type, and connection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description says to 'Put something on the map' and lists actions such as session_start, picture_put, backup, and import_audit. This gives a general sense of capture-like behavior, but the metaphor and the heterogeneous action list leave the core purpose vague and do not clearly distinguish it from siblings like report or change.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It says to 'Call with the action and its params' and lists action names, plus points to query for action details. However, it gives no explicit when-to-use guidance, no exclusions, and no criteria for choosing capture over sibling tools such as query, report, or change.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 with only the id says you checked the item and it is still true. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| ops | No | What to change. Needed, except with retry. | |
| run | No | The run id from session_start, or the session id. | |
| hold | No | true to wait for the human even where agents’ changes apply as made. | |
| actor | No | Who you are, for the log. | |
| fixes | No | With retry: the ops that replace those that were wrong. | |
| retry | No | The name the refusal gave. Send only retry and fixes. | |
| reason | No | Why, as the activity log shows it. Needed, except with retry. | |
| source | No | Where these facts came from. | |
| drawing | No | Sent by the page alone. | |
| authority | No | On whose authority. Left out, your own judgment; settling a decision or hypothesis needs it said. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Well beyond the annotations, it discloses the actual lifecycle: ops are checked as a whole then applied or held as a proposal for a human by policy; refusals are retained only a few minutes under a specific name and must be replayed via retry+fixes; archive/forget/merge are destructive and closing a decision or hypothesis is held for the human unless the workspace auto-applies agent changes. The destructiveHint=true annotation is consistent with the destructive ops enumerated (archive, forget, merge), so there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the single most important sentence, and nearly every clause carries operational weight — the op enumeration is unavoidable because the schema does not type the op objects. Some sentences are compressed to the point of near-opacity ('Checked as a whole, then applied or held as a proposal for a human, by policy'; 'query actions with action change says each field'), which costs readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter mutation tool with nested, untyped op objects and no output schema, the description covers the gaps that matter: the op vocabulary, the ref-linking rule, the hold/proposal policy, the refusal-and-retry loop, and the decision-closing authority requirement. What an agent needs in order to construct a valid call is present; only the success response shape is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is nominally 100%, the ops item is an untyped bag (additionalProperties: {}), so the description does the real work by spelling out the full op grammar — create/update/link/unlink/archive/forget/restore/merge/define_type and their individual fields. It also gives semantic content the schema lacks: what a create's ref is for and how a title/note names it, that fixes are addressed by op number with a 1-based 'at', and that update with only an id asserts the item was checked and is still true.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a concrete statement of the operation and its scope: 'The only way to change the map: a list of ops with a reason,' which also implicitly claims exclusivity versus the mutation-adjacent siblings (revise, settle, undo). The 'map' metaphor and the dense follow-on prose (refusals, holds, op grammar) make the core purpose slightly harder to extract than it needs to be.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Several explicit routing rules are given: use append/replace instead of resending the whole body; use retry+fixes rather than re-sending all ops after a refusal; and only send props.outcome/props.rationale when closing a decision in an agent-applying workspace. It does not, however, say when to reach for this tool rather than the sibling tools revise, settle, or undo, which an agent composing a workflow still has to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Draw a view in this chat, for the person reading it, in a client that draws MCP Apps (Claude chat). Elsewhere nothing is drawn: report show opens it on their canvas, query look gives you the picture.
| Name | Required | Description | Default |
|---|---|---|---|
| actor | No | Who you are, for the log. | |
| query | No | A query, as query flat takes it. | |
| style | No | How it is drawn, as query look takes it: { layout, lit, id }. | |
| entity | No | A view kept on the map (type lens), or any item. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it a safe read (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description adds genuinely non-obvious behavior: the effect is client-dependent and is a silent no-op outside MCP Apps clients. It does not say what, if anything, is returned to the caller.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, purpose front-loaded, alternatives second. No wasted words, though the dense sibling shorthand ('report show', 'query look') trades clarity for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the essential decision points for a 4-optional-param, no-output-schema tool: when to use it, when not to, and what substitutes. It stops short of explaining what a 'view' or 'the map'/'type lens' entity is, leaving some conceptual gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter is described in the schema, including the nested style shape { layout, lit, id }, so the baseline is 3. The description adds no parameter guidance of its own and only cross-references sibling tools ('as query flat takes it').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Draw a view in this chat') plus the audience ('for the person reading it') and the platform precondition (an MCP Apps client such as Claude chat). The term 'view' is undefined jargon, but the platform constraint and the contrast with siblings make the intent legible.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly covers the when-not case ('Elsewhere nothing is drawn') and names the concrete alternatives with their differing behavior: 'report show opens it on their canvas, query look gives you the picture.' An agent can pick the right tool without opening any schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the map: every read is one call, query with the name of what to read and its params. With no name, every name with what it answers. actions says what one takes, whole: params read (a read or view, such as flat), action (or change, for its ops) or verb. An agent is given each answer without its empty fields and with long lists cut to what is read (params.full: true for all of it). The reads and their params: schema (type?, full?); search (q?, type?, status?, owner?, open?, include_archived?, limit?, full?); get (id, history?, full?); events (since?, target?, actor?, by?, before?, origin?, limit?, full?); proposals (status?, full?); picture (result?, look?); watch (after?, wait_seconds?); packs (none); acts (none); document (id, drawn?); publish_plan (within); published (id); share_figure (via, id); backup_download (none); places (canvas?); look (entity?, query?, lens?, style?, width?, height?, scheme?, fresh?, marks?); seeing (run?). Every other name is a view: flat, changed_since, spent, usage, notifications, sessions, saved_views, style, instructions, story, attention, graph, tree, hubs, brief. flat is the query: filter { find, only, not }, walk { over, steps }, limit.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | What to read: a read, a view or a lens. Left out, the list of them. | |
| actor | No | Who you are, for the log. | |
| params | No | Its inputs, as the list names them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds useful behavioral detail: answers omit empty fields, long lists are truncated unless params.full is true, and actor is used for the log. It could say more about errors or limits, but it adds meaningful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is information-dense and generally front-loads the purpose, but it is written as a sprawling run-on with cryptic phrases like 'whole: params read' and 'actions says what one takes.' The content largely earns its place, but the structure makes it harder to parse than necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a broad generic read dispatcher with no output schema, the description is fairly complete: it covers valid names, per-read params, discovery behavior, and result trimming. It still lacks explicit output-shape summaries for individual reads and clear usage exclusions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% descriptive coverage, but the description goes far beyond it by enumerating valid names, distinguishing reads from views, and listing the accepted params for each read. This is exactly the semantic detail an agent needs to construct a valid call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
It states a clear core purpose: query with the name of what to read and its params, and with no name return the available names. The 'read the map' framing is unusual, but the enumerated reads/views make it distinguishable from mutation-oriented siblings such as change or draw.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies that this is the entry point for reads and explains discovery via an omitted name or the actions view. However, it does not explicitly say when to prefer this tool over sibling tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Say that something happened or is so: progress, a result, a payment received, a check that it is still true. Also answers the owner with a view: show, with a kept view or an ad-hoc lens and style. Call with the action and its params. Its actions: session_update (run, status?, note?, task?, branch?, title?); session_end (run, outcome?, reason?, summary?, still_true?, cannot_tell?, cannot_tell_rest?); tell (run, said, about?, links?, replaces?, finding?); run_report (repo, title, ok?, tokens?, cost_usd?, turns?, link?, summary?, surface?); rechecked (repo, summary?); show (entity?, query?, lens?, style?, screen?, note?, look?, width?, height?, scheme?, pane?, run?); check_connections (none); health (heartbeat?, monitor?, msg?, live?, idle?, said?). query actions says what each does.
| Name | Required | Description | Default |
|---|---|---|---|
| actor | No | Who you are, for the log. | |
| action | No | ||
| params | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=false and openWorldHint=false, so the safety profile is partly covered. The description adds nothing about what session_end or health actually do, whether ending a session is reversible, or what any action returns, which is a meaningful gap for a tool whose actions span reads and lifecycle changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The first two sentences are rambling and abstract while the actual useful information is crushed into a single dense parenthetical list. It is information-dense but poorly front-loaded, and the cryptic prose does not earn its space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Eight distinct actions, a free-form nested `params` object, no output schema, and low schema coverage demand far more explanation than provided. No return values, no per-action meaning, and no guidance on the nested params structure are given.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% and the critical `action` parameter has no description or enum. The description does compensate somewhat by enumerating valid action values and their per-action params, but those names (said, about, replaces, lens, pane, look) are never defined, leaving real ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening prose is cryptic ("Say that something happened or is so") but the enumerated action list (session_update, session_end, tell, run_report, rechecked, show, check_connections, health) does reveal that this is a multi-action reporting/dispatch tool. It never distinguishes itself from close siblings like query, ask, or capture, so an agent cannot tell why it should pick report over those.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use, when-not-to-use, or alternative routing guidance; the only instruction is the tautological "Call with the action and its params." The pointer "query actions says what each does" offloads the semantics to a sibling tool rather than explaining them here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change, correct or undo what is on the map. Call with the action and its params. Its actions: release (resource, holder?, reason); places_put (canvas?, moves?, clear?); publish (id, authority?); publish_all (within, authority?); undo (changeset). query actions says what each does.
| Name | Required | Description | Default |
|---|---|---|---|
| actor | No | Who you are, for the log. | |
| action | No | ||
| params | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and openWorldHint=false, so the safety profile is covered structurally. The description adds an action inventory but says nothing about what destruction actually occurs, whether 'undo' or 'clear' are reversible, what permissions are needed, or what 'release' does — the very context a destructive dispatcher needs beyond the hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense and front-loaded: purpose first, then calling convention, then the action signatures. Nothing is padded, though the final sentence 'query actions says what each does' is a vague deferral that earns its place only weakly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive multi-action dispatcher with a free-form nested 'params' object, no output schema, and no enums, the definition is thin: action semantics are entirely deferred to a separate 'query' call and there is no statement of effects, reversibility, or return shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 33% schema coverage (only 'actor' is documented) the description must compensate, and it partially does by listing the per-action param keys inside the otherwise opaque 'params' object (e.g. release: resource, holder?, reason). However, it never explains what any of those keys mean, and the 'action' string has no enum in the schema, so the listed values are the only enumeration available.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb ('change, correct or undo') is clear, but the resource is vague ('what is on the map'), and the framing directly overlaps with sibling tools literally named 'change' and 'undo' without distinguishing itself from them. The inline enumeration of action values (release, places_put, publish, publish_all, undo) is the only thing that makes the tool's actual scope legible.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use 'revise' versus the sibling tools 'change', 'undo', or 'draw', which appear to overlap. The single directive 'query actions says what each does' offloads the entire selection decision to another tool call rather than stating any conditions here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close a question by someone's word or by evidence: a decision made, a hypothesis borne out. Call with the action and its params. Its actions: confirmed (upto, basis). query actions says what each does.
| Name | Required | Description | Default |
|---|---|---|---|
| actor | No | Who you are, for the log. | |
| action | No | ||
| params | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare openWorldHint=false and destructiveHint=false, but the description adds nothing about side effects: whether settling is reversible, what happens to the question afterward, whether an actor identity/authorization is required, or whether it is idempotent. For a mutation-shaped tool that "closes" something, that silence is a real gap; the "by someone's word or by evidence" clause is conceptual framing, not behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short and the core instruction sits early, but two of the four sentences are spent on metaphor and on deferring to the `query` sibling, while the actionable noun list ("confirmed (upto, basis)") is compressed into a fragment that takes rereading to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a nested `params` object, an untyped `action` string with no enum, no output schema, and zero required parameters, the description needed to carry substantial weight. Instead it documents exactly one action and tells the agent to go ask another tool for the rest, leaving the agent unable to invoke `settle` correctly from this definition alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only `actor` is documented), but the description does compensate partially by naming the action value "confirmed" and its params "upto, basis" — information absent from the schema. However, it leaves the meaning of `upto` and `basis` unexplained and does not indicate whether other actions exist or how `params` is keyed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gestures at a verb+resource ("Close a question") and names a single action, "confirmed", but the framing is metaphorical ("by someone's word or by evidence: a decision made, a hypothesis borne out") rather than operational. It never says concretely what object is being closed or what state change results, and offers no differentiation from siblings like ask, revise, or report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use/when-not guidance relative to the nine sibling tools, several of which (ask, revise, report) plausibly overlap with closing a question. "Call with the action and its params" is an invocation mechanic, not a usage rule, and "query actions says what each does" offloads the routing decision to another tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reverse one change set (its id is on every event it logged) by applying the opposite as a new change: created items are archived, edits put back, links removed or restored. An edit changed again since is left alone and reported. Subject to the same policy as any change.
| Name | Required | Description | Default |
|---|---|---|---|
| actor | No | Who you are, for the log. | |
| changeset | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the annotations: it discloses that undo is additive (a new change is written), the per-item outcomes (created items archived, edits restored, links removed/restored), and the conflict policy of leaving recently re-edited items alone and reporting them. This matters because destructiveHint=true might otherwise read as a hard rollback; the description corrects that mental model rather than contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences: mechanism first, then per-type outcomes, then the conflict and policy caveat. No filler, and the crucial 'not a real rollback' framing is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with no output schema, the description covers what is applied, what happens per entity type, and conflict handling. It stops short of saying what the call returns (the new change set?) and what 'same policy' concretely gates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% and the required 'changeset' parameter has no schema description, but the description compensates by saying its id appears on every event it logged, telling the agent where to obtain the value. The optional 'actor' parameter's meaning is left entirely to the schema, which does cover it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (reverse) plus resource (one change set) and explains the mechanism: the opposite is applied as a new change rather than a true rollback. It is distinguishable from siblings like change/revise, though it never names which sibling to prefer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicit when-to-use: pick this to reverse a prior change set, and the note that an edit changed again since is skipped and reported clarifies an edge condition. There is no explicit routing against alternatives such as revise or change, and 'Subject to the same policy as any change' gestures at a precondition without stating it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
askassigncapturechangedrawqueryreportrevisesettleundoScored across 10 tools
Several tools appear to do the same thing: change claims to be the only way to modify the map, while revise also says it can change/correct/undo the map, and undo duplicates revise's undo action. query, report show, and draw all overlap around reading/rendering views, while capture, change, and report overlap around recording events or map state. Agents will struggle to choose correctly without trial and error.
All tool names are lowercase single imperative verbs, so the naming style is consistent and readable. The main weakness is that several are broad meta-verbs (query, change, revise) rather than predictable verb_noun names, making their semantics less obvious despite consistent formatting.
Ten top-level tools is a reasonable count on the surface, but each tool is actually a mega-dispatcher bundling many actions, so the effective tool surface is much larger and poorly scoped. The count hides substantial complexity rather than reflecting a clean, well-bounded set.
The surface broadly covers the apparent domain: reading/searching the map, creating/updating/linking/archiving/restoring items, sessions, reporting, publishing, proposals, backups, and drawing. Some lifecycle edges are unclear or buried in dispatcher actions, but there are no obvious severe gaps for the stated scope.
Project management for AI agents: tasks, docs, decisions and time in one shared team context.
Track issues, projects and dependencies with your agent in a workspace you control.
Fluid cowork platform. Synthesizes work data across boundaries, with project tracking built in.
AI-native project management for tasks, docs, collaboration, and agents.
