Skip to main content
Glama
Sign In
Pachakutech

Pachakutech Presence

Official
by Pachakutech
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

Pachakutech Presence

A local agent is given one body on the compositor the person is already using, and six typed actions for marking that screen and speaking through the body. The package is the MCP binding, the presence CLI, and a Linux x86_64 daemon that owns Vulkan and Wayland. The account of what that daemon actually does is docs/situated-presence.md. Read it before the notes under docs/plans/.

Situated presence

What is running

  • A layer-shell disc, 220 pixels on a side, idle and with a presence. It takes no pointer input and reserves no layout space. A heat field over the captured screen chooses the seat. A visible mark is written into that field as hot.

  • A MakeHuman proxy, 181 joints, about 50,000 Gaussians, skinned and reconstructed on the GPU and checked against a CPU oracle at startup. The rig is not cut down to the 64-bone palette used for ordinary splat clouds.

  • Screen and webcam enter as dma-bufs when the device allows it. Body colour is sampled from those images. PRESENCE_APPEARANCE_BAKE=1 draws the joint palette instead, and is read only at process start.

  • The discs occlude one another. Depth is tested and written. The fragment outputs a covered sample at full alpha.

  • Speech is Piper and Rhubarb, on this machine. The jaw follows the audio. This export of the mesh has no viseme_* shape keys, and the log says so. The jaw still moves.

  • While she is speaking, a visible mark selects a frame of the Point clip by screen angle. Frames 1–180 are her left hand, which is the hand for a mark on the viewer's right. Frame 270 is her right hand. The camera is one half-turn about X, so the face comes forward and left stays on the viewer's right. She yaws up to a quarter turn toward the mark. With no mark, the arms go out to frame 20 and back, and the body yaws about two degrees.

Shader history is docs/gpu-splat-pipeline.md. The process split is docs/architecture.md. The reason the contract looks like this is docs/vision.md.

Related MCP server: mcp-interactive-ui-server

The blackboard

Each actor posts a frame-coherent message on its own channel when its work finishes. Inside a message, every value comes from that one pass. Where the message is a table, the columns are a structure of arrays and they share one length. A newer message replaces the previous one whole. A reader takes the latest complete message. The tick carries on while a writer is still working.

The split is the G-buffer idea, applied to compute state. A G-buffer keeps albedo, normal, and depth for one frame. Here a channel keeps the columns of one pass: the words on the glass, the heat cells, or the pose. The channels keep their own clocks. On this panel the screen-text pass takes about two and a half seconds, the capture clock is 100 ms, and the pose tick is 33 ms.

The CPU writes the buffer the next reader samples. For the body, that reader is the expand pass. One dispatch binds this tick's skin matrices and morph weights, with the mesh channels beside them, and writes one finished splat per sample. Locate reads the screen-text channel. Placement reads the heat. The voice posts when the line is ready, and the tick polls that message.

That is the blackboard, and the writers are asynchronous. The snapshot a reader binds is the latest coherent message on the channel it asked for.

The control surface

The pose is one channel of that blackboard. It is the record: breath, gesture, jaw, yaw, and the seat. Each tick the CPU sends that pose as 181 skin matrices and the morph weights. The device rebuilds the 50,000 samples on the deformed mesh and stores finished splats for the projection shader to draw. The buffers, the push constant, and the 96-byte record are in docs/control-surface.md.

Speaking and marking

The daemon copies its environment once, at start. The shell that runs presence daemon start has to export PRESENCE_PIPER_MODEL, PRESENCE_RHUBARB_BIN, WAYLAND_DISPLAY, and XDG_RUNTIME_DIR. Rhubarb's res/ directory sits beside the rhubarb binary. A variable exported after start does not reach the process, and speak still returns success.

presence daemon start
id=$(presence spawn)                 # stdout is only the id
presence highlight "$id" 0.53 0.46 0.12 0.12 45
presence speak "$id" "The sentence inside the mark."
presence retire "$id"

A phrase the user can already see is one command. It finds, checks the crop, tints, then speaks. If the phrase is missing it does neither.

presence highlight-and-speak "$id" --source web --query "fellow-mortal" \
  --text "The sentence inside the mark."
