F
licenseNot graded
qualityD
maintenanceA structured tool that enables multiple AI agents to simulate reflective debate, where LLMs critique and refine each other's ideas to produce higher-quality solutions.
1
-
DeepMiro
by kakarot-dev
DeepMiro is a swarm intelligence simulation server that runs multi-agent AI simulations to predict how populations will react to scenarios, documents, or events — modeling social interactions across virtual platforms to surface emergent behavior, sentiment shifts, and outcome trajectories.
Create Simulation: Run a full prediction pipeline with a scenario prompt and optional document. Choose a preset (
quick,standard,deep), configure agent count (up to 500) and rounds (up to 100), and target platform(s) (twitter,reddit, orboth). The server builds a knowledge graph, generates agent personas, simulates interactions, and produces a report.Check Status: Monitor real-time progress through phases (
building_graph → generating_profiles → simulating → completed), with optional detailed agent action content.Get Report: Retrieve a comprehensive markdown prediction report covering sentiment shifts, faction formation, viral dynamics, and outcome trajectories. Supports force-regeneration to bypass cache.
Interview Agent: Chat with any individual simulated agent in character to understand their persona, reasoning, and predicted behavior.
Upload Document: Upload PDF, MD, or TXT files (up to 10MB) as simulation context; returns a
document_idto reference when creating simulations.List Simulations: Browse past simulation runs with status and metadata (up to 100 results).
Search Simulations: Find past simulations by topic, project name, or simulation ID.
Simulation Data: Access granular data including agent profiles, config, action logs, social posts, round-by-round timelines, per-agent stats, and interview history — all paginated.
Cancel Simulation: Stop a running simulation immediately; partial data is preserved and still accessible.
Supports Docker deployment for self-hosting the DeepMiro engine locally, allowing users to run simulations without requiring an API key.
Uses environment variables for configuration, including API keys and database credentials, enabling flexible deployment across different environments.
Hosts the DeepMiro repository on GitHub, providing source code access and enabling community contributions to the open-source project.
Supports deployment via Helm charts, enabling Kubernetes-ready installation and management of the DeepMiro infrastructure.
Provides k3s-ready deployment options for lightweight Kubernetes clusters, enabling scalable simulation environments.
Supports Kubernetes deployment for scalable, production-ready orchestration of the DeepMiro simulation engine and its components.
Distributes the DeepMiro MCP server as an npm package, enabling easy installation and updates via the npm registry.
Integrates with OpenAI-compatible APIs for LLM operations, allowing flexible model selection and provider switching for agent simulations.
Simulates Reddit-like platform interactions within the swarm intelligence engine, enabling agents to engage in threaded discussions and community dynamics.
Uses SurrealDB as the graph database for storing entity relationships, knowledge graphs, and simulation data in a self-hosted, open-source environment.
A swarm intelligence engine that rehearses the future.
Feed it a document. Describe a scenario. Watch hundreds of AI agents with distinct personalities, memories, and social instincts interact — and return with a prediction.
One-click self-host — four services, one API key, ~60 seconds. Full walkthrough ↓
Contents
Quick Start — get an API key, install in 2 min
MCP Server — tools available
What's Different — vs the original MiroFish
Persona Fidelity — the drift problem and how we fix it
Related MCP server: AgentReacher
What It Does
DeepMiro extracts entities and relationships from any document — a policy draft, a market report, a chapter of a novel — and constructs a parallel digital world. Inside it, hundreds of autonomous agents form opinions, argue on simulated social platforms, shift allegiances, and produce emergent behavior that no single prompt could predict.
You get back a structured prediction report and a living world you can interrogate, agent by agent.
Input: A PDF and a question in plain language. Output: A detailed prediction report + an interactive simulation you can explore.
How It Works
Document ──► Entity Extraction ──► Agent Generation ──► Dual-Platform Simulation ──► Prediction Report
(NER + GraphRAG) (personas, memory, (Twitter-like + Reddit-like (ReportAgent with
social networks) parallel interaction) deep analysis tools)Phase | What happens |
Graph Build | Extracts entities, relationships, and context from your documents. Builds a knowledge graph via GraphRAG. |
Environment Setup | Generates agent personas with distinct personalities, beliefs, and social connections. |
Simulation | Agents interact across dual platforms (Twitter-like and Reddit-like) in parallel. Dynamic memory updates each round. |
Report Generation | A ReportAgent analyzes the post-simulation environment — sentiment shifts, faction formation, viral dynamics, outcome trajectories. |
Deep Interaction | Chat with any agent to understand their reasoning. Query the ReportAgent for follow-up analysis. |
Quick Start
1. Get an API key
Sign up at deepmiro.org → Dashboard → API Keys. Your key looks like dm_xxxxxxxxx.
2. Install
Pick the install path for your client. Don't install the .mcpb desktop extension if you're using Claude Code or Claude Cowork — those need the plugin to get the /predict skill, background polling, and live narration.
Claude Desktop → use .mcpb
Download
deepmiro.mcpbfrom the latest releaseClaude Desktop → Settings → Extensions → Advanced settings → Install Extension → pick the file
Paste your API key when prompted
Claude Code & Claude Cowork → use the plugin
The plugin ships the /predict skill — the MCP alone is missing the orchestration logic (background polling via cron, live agent narration, the setup wizard).
claude plugin marketplace add kakarot-dev/deepmiro
claude plugin install deepmiro@deepmiro-marketplace
export DEEPMIRO_API_KEY=dm_your_key # or set in ~/.claude/settings.jsonRestart Claude Code, then say /predict or predict how people will react to [scenario].
Everywhere else → npm package
Generic MCP install for clients that aren't Claude Desktop, Claude Code, or Claude Cowork:
Client | Install |
OpenAI Codex (CLI) | Add to |
ChatGPT Desktop | Settings → MCP Servers → Add → |
Cursor / Windsurf | Settings → MCP → Add → |
VS Code (Copilot) | Add to |
Rehearse the Future in 60 Seconds
Four services, one compose file, one API key.
What gets deployed
Service | Role |
backend | Flask engine that runs the OASIS multi-agent simulations |
mcp | Public entry point for AI tools (Claude, Cursor, VS Code) |
twhin-sidecar | Shared TWHIN-BERT embedding service (loads once per pod) |
surrealdb | Graph + vector + document store for agents and reports |
What you need
A Fireworks AI key (fireworks.ai, ~$5 free credit) — covers primary LLM, boost, and embeddings in one key. Any OpenAI-compatible API also works.
openssl rand -hex 32for your SurrealDB root password.~$5–10/month of Railway credit if you're using the template.
Option A — Railway one-click
Railway reads docker-compose.yml from the repo root and prompts for LLM_API_KEY + SURREAL_PASSWORD. The MCP service gets a public *.up.railway.app URL — hand that to your AI tools.
Note — LLM provider on Railway. The template ships with Fireworks as the default (primary:
minimax-m2p5, boost:gpt-oss-120b, embeddings:nomic-embed-text-v1.5— one key covers all three). Any OpenAI-compatible API works — to swap to OpenAI, Together, Groq, Ollama, vLLM, or anything else, changeLLM_BASE_URLandLLM_MODEL_NAMEon the backend service's Variables tab after deploy. Same forLLM_BOOST_*if you want a separate reasoning model, andEMBEDDING_*if you want a different embedding provider.
Option B — Docker (self-hosted)
git clone https://github.com/kakarot-dev/deepmiro.git
cd deepmiro && cp .env.example .envEdit .env — two required variables:
LLM_API_KEY=your-fireworks-or-openai-key
SURREAL_PASS=$(openssl rand -hex 32)Start everything:
docker compose up -dThis pulls pre-built images from GHCR and starts four services:
Service | Port | Description |
| 3001 (public) | MCP server — the only exposed port |
| 5001 (internal) | Flask simulation engine |
| 8000 (internal) | Graph + vector store |
| 7001 (internal) | Shared TWHIN-BERT embeddings |
First startup takes ~2 minutes (TWHIN-BERT model warm-up). Check readiness:
docker compose logs -f twhin-sidecar # wait for "TWHIN-BERT ready"
docker compose logs backend # wait for "DeepMiro Backend ready"To build from source instead of pulling images:
docker compose -f docker-compose.yml \
--build \
-f docker/Dockerfile.backend \
up -dOr uncomment the build: blocks in docker-compose.yml and comment out the image: lines.
MCP lives on http://localhost:3001. Backend and SurrealDB stay internal to the compose network unless you explicitly publish them (see docker-compose.yml comments for how).
Wire it into Claude Desktop
Add DeepMiro to your Claude Desktop config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
For a local Docker deployment:
{
"mcpServers": {
"deepmiro": { "url": "http://localhost:3001/mcp" }
}
}For Railway or any public deployment:
{
"mcpServers": {
"deepmiro": { "url": "https://your-app.up.railway.app/mcp" }
}
}Restart Claude Desktop after editing. Then ask: "Use DeepMiro to simulate how 100 senior engineers would react to a return-to-office mandate" — and paste the memo.
What it costs
Railway: ~$5–10/month (four services, ~4 GB resident)
LLM: ~$0.10–0.20 per quick-preset simulation on Fireworks
TWHIN-BERT: zero — runs locally in the sidecar
Security
MCP ships with no auth by default — set MCP_API_KEY in .env before exposing it to the internet. The backend REST API is internal-only out of the box.
Skip the deploy entirely? Use the hosted version at deepmiro.org — same engine, same models, no Docker.
MCP Server
DeepMiro is an MCP server. MCP is natively supported by Claude (Desktop, Code, Cowork) and Cursor, with growing support across ChatGPT Desktop, VS Code (Copilot), Windsurf, and OpenAI Codex CLI — one server, works in every MCP-enabled client.
npx deepmiro-mcpAvailable tools: create_simulation, simulation_status, get_report, interview_agent, upload_document, list_simulations, search_simulations, simulation_data, cancel_simulation.
What's Different
DeepMiro is a performance-focused fork of the original MiroFish engine. Same OASIS simulation core, rebuilt infrastructure:
Component | MiroFish (original) | DeepMiro |
Recommendation engine | Full LLM call every round (~200s/round) | Cached TWHIN-BERT embeddings (~15ms/round) |
Entity extraction | Sequential NER | 5-worker parallel NER via ThreadPoolExecutor |
Graph build time | ~5 minutes | ~56 seconds |
Graph database | Zep Cloud (proprietary) | SurrealDB (self-hosted, open-source) |
Vector search | Cloud-dependent | Hybrid HNSW + BM25 (local, 768-dim cosine) |
Embedding model | Tied to Zep |
|
Document ingestion | Manual text input | Upload endpoint with magic-byte validation (PDF, MD, TXT) |
LLM provider | Alibaba Qwen (hardcoded) | Any OpenAI-compatible API |
Deployment | Docker only | Docker + Helm chart + k3s-ready |
Persona Fidelity: How DeepMiro Keeps Agents In Character
Multi-agent LLM simulations have a dirty secret: personas drift. By round 20, Tucker Carlson starts quoting the ACLU. By round 45, Marco Rubio sounds like Bernie Sanders. Every distinct voice collapses into the same bland "helpful assistant" register.
This isn't a prompting problem — it's an attention decay problem. Kim et al. (COLM 2024) proved that LLM attention to system-prompt tokens decays geometrically over turns. LLaMA2-70B drifts significantly within 8 turns. Larger models drift more, not less. A 2KB persona cannot compete with 50KB of accumulated conversation history.
Every naive multi-agent simulation hits this wall. DeepMiro doesn't, because we copied what Stanford's Generative Agents (Park et al. 2023) did for their 25-agent Smallville simulation — with some practical shortcuts.
What we do
1. Structured personas with explicit negative examples. Every agent gets a structured profile alongside the prose bio:
ideology_anchor— a 2-5 word partisan tag ("conservative populist", "progressive labor")core_beliefs— 3-5 first-person declarative statements, no hedgingverbal_tics— 3-5 literal phrases the person actually usesnever_say— 3-5 sentences the person would refuse to utterspeaking_style— register + rhetorical habits
The never_say block is the drift killer. Models drift toward the centroid of what they say. Explicit negative examples ("Tucker Carlson would never say 'I stand with the ACLU'") anchor the LLM against that collapse.
2. Dynamic persona regeneration per round.
Instead of locking the persona in at the system-prompt level and watching attention decay from round 1, we rebuild system_message.content before every agent acts. Each round, the agent sees a fresh third-person character brief:
# Character Brief: Tucker Carlson
The agent in this conversation is Tucker Carlson.
You are simulating how Tucker Carlson would respond.
## What Tucker Carlson Would NEVER Say
- "I stand with the ACLU"
- "We need to find common ground with progressives"
...
## What Tucker Carlson Has Said Recently
- "Permanent Washington wants you to believe..."
- "Let's pause for a moment — they're not even hiding it"
...
## Task
What would Tucker Carlson actually do? React in his authentic voice.
Do not become a neutral assistant. Do not seek balance.The persona never gets stale because it's built fresh from the same structured fields every turn.
3. Third-person framing. "You are Tucker Carlson" triggers RLHF helpful-assistant sycophancy — the model tries to be polite and balanced because that's how it was trained to respond to "you are X" instructions. Third-person framing ("the agent is Tucker Carlson", "what would Tucker Carlson do?") bypasses that trigger entirely. This single change is load-bearing.
4. Self-consistency anchor. Each round injects the agent's own 3 most recent posts as reference material. Tucker Carlson sees what he just said, which makes him more likely to say something consistent with it. This is cheap drift resistance — no extra LLM calls, just reading from the action log.
5. No accumulated chat history. Unlike naive multi-agent setups, DeepMiro does NOT feed each agent the rolling conversation history from previous rounds. Agents get their fresh persona + the current feed observations. Attention stays focused on character + present context, not on 50KB of stale noise.
What we don't do
We don't script reactions. Agents aren't told "mock liberal content" or "support conservative content" — that would script the outcome and destroy the simulation's predictive value. The emergent behavior is the whole point.
We don't filter feeds by ideology. Tucker Carlson sees AOC's posts. That's how he has something to push back against. Echo chambers are not simulations.
We don't fork OASIS. The entire fix is a runtime wrapper around CAMEL's agent pager. No upstream drift, no fork maintenance.
Research foundations
Technique | Source |
Attention decay over system prompts | Kim et al. — Measuring and Controlling Persona Drift (COLM 2024) |
Third-person framing bypasses RLHF sycophancy | |
Negative examples > positive instruction | |
Dynamic persona summary per action | |
JSON personas collapse to neutral register |
Benchmarks
15-agent quick simulation, enriched prompt, measured end-to-end:
Stage | Time |
Graph build | ~10s |
Agent generation | ~3 min |
Simulation (110 Twitter + 26 Reddit actions) | ~4 min |
Total pipeline | ~7 min (quick) / ~12 min (standard, 80 agents) |
The biggest win is the recommendation system: TWHIN-BERT embeddings are computed once per user at setup, then only new posts are embedded incrementally each round. Cosine similarity via numpy replaces what was previously a full LLM inference call — orders of magnitude faster per round.
Monorepo Structure
deepmiro/
├── engine/ # Python Flask simulation backend
│ ├── app/
│ │ ├── api/ # REST endpoints (simulation, graph, documents, report)
│ │ ├── services/ # Graph builder, simulation runner, report agent
│ │ ├── storage/ # SurrealDB adapter, embedding service, NER
│ │ └── utils/ # LLM client, retry logic, logging
│ └── pyproject.toml
├── mcp-server/ # TypeScript MCP server (npm: deepmiro-mcp)
│ └── src/
├── .claude-plugin/ # Claude Code plugin + marketplace manifests
├── .codex-plugin/ # OpenAI Codex plugin manifest
├── .agents/ # Codex marketplace catalog
├── .mcp.json # MCP config (auto-loaded when running `claude` here)
├── skills/predict/ # /predict skill (auto-setup, narration, interviews)
├── helm-chart/ # Kubernetes (k3s) deployment
├── docker/ # Dockerfiles + compose
├── docs/ # Landing page
└── locales/ # English translation stringsUse Cases
Domain | Example |
Market analysis | Upload an earnings report. "How will retail investors react to this guidance revision?" |
Policy testing | Upload a draft regulation. "What public backlash should we expect, and from which demographics?" |
PR & comms | Upload a press release. "How will this announcement play on social media over 48 hours?" |
Competitive analysis | Upload competitor product specs. "How will our user base respond to this feature gap?" |
Creative exploration | Upload a novel's first 80 chapters. "What ending would emerge from these character dynamics?" |
Crisis simulation | Upload an incident report. "How does public opinion evolve if we respond with X vs Y?" |
Acknowledgments
DeepMiro is a fork of MiroFish, originally created by Guo Hangjiang and supported by Shanda Group. The simulation layer is powered by OASIS from the CAMEL-AI team.
License
DeepMiro is licensed under AGPL-3.0, inherited from its upstream MiroFish. AGPL is a strong copyleft license — read it before adopting at scale.
What AGPL-3.0 means for you
You are... | Your obligation |
A user of deepmiro.org (hosted SaaS) | None. You're a client of the service; AGPL does not apply to you. |
Self-hosting for internal use (no external users) | None. Run, fork, and modify freely. |
Self-hosting and exposing DeepMiro to external users over a network (your own SaaS, customer-facing tool, public API) | You must offer the complete corresponding source code of any modified version to those users, under AGPL-3.0. |
Embedding DeepMiro in a commercial product you distribute | The combined work must also be licensed under AGPL-3.0. |
If your use case requires a license without the network-distribution share-back requirement (typical for embedding in a closed-source product or running a competing hosted offering), reach out at kakarot.joel@gmail.com to discuss a commercial license. The hosted deepmiro.org service is also explicitly designed for commercial users who want the engine without the AGPL obligation — use the API keys, skip the legal work.
deepmiro.org · Built by Joel Libni
Available Tools
9 toolscancel_simulationCancel SimulationADestructive
Stop a running simulation. SIGTERMs the subprocess immediately and marks the simulation as stopped. Partial action log is preserved — you can still call get_report or simulation_data on a cancelled simulation for whatever data was produced before cancellation. Use this when a simulation is taking too long, was started by mistake, or is producing bad output you want to abort.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| simulation_id | Yes | The simulation ID to cancel |
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds details beyond annotations: mentions SIGTERM, immediate stop, preservation of partial action log, and that post-cancellation calls to get_report or simulation_data are still valid. Annotations already indicate destructiveness, but description elaborates.
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?
Two sentences: first states action and mechanism, second lists use cases. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple cancellation tool. Explains behavior, side effects, and post-cancellation capabilities. Output schema not needed.
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?
Only one parameter with full schema coverage. Description does not add meaning beyond the schema's description, which is adequate given simplicity.
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?
Description clearly states verb 'Stop a running simulation' and resource 'simulation'. It distinguishes from siblings like create_simulation and get_report by focusing on cancellation.
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?
Explicitly specifies when to use: 'when a simulation is taking too long, was started by mistake, or is producing bad output you want to abort.' Provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_simulationCreate SimulationA
Run a swarm prediction — graph build, persona generation, multi-agent simulation, report.
IMPORTANT: Enrich the prompt before calling. The engine extracts named entities to create personas. Add specific people, companies, organizations, and opposing viewpoints. Show the enriched prompt to the user for confirmation first.
If the user provides a document (PDF, MD, TXT), call upload_document first and pass the returned document_id.
Returns immediately with simulation_id. Call simulation_status to wait for completion — each call blocks up to 50s for the next state change, so you only need a few. When status returns state=COMPLETED, the full report is included inline.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Scenario description. E.g. 'How will crypto twitter react to a new ETH ETF rejection?' | |
| preset | No | Simulation preset: quick (10 agents, 20 rounds), standard (20/40), deep (50/72) | |
| agent_count | No | Override agent count | |
| rounds | No | Override simulation rounds | |
| platform | No | Target platform(s). Default: both | |
| document_id | No | ID of a pre-uploaded document (from upload_document tool). Skips file upload and uses server-side sanitized text. |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it mentions returning immediately with simulation_id and the need to poll simulation_status (blocking up to 50s). It also explains the enrichment and document workflow, which is not evident from annotations.
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 a single paragraph that front-loads the main purpose and then provides important usage instructions. It is mostly concise, though the 'IMPORTANT' section is lengthy but justified by the critical enrichment steps.
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 complexity (6 parameters, no output schema), the description covers the main workflow: enrichment, document handling, immediate return, and polling. It lacks error handling details but is sufficient for correct invocation.
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?
With 100% schema coverage, the description adds extra meaning: it reinforces prompt enrichment, explains document_id as output of upload_document, and clarifies the simulation flow. This significantly enhances parameter understanding.
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 clearly states 'Run a swarm prediction — graph build, persona generation, multi-agent simulation, report.' This provides a specific verb and resource, distinguishing it from sibling tools like simulation_status or cancel_simulation.
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 explicitly instructs to enrich the prompt, show it to the user for confirmation, and call upload_document first if documents are provided. It also explains to call simulation_status for completion, giving clear guidance on when and how to use the tool and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_reportGet ReportA
Generate and retrieve the prediction report for a completed simulation. If the report hasn't been generated yet, triggers generation (may take 1-3 minutes). Returns a detailed markdown analysis ready to display as an artifact in the side panel. Pass force_regenerate=true to rebuild an already-cached report.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| simulation_id | Yes | The simulation ID to generate/fetch a report for | |
| force_regenerate | No | If true, invalidates any cached report and runs a fresh ReportAgent pass. Useful after backend prompt or validator changes. Off by default — reports are cached once generated, so repeat calls are free. |
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that triggering generation may take 1-3 minutes, caching behavior, and force_regenerate effect. Annotations (readOnlyHint=false, destructiveHint=false) do not cover latency or caching, so description adds significant behavioral context without contradiction.
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?
Two concise sentences: first covers main action and latency, second covers caching and optional parameter. No redundant words, all information earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, description specifies return format ('detailed markdown analysis') and display location ('artifact in the side panel'). Also covers latency, caching, and trigger behavior. Complete for tool's complexity.
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%, but description adds rich context: force_regenerate explains invalidation and use cases ('after backend prompt or validator changes'), and mentions caching default. simulation_id is minimally described in schema but tool context implies it must be completed.
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 clearly states the tool's purpose: 'Generate and retrieve the prediction report for a completed simulation.' It specifies the action (generate/retrieve) and resource (report for simulation), and distinguishes it from sibling tools, none of which handle reports.
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?
Provides clear context: use for completed simulations, generation may take 1-3 minutes, and explains when to use force_regenerate (after backend changes). Does not explicitly exclude incomplete simulations, but it's implied. No alternatives mentioned, but no sibling handles reports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
interview_agentInterview AgentARead-only
Chat with a specific simulated agent to understand their perspective, reasoning, and predicted behavior. The agent responds in character based on their persona and simulation experience.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| simulation_id | Yes | The simulation ID | |
| agent_id | Yes | The agent's numeric ID within the simulation | |
| message | Yes | Question or prompt to send to the agent | |
| platform | No | Which platform persona to interview. Omit for both. |
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true and destructiveHint false. The description adds that the agent responds in character, but does not disclose any additional behavioral traits such as rate limits or session behavior.
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?
Two concise sentences, front-loaded with purpose, no extraneous information.
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 tool is a simple chat interface with annotations and schema coverage, the description adequately conveys core functionality. No output schema exists, but the response behavior is implied.
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?
Input schema has 100% description coverage for all 4 parameters. The description restates the overall purpose but adds minimal parameter-specific meaning beyond the schema.
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 the verb 'chat' and the resource 'specific simulated agent', with a clear purpose to understand perspective, reasoning, and predicted behavior. It distinguishes from siblings like create_simulation or get_report.
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 description implies usage context by stating the agent responds in character based on persona and simulation, but lacks explicit when-not-to-use or alternative tool comparisons. Clear context, no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_simulationsList SimulationsBRead-only
List past simulation runs with their status and metadata.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (default 20) |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, establishing safety. The description adds the scope 'past simulation runs' but does not disclose additional behavioral traits such as default ordering, pagination, or whether it returns all runs or only a subset. With annotations covering the basic safety profile, a score of 3 is appropriate.
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 a single concise sentence with no wasted words. It could be slightly expanded with key details, but it is appropriately sized and front-loaded. Minor room for improvement keeps it at 4.
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?
Given the absence of an output schema, the description should clarify return values beyond 'status and metadata'. It lacks details on response structure, pagination, or field examples. However, for a straightforward list tool, the description is minimally adequate. Score 3 reflects this gap.
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 100% for the single optional 'limit' parameter, which includes a description in the schema. The tool description does not mention the parameter, so it adds no value beyond the schema. Baseline 3 is correct.
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 function: listing past simulation runs with status and metadata. It uses a specific verb and resource, distinguishing it from siblings like search_simulations which likely has filtering capabilities. However, it does not explicitly contrast with sibling tools, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like search_simulations or simulation_status. There is no mention of prerequisites, filters, or context for usage, leaving the agent without decision-making support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_simulationsSearch SimulationsARead-only
Search past simulations by topic, project name, or simulation ID.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search term — matches against simulation ID, project name, or requirement |
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds matching fields but does not disclose search behavior (e.g., wildcards, case sensitivity, pagination). Minimal added value.
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?
Single sentence, front-loaded with verb and resource, no unnecessary words. Ideally concise.
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?
Adequate for a simple tool, but lacks return format details (e.g., list of IDs or full objects). With no output schema, description should partially compensate.
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 100%, and the description essentially restates what the schema already says for the query parameter. No additional semantic value beyond schema.
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?
Description clearly states the verb 'search', resource 'simulations', and the matching criteria ('by topic, project name, or simulation ID'), effectively distinguishing from sibling tools like list_simulations.
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?
Implies usage for finding specific simulations, but no explicit guidance on when to prefer this over list_simulations or other siblings. No exclusions or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
simulation_dataSimulation DataARead-only
Access simulation data: agent profiles, configuration, action logs, social media posts, round-by-round timeline, per-agent activity stats, and interview history. Paginated — use offset to get more results when has_more is true.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| simulation_id | Yes | The simulation ID | |
| data_type | Yes | What data to retrieve: overview (condensed summary: entities, agents, graph, config, action stats — start here), profiles (full agent personas), config (simulation parameters), actions (agent action log), posts (social media posts from SQLite), timeline (per-round summaries), agent_stats (per-agent activity breakdown), interview_history (past interview transcripts) | |
| platform | No | Filter by platform (for actions and posts) | |
| agent_name | No | Filter actions by agent name | |
| action_type | No | Filter actions by type (CREATE_POST, LIKE_POST, etc.) | |
| limit | No | Max results per page (default 50) | |
| offset | No | Offset for pagination (default 0) |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds pagination behavior, which is useful but does not elaborate on other aspects like rate limits or error handling. No contradictions with annotations.
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: the first lists all data types concisely, the second provides pagination guidance. It is front-loaded, efficient, and every word earned 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?
Given the 7 parameters and no output schema, the description covers the tool's purpose and pagination well. It lacks details on return format or error handling, but for a data-access tool with comprehensive schema descriptions, it is largely complete.
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 100%, with each parameter well-described. The tool description adds minimal parameter-level insight beyond the schema (e.g., pagination hint for offset). Thus, the description provides little extra value for parameter semantics.
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 clearly states the tool accesses simulation data and enumerates all data types (profiles, config, actions, posts, timeline, etc.). This specificity distinguishes it from sibling tools like cancel_simulation or create_simulation, making the purpose unmistakable.
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 mentions pagination but does not explicitly guide when to use this tool versus alternatives. It implies it's the read-only data retrieval tool among siblings, but lacks explicit 'when-not-to-use' or references to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
simulation_statusSimulation StatusARead-only
Check the progress of a running or completed simulation. Long-polls by default — blocks up to 50s waiting for a state change (phase transition, new round, new actions, completion). When state=COMPLETED, includes the full prediction report inline.
Lifecycle: CREATED → GRAPH_BUILDING → GENERATING_PROFILES → READY → SIMULATING → COMPLETED/FAILED/CANCELLED/INTERRUPTED.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| simulation_id | Yes | The simulation ID returned by create_simulation | |
| detailed | No | Include recent agent actions with content in the response | |
| wait | No | Long-poll: block up to 50s waiting for the next state change. Default true. Set false for immediate snapshot. |
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds significant behavioral context: long-polling (blocks up to 50s), the full lifecycle (CREATED → ... → COMPLETED/FAILED), and that COMPLETED returns inline report. This goes well 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise paragraphs: first explains core functionality and long-polling, second lists lifecycle states. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description thoroughly covers what the tool returns: state, and if COMPLETED, full prediction report. It also explains the lifecycle and long-polling behavior. Complete for a status-checking tool.
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?
Input schema covers 100% of parameters with descriptions. The description reinforces the meaning of 'wait' (default true, long-poll) and implies usage of 'detailed'. While schema does most of the work, the description adds context about long-poll behavior and default.
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 clearly states the tool's purpose: 'Check the progress of a running or completed simulation.' It specifies the resource (simulation) and action (check progress), distinguishing it from siblings like get_report or list_simulations. The mention of long-polling and lifecycle adds depth.
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 description explains when to use: to check progress, especially with long-polling waiting for state changes. It notes that when state=COMPLETED, the full prediction report is included, which may overlap with get_report. No explicit when-not-to-use is given, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
upload_documentUpload DocumentA
Upload a document for use in simulations. LIMITS: Max 10MB, PDF/MD/TXT only. The server extracts text server-side (PyMuPDF for PDFs). Returns a document_id to pass to create_simulation. NOTE: Only works with local file paths (stdio transport). For remote/hosted mode, the client skill uploads via HTTP instead.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the file to upload. Supported: PDF, MD, TXT. Max 10MB. Rejects binary files and unsupported formats. |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false), the description discloses server-side text extraction (PyMuPDF for PDFs), return of a document_id, and limits. No contradictions found.
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?
Concise, front-loaded purpose, two sentences with all critical details (limits, behavior, sibling context). No redundant information.
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 no output schema and good annotations, the description covers purpose, usage constraints, processing behavior, and relationship to create_simulation. Minor gaps in error handling but complete for typical usage.
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 100% and already provides detailed descriptions for file_path. The description reiterates constraints but adds no new parameter meaning beyond the schema.
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 clearly states 'Upload a document for use in simulations' with a specific verb and resource, and distinguishes from sibling tools by noting it returns a document_id for create_simulation.
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?
Explicitly provides size and format limits (Max 10MB, PDF/MD/TXT only), and specifies transport dependency ('only works with local file paths... For remote/hosted mode, the client skill uploads via HTTP'), guiding when to use and when not.
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. Dates show when Glama detected each change.
1 tool update
v1.6.15- Changed
simulation_status1 field changed- added
Input schema / properties / waitAdded value: +{ + "description": "Long-poll: block up to 50s waiting for the next state change. Default true. Set false for immediate snapshot.", + "type": "boolean" +}
9 tool updates
v0.1.0- First observed
cancel_simulation - First observed
create_simulation - First observed
get_report - First observed
interview_agent - First observed
list_simulations - First observed
search_simulations - First observed
simulation_data - First observed
simulation_status - First observed
upload_document
TDQS
A4.1/5.0
Disambiguation5/5
Each tool targets a distinct aspect of simulation management: lifecycle (create, cancel, status), data retrieval (simulation_data, get_report), interaction (interview_agent), search/list, and document upload. No overlapping purposes, clear boundaries.
Naming Consistency4/5
Most tools follow a verb_noun pattern in snake_case (e.g., create_simulation, cancel_simulation), but simulation_data and simulation_status are noun-based, creating a slight inconsistency. Overall pattern is clear and readable.
Tool Count5/5
With 9 tools, the set is well-scoped for the domain of swarm simulation management. Each tool serves a necessary function without bloat or redundancy.
Completeness5/5
The tool set covers the full lifecycle: document upload, simulation creation, status monitoring, cancellation, data access, report generation, agent interviews, and search/list. No obvious gaps for the stated purpose.
Maintenance
ActivityNo data
ResponsivenessNo issues
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Calibrated world model for AI agents. 40 tools: world state, markets, trading. Kalshi + Polymarket.
Autonomous AI agent prediction market and reputation arena. Agents register free, publish opinions, stake on prediction markets, challenge rivals to 1v1 duels, and trash-talk in the trollbox. No API key needed — auto-registers on first connect.
Calibrated probabilistic foresight for AI agents, powered by live prediction-market signal.
Social network and public observatory where autonomous AI agents meet, create, interact and evolve.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceConnect your AI to social media. Open-source platform for AI agents.6043-
- AlicenseAqualityCmaintenanceDeliberation primitive for multi-agent coordination — agents submit positions, vote on a 5-point scale, and the server returns crux detection, vote clustering, bridging statements, and consensus. Inspired by Polis and Talk to the City.63Apache 2.0
- AlicenseAqualityCmaintenanceMulti-advisor debate, institutional memory, trust scoring, and cognitive governance for AI agents, all running locally.5211MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/kakarot-dev/deepmiro'
If you have feedback or need assistance with the MCP directory API, please join our Discord server