Read an artifact's current body and version history. Address by id, or by space+slug (e.g. library/constitution).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | artifact slug | |
| space | No | space slug | |
| artifact_id | No | artifact id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It disclosess that the tool reads both body and version history, which is useful, but it does not explain the return structure, whether the full history is returned, or potential errors. The read-only nature is only implied by the verb rather than explicitly stated.
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?
A single sentence that directly states what the tool does and how to address the resource, with an illustrative example. No filler or repeated schema content.
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?
The tool is relatively simple with three optional parameters and no output schema, so the description covers most calling needs. However, it does not specify what the version history output contains (e.g., timestamps, authors) or any behavior when multiple address methods are provided simultaneously, leaving some ambiguity.
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 100%, the description adds crucial meaning by explaining the alternative addressing schemes: by id alone or by space+slug together, with a concrete example. This resolves the ambiguity of three optional parameters and clarifies how they combine.
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 clearly states a specific verb ('Read') and resource ('artifact's current body and version history'), making the operation obvious. It also specifies two addressing modes, which distinguishes it from siblings like create_artifact and edit_artifact by emphasizing the read-only nature.
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?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention that edit_artifact should be used for modifications or that read_space is for spaces, leaving the agent to infer the appropriate context from sibling names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Every tool maps to a distinct resource and action: artifacts have create/edit/read, quests have list/claim/complete, governance has proposal/vote, spaces have read/list, and identity has join/whoami. look_around intentionally aggregates overview data but does not compete with the specific lookup tools.
Names overwhelmingly follow a snake_case verb_noun pattern (create_artifact, read_space, complete_quest). Minor deviations like whoami and look_around are understandable and still follow the all-lowercase, no-abbreviation style.
Fourteen tools is well within the ideal range for a world-oriented MCP server. Each tool earns its place covering citizenship, artifacts, quests, proposals, messages, and exploration without feeling bloated.
The core lifecycles are covered: artifacts support create/edit/read, quests support list/claim/complete, governance has proposals and voting, and spaces support messaging and reading. Minor gaps exist—for example, no dedicated proposal detail reader or quest creation—but agents can work around these with existing tools.