presence highlight-query "$id" --source pdf --uri ./notes.pdf --page 2 \
  --query "the clause in question"

highlight-and-speak defaults the tint to 90 seconds. Pass --seconds to override. The ceiling is 360. A reply that walks through more than one passage is annotated once. text is the spoken reply. --cues is a JSON list of {at, query} beside it. at names one sentence of that reply. query is the passage to find on the page, a phrase or start ... end. The runtime splits the reply, binds each cue to a sentence, and finds the first passage before any audio. Later passages move with the sentence clips. On the web the open tab's find brings the phrase into view. The browser's highlight is cleared before the photograph. One photograph is the box. When that photograph does not contain the phrase, the locator waits for the screen to settle and photographs once more. A second miss stands. A line sitting high or low moves eighty pixels and is photographed again. Our tint uses that box. A phrase the find does not see stops the search. A PDF is searched in its text layer, and Evince turns to that page. --page wins when the call names one. Evince's search highlight stays off. A terminal, an editor, and a document window are one read of the glass already up. The document reader does not send keys. The tint comes down while the page moves, and the new box goes up when the crop passes. A miss leaves the tint down. The voice continues, and the tint stays up until the voice ends. The safety cap is about as long as the words. During the quiet between clips the next passage is found. The binding rules are in Annotating the reply. highlight-query is the same find and tint with no speech. Stdout is one JSON object: the locate box, highlight.status, and, when it speaks, speak.status. --source is web, pdf, terminal, doc, or ide. On the web the browser's find moves the page. PDF takes a path, and the text layer names the page. Terminal, doc, and ide read a window already up and do not type into it. ide is the editor window (code, code-oss, cursor, zed, jetbrains); reveal the line first.

A terminal, a PDF, a document, and the editor read the daemon's latest screen-text message before the screenshot. The message is the columns of one capture (text, x, y, w, h, conf), kept for about eight seconds after it is posted. One hit in the chosen window is the measure, and the method is screen-text-memory. The crop is still read before a tint. A quiet message, two hits, or a failed crop uses the screenshot path. The web measure is the photograph after the browser's find, because that find has just moved the page. presence screen-text prints the message. It does not tint and it does not speak.

u, v, w, and h are fractions of the whole composited output, origin at the top left, v downward. A bare highlight lasts 5 seconds unless a duration is passed. The daemon clamps a duration to between 1 and 360. The arms move only while audio is playing and the tint is still up. After the tint fades, the presence keeps the rectangle and the stored rectangle does not hold the pose. speak returns when the line is accepted. A second speak replaces the line still playing. A daemon restart drops every live id. highlight-and-speak and highlight-query are the fused path. locate still returns the box alone.

The same proposals exist as MCP tools: spawnPresence, animatePresence, manifestHighlight, retirePresence, addArtifact, retireArtifact, locateScreenRegion (find a phrase, return UV, do not mark), highlightAndSpeak (find, tint, speak, one rate-limit tick), and manifestHighlightFromQuery (find and tint, no speech). A locate failure inside either fused tool does not tint and does not speak. Full schemas are in src/index.ts. Expected motion, the corner rule, and the camera are written out in docs/situated-presence.md. A one-page printing of the contract is docs/contract-onepager.html.

Tool

Pattern

Does

manifestHighlight

ephemeral

Tints a full-screen UV box. The tint fades. The box remains until replace or retire

locateScreenRegion

read

Finds a phrase and returns UV JSON. A single hit in the screen-text memory can supply the words. It does not mark or speak

highlightAndSpeak

fused

Speaks text. One passage passes query. Several passages pass cues, each naming a sentence of text and the words to find on the page. The first passage is tinted before any audio. Later ones move with the sentence clips and hold the tint for the utterance. One gate tick. A miss on the first passage does not tint or speak

manifestHighlightFromQuery

fused

Finds the phrase and tints it. No speech

spawnPresence

instanced

Returns a presenceId. The first live presence receives the body

animatePresence

instanced

Speaks text through that presence

retirePresence

instanced

Ends it and frees the slot

addArtifact

instanced

Holds a local .splat or .ply. The file is read by the daemon. The cloud is not the avatar

retireArtifact

instanced

Drops a held cloud

The MCP process applies a policy gate before the socket: 1.5 seconds between calls to the same tool, at most three presences, at most twenty artifacts. Retire is not rate-limited. A presence started from the CLI does not pass through that gate. The CLI and the MCP server write the same socket.

Install — Linux x86_64

npm install -g @pachakutech/presence-mcp
presence doctor
presence daemon start
presence setup claude

The package contains the Node binding, the CLI, a prebuilt presence-daemon, and skills/presence/SKILL.md. Install does not compile anything and does not start the daemon. presence setup claude runs claude mcp add presence -- presence mcp and copies the skill to ~/.claude/skills/presence. setup codex and setup grok do the same for those clients. The agent then launches presence mcp on stdio. That process talks to $XDG_RUNTIME_DIR/pachakutech/presence.sock.

The daemon runs in a logged-in desktop session, as that user, never as root. Stop it with presence daemon stop. presence daemon path prints the binary that start will launch. Its stdout and stderr go to $XDG_RUNTIME_DIR/pachakutech/presence-daemon.log.

The host session is not in the package:

  • Linux x86_64.

  • A Wayland session (WAYLAND_DISPLAY). Hyprland is the compositor this was built against.

  • A Vulkan loader and a vendor driver.

  • The DRM render node (/dev/dri/renderD128). logind grants this to the seat. Membership of the render group is the fallback.

  • /dev/video* when the webcam is wanted. On most distributions that is the video group. A missing webcam permission fails quietly.

On a machine with no Vulkan driver the daemon prints the error and exits. On a working desktop it names the GPU, reports whether dma-buf import is available, runs a one-splat smoke dispatch, and only then listens. A failed smoke dispatch is fatal.

If the daemon is down, the binding falls back to notify-send and appends to ~/.local/state/pachakutech-presence/log.jsonl.

There is no auto-update.

npm outdated -g --depth=0
npm update -g @pachakutech/presence-mcp
presence daemon restart
presence --version
presence daemon status

On Omarchy, docs/omarchy.md records an omarchy-mise-install line that has not been verified. The npm install above is the one that matches this tree.

Building from this repository

Rust and Cargo are required only for a daemon built here. Shader compile needs glslangValidator (glslang on Arch). Run time needs vulkan-icd-loader and a vendor driver.

git clone https://github.com/Pachakutech/pachakutech-situated-ai-presence-mcp.git
cd pachakutech-situated-ai-presence-mcp
npm install
npm run prepare:package   # tsc, cargo build --release, stage into native/linux-x64
npm link

presence daemon start runs native/linux-x64/presence-daemon. A binary left in daemon/target is not that file. scripts/stage-daemon.mjs copies the release build into place. The contributor recipe, including the speech variables, is docs/dev/debug_build.txt. The overlay and the ingress path are summarized in daemon/README.md.

prepare:package assembles the tarball. npm publish runs it from prepublishOnly. npm install does not.

Where the process sits

The MCP server is a child of the agent CLI, on stdio, on this machine. It inherits the desktop session, including WAYLAND_DISPLAY, XDG_RUNTIME_DIR, and DBUS_SESSION_BUS_ADDRESS. A systemd unit would have to be given that environment on purpose. This process does not.

The binding knows the schema. The daemon knows the device. They exchange one JSON object per line and no buffers. That boundary is described in docs/architecture.md.

MIT licensed. github.com/Pachakutech/pachakutech-situated-ai-presence-mcp.

Available Tools

6 tools
addArtifactAdd a reference artifactA

Instanced Manifestation, step 1 of 2 (add / retire). Adds a Gaussian splat artifact (or other content asset) to the substrate as reference material — it is held, not rendered. Use this to give spawnPresence something concrete to build from (e.g. 'this is what I want the presence to look like') rather than describing appearance in prose. Returns an artifactId.

NameRequiredDescriptionDefault
sourceUriNoWhere the content came from, if applicable
descriptionYesWhat this artifact is/depicts

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries the behavioral burden. It usefully discloses that the artifact is 'held, not rendered', returns an artifactId, and is part of a 2-step lifecycle. It does not mention persistence, ordering constraints, or permission requirements, but the core observable behavior is clearly communicated.

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

Conciseness4/5

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

The description is focused and each sentence earns its place, including the return value and the concrete example. It is slightly dense with the phrase 'Instanced Manifestation' and the parenthetical lifecycle note, but remains efficient and readable.

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 simple 2-parameter tool, the description is largely complete: it covers the resource, the behavior, the intended use case, and the return value. It leaves minor questions about sourceUri applicability and any side effects, but does enough for an agent to select and call it correctly.

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

Parameters4/5

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

Schema coverage is 100% for the two parameters, so the schema already explains sourceUri and description. The description adds value by showing the intended content of the description parameter: 'this is what I want the presence to look like'. It does not add anything specific about sourceUri.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise action: 'Adds a Gaussian splat artifact (or other content asset) to the substrate as reference material'. It also distinguishes this tool from siblings by explaining the artifact is 'held, not rendered', and positions it as step 1 in an add/retire lifecycle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance: 'Use this to give spawnPresence something concrete to build from' and contrasts with 'describing appearance in prose'. The add/retire pairing also implicitly names retireArtifact as the opposite operation.

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

animatePresenceDrive an existing presenceA

Instanced Manifestation, step 2 of 3. Feeds new content (e.g. words to say) to a presence created by spawnPresence.

NameRequiredDescriptionDefault
textYesWhat the presence should say or express next
presenceIdYes

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations, the description carries the burden. It states it 'feeds new content' and is 'step 2 of 3', which implies mutation but not the clarity of whether it modifies state irreversibly. It doesn't omit major behavioral aspects, but lacks details like whether it is asynchronous, or if it returns a confirmation. This is a neutral, not very rich disclosure.

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?

The description is one sentence, front-loaded with the purpose and step. It gives a concrete example of input ('words to say') without verbosity. Every word earns its place, and it is appropriately targeted for the agent.

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?

Given the 2-parameter schema and a clear lifecycle context, the description is fairly complete. It doesn't have an output schema, but for a feeding operation, an agent can infer it returns nothing. It lacks details on return value or behaviour on non-existent presenceId, but this is minor given the overall simplicity.

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 coverage is 50%: parameter 'text' has a description, but 'presenceId' does not. The description adds meaning by relating 'text' to 'words to say', which partly compensates for the schema gap; however, 'presenceId' remains semantically weak. Baseline is 3 since coverage is moderate.

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 clearly states the verb 'feeds' and the resource 'presence', and it identifies its place in a 3-step process. It differentiates from siblings by mentioning 'spawnPresence' and 'retirePresence', though it doesn't explicitly contrast with them. The title 'Drive an existing presence' also reinforces the action.

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 implies usage as step 2 of 3, after spawnPresence Illustrates when to use, but it doesn't provide explicit when-not-to-use or alternatives. The context is clear enough to understand the lifecycle, but there is no mention of conditions to avoid using or of the sibling 'manifestHighlight'.

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

manifestHighlightHighlight something on screenA

Ephemeral Manifestation. Draws a bounded, temporary highlight over the described on-screen content. Prefer this over describing a location in text when the user can see their screen.

NameRequiredDescriptionDefault
descriptionYesWhat to highlight, e.g. 'the red error banner'
durationSecondsNo

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations provided, the description must carry the behavioral burden. It discloses 'ephemeral' and 'temporary' to indicate the non-persistent nature of the highlight, but it does not explicitly state that the tool modifies no underlying state or that the highlight fades without side effects. This leaves some room for agent interpretation.

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?

The description consists of two concise sentences. The first imparts the core action and scope, and the second offers a practical usage tip. There is no fluff, and the information is front-loaded, making it easy for an agent to scan and apply.

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 simple drawing tool with no output schema, the description covers the core behavior and usage preference. It could mention the optional duration parameter or its bounds explicitly, but those are already in the input schema. The tool's behavior is sufficiently explained, though there is no clarification about its relationship to sibling manifestation tools, which slightly detracts from completeness.

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 50%; the description parameter is already well documented (with an example), and the tool description aligns with it ('described on-screen content'). However, the description says nothing specific about durationSeconds beyond the schema's default/range, so it does not add meaningful semantic value to that parameter. Since the coverage is exactly at the threshold, the description provides only marginal added insight.

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 clearly states it 'Draws a bounded, temporary highlight over the described on-screen content', identifying the specific action and target. However, it does not directly differentiate from sibling tools such as spawnPresence, so it falls short of full 5 for sibling awareness.

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?

The sentence 'Prefer this over describing a location in text when the user can see their screen' gives a clear context for when to use this tool. It does not mention alternatives like sibling manifestation tools, but the guidance is explicit about a common alternative.

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

retireArtifactRetire a reference artifactB

Instanced Manifestation, step 2 of 2. Removes a held artifact and frees its slot.

NameRequiredDescriptionDefault
artifactIdYes

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations provided, the description carries the burden of disclosing behavior. It clearly indicates a destructive operation ('Removes') and the slot-freeing effect, but it does not mention irreversibility, idempotency, error behavior, or any side effects beyond the slot release.

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

Conciseness4/5

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

The description is very concise and front-loaded with the key action. The phrase 'Instanced Manifestation, step 2 of 2' adds workflow context, though it is slightly cryptic. Overall, every word earns its place.

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 simple one-parameter operation, the description is adequate but has clear gaps: it does not describe what happens if the artifact is not held, whether the retire is reversible, what response to expect, or how this step connects to the full manifestation workflow.

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?

The schema contains only artifactId with no documentation, so the description partially compensates by clarifying that the removed entity is a 'held artifact.' This makes the artifactId's role inferable, but the description does not explicitly state that artifactId is the identifier of the artifact to retire or explain any format expectations.

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 clearly states the action ('Removes a held artifact') and the resource ('artifact'), with an additional consequence 'frees its slot.' The phrase 'step 2 of 2' provides context but does not clearly differentiate this tool from sibling tools like retirePresence.

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?

The description implies usage within a two-step workflow ('step 2 of 2'), suggesting it should follow a prior manifestation step. However, it does not explicitly state when to use this tool versus alternatives such as addArtifact or retirePresence, leaving the choice to inference.

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

retirePresenceEnd a presenceA

Instanced Manifestation, step 3 of 3. Cleanly ends a presence created by spawnPresence and frees its slot. Always call this when the presence is no longer needed — concurrent live presences are capped.

NameRequiredDescriptionDefault
presenceIdYes

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It discloses that the operation is 'clean' and frees a slot, implying it's not destructive in a harmful way but is a cleanup action. It does not mention any side effects like throwaway resources, idempotency, or failure behavior, so it's adequate but not rich.

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?

The description is two sentences with no filler. The first sentence is front-loaded with the verb and purpose, and the second provides the usage guidance. Every word earns its place.

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 simple one-parameter cleanup tool, the description is complete enough. It explains the lifecycle context (step 3 of 3), the benefit (frees slot), and the necessity (concurrency cap). It does not detail the output or error states, but given no output schema and the clear action, this is sufficient.

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?

There is only one parameter, presenceId, with 0% schema description coverage, but the description implies it identifies the presence to retire by referencing 'a presence created by spawnPresence.' It doesn't state that presenceId must be a valid ID from a previous spawn, but the context is reasonable. The description adds minimal extra meaning beyond the schema's property name.

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 clearly states the tool's action ('Cleanly ends a presence'), the resource it applies to ('created by spawnPresence'), and its role in a sequence ('step 3 of 3'). It does not explicitly distinguish from siblings like retireArtifact, but the context of presence is specific enough to avoid confusion.

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?

It provides an explicit 'when to use' directive: 'Always call this when the presence is no longer needed.' It also explains the rationale — 'concurrent live presences are capped' — signaling that cleanup is important. However, it does not describe when NOT to use it (e.g., if the presence is already ended) or alternatives.

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

spawnPresenceSpawn a persistent presenceA

Instanced Manifestation, step 1 of 3 (spawn / animate / retire). Creates a persistent presence derived from the given context (e.g. 'a character based on what's on screen'). Optionally built from a held artifact (see addArtifact) rather than derived fresh. Returns a presenceId — pass it to animatePresence and retirePresence. The generative work (what the presence actually looks like) happens inside this contract; the contract itself never changes.

NameRequiredDescriptionDefault
styleHintNoOptional style guidance
artifactIdNoOptional id from addArtifact — use this artifact's content as the basis
sourceContextYesWhat to derive the presence from

TDQS

A4.1/5.0
Behavior3/5

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

With no annotations, the description carries the behavioral burden. It does disclose that the presence is persistent, that generative work happens 'inside this contract,' and that 'the contract itself never changes,' plus the return of a presenceId. However, it omits side-effect details such as whether an artifact is consumed, whether spawning twice overwrites, or permission requirements, and the final sentence is somewhat cryptic.

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

Conciseness4/5

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

The description is compact and front-loaded with lifecycle context before diving into parameters and return values. The final sentence about 'generative work' is somewhat vague and may not earn its place as clearly as the rest, but overall the structure is efficient.

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 tool with 3 parameters, no annotations, and no output schema, the description covers the essential context: what it creates, how it relates to addArtifact, what it returns, and what to do with that return value. It is reasonably complete, though a note about error conditions or idempotency would make it fully self-sufficient.

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

Parameters4/5

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

The schema already covers 100% of parameters, and the description adds meaning beyond it: it gives a concrete example for sourceContext, explains that artifactId is an alternative to fresh derivation, and clarifies that styleHint is optional. This enriches the bare schema descriptions without redundancy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: 'Creates a persistent presence derived from the given context.' It also positions the tool as 'step 1 of 3 (spawn / animate / retire)' and references animatePresence and retirePresence by name, making it easy to distinguish from the siblings and from addArtifact.

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?

The lifecycle is explicit: this is step 1, the returned presenceId feeds animatePresence and retirePresence, and the tool can be used either from fresh context or from a held artifact via addArtifact. It does not explicitly state when not to use it (e.g., versus manifestHighlight), so the guidance is clear but not exhaustive.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.1.0
    • First observedaddArtifact
    • First observedanimatePresence
    • First observedmanifestHighlight
    • First observedretireArtifact
    • First observedretirePresence
    • First observedspawnPresence
Deploy Server
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

TDQS

A4/5.0

Scored across 6 tools

Disambiguation5/5

Each tool targets a distinct resource and lifecycle stage: artifacts are added/retired, presences are spawned/animated/retired, and manifestHighlight covers a separate ephemeral display. The lifecycle hints in the descriptions make the boundary between artifact management and presence management clear.

Naming Consistency5/5

All six tools use a consistent camelCase verb-noun pattern, such as addArtifact, retirePresence, and spawnPresence. The resource-specific roots (artifact, presence, highlight) are kept uniform, so there are no mixed conventions or vague generic verbs.

Tool Count5/5

Six tools is well-scoped for a presence server: two artifact lifecycle tools, three presence lifecycle tools, and one ephemeral display tool. Each tool serves a distinct purpose, and none feels redundant or like filler.

Completeness4/5

Core lifecycles are covered: artifacts have add/retire, presences have spawn/animate/retire, and the highlight feature is available for ephemeral display. The only notable gap is the lack of a list/query tool for current artifacts or active presences, but agent workflows can work around that with returned IDs.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-interactive-ui-server

    AiAgentKarl
    A
    license
    A
    quality
    D
    maintenance
    Enables AI agents to render interactive user interfaces such as forms, dashboards, charts, tables, and wizards directly in MCP-compatible clients. Supports structured data collection and richer interactions beyond text responses.
    6
    MIT

  • Persona MCP

    UMEBOSHIISAN
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables supported local AI clients to control a visible desktop presence through bounded presentation tools such as animations, window control, and short local speech over a loopback endpoint, without granting decision or execution authority.
    MIT

  • Open Computer Use

    aibo204
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to observe and control the user's live desktop by listing apps, reading accessibility trees, and performing clicks, typing, scrolling, dragging, and other input actions with per-action approvals and local audit archives.
    1
    MIT