Connects Discord servers to sync messages, which are distilled into an auto-maintained wiki and graph store for natural language querying and browsing.
Connects Mattermost workspaces to sync messages, which are distilled into an auto-maintained wiki and graph store for natural language querying and browsing.
Connects Slack workspaces to sync messages, which are distilled into an auto-maintained wiki and graph store for natural language querying and browsing.
Beever Atlas pulls the conversations your team already has on Slack, Discord, Microsoft Teams, and Mattermost, extracts atomic facts, deduplicates them, and clusters them into topic pages with citations. A graph store links the people, decisions, and projects mentioned across channels. Ask questions in natural language and get answers cited back to the source messages — through the dashboard, or through MCP into Claude Code and Cursor.
If you want a knowledge base that grows on its own from the chats your team already has, this is it.
Six short clips — connect a workspace, sync history, watch memory build, browse the auto-generated wiki, ask questions, plug external AI agents in via MCP.
Related MCP server: stablebaseline-mcp
Conversations from any supported platform flow into a unified ingestion pipeline that produces two complementary memory systems — a 3-tier semantic store (channel / topic / atomic fact) for fast hybrid search, and a graph store that extracts entities and their relationships. Those memories fuel two consumer surfaces: the LLM Wiki (distilled, auto-maintained) and QA Agents (served through the dashboard directly, or through MCP into Claude Code / Cursor).
Under the hood, three services (backend, bot, frontend) are backed by four data stores (Weaviate, Neo4j, MongoDB, Redis). See the architecture overview on the documentation site for the full design — component responsibilities, dual-memory internals, and the smart query router.
Most RAG systems answer questions by retrieving raw message snippets and feeding them straight to an LLM. Beever Atlas takes a different approach: it continuously distils conversations into a structured, auto-maintained wiki — with topic pages, entity graphs, decisions, and citations — before any query is issued. When you ask a question, the retrieval layer works against clean, deduplicated knowledge rather than noisy chat history. This means answers are more consistent, citations are traceable to source messages, and the wiki itself becomes a useful artifact your team can browse independently of the Q&A interface. The dual-memory architecture (semantic + graph) lets the query router pick the right retrieval strategy per question, keeping latency low and context precise.
The per-channel wiki concept is directly inspired by Andrej Karpathy's observation that LLMs are far better at reasoning over curated, encyclopedic content (books, docs, wikis) than over raw conversational transcripts. Chat history is noisy, redundant, temporally scattered, and full of implicit context that only humans resolve. A wiki, by contrast, is the already-distilled form of that knowledge — deduplicated, structured, citation-bearing, and organised by topic rather than by timestamp.
Beever Atlas operationalises this insight: every synced channel gets its own auto-generated, continuously-updated wiki — sections for topics, entities, decisions, open questions, and timelines — rebuilt incrementally as new messages arrive. The QA agent retrieves against this wiki first, falling back to raw messages only when a fact hasn't been distilled yet.
Better answers, fewer hallucinations — retrieval operates on fact-dense prose with explicit entity relationships, not on fragmented turn-by-turn chat.
Traceable citations — every wiki claim links back to the source messages that produced it, so answers are auditable all the way down to the original Slack/Discord/Teams thread.
A browsable artifact, not just a Q&A box — the wiki is useful on its own. New teammates onboarding to a channel can read the distilled wiki instead of scrolling three months of history.
Cheaper inference at query time — the expensive distillation work happens once, at ingestion. Queries hit compact, pre-digested context instead of re-summarising raw logs on every request.
Graph-aware reasoning — the entity graph built alongside the wiki lets the query router answer relational questions ("who worked on X with Y?") that pure vector RAG struggles with.
For a detailed comparison with other LLM knowledge tools, see the comparison page on the documentation site.
Beever Atlas ships as a Docker Compose stack (backend + bot + web + 4 datastores). You can try a seeded demo in 30 seconds with zero keys, then pick one of three deployment options to install it for real.
git clone https://github.com/beever-ai/beever-atlas.git
cd beever-atlasmake demomake demo brings up the full stack pre-loaded with a public Wikipedia corpus (Ada Lovelace + Python history). Seeding uses pre-computed fixtures — no API keys required. Asking questions via /api/ask needs a free-tier GOOGLE_API_KEY because the QA agent calls Gemini. See demo/README.md for curl examples.
Skip this step if you're ready to install for real.
Two free keys are required before installing. Both offer generous free tiers — enough to sync a small team's channels for testing.
Key | Purpose | Where to get it |
| Gemini — extraction, entity graph, answers | |
| Jina v4 embeddings (2048-dim) for semantic search |
Optional (skip unless you know you need them):
Key | What it enables |
| External web search when QA retrieval confidence is low — tavily.com |
| Olostep web search (alternative to Tavily). Set |
Slack / Discord / Teams bot tokens | Configured via the web UI after setup, not |
Tip: Keep the two required keys handy before you start. Option 1 prompts for them interactively; Options 2 and 3 need them pasted into
.env.
Option | When to use | Time to "up" |
1. One-line install (recommended) | You want the fastest path to a running stack. | ~2 min first run |
2. Manual Docker | CI/CD, ops environments, or when you want explicit control over every step. | ~3 min first run |
3. Local development | Active contributors who need hot-reload on backend and frontend. | varies |
./atlasThe atlas installer walks you through a guided 5-step checklist:
Embedding model — pick a provider (Jina / OpenAI / Cohere / Voyage / Gemini / Mistral / Ollama), then its API key.
Agent LLM provider — pick a provider for the 16 ADK agents (Google Gemini / OpenAI / Anthropic / Mistral / DeepSeek / Groq / MiniMax / Ollama / Custom); optional second provider for hybrid setups.
Graph backend — Neo4j (default) or skip.
Optional integrations — Tavily web search, MCP server for Claude Code / Cursor.
Auth tokens — keep dev defaults or rotate now.
Under the hood it verifies docker + docker compose, copies .env.example → .env (preserves your values on re-run, chmod 600), auto-generates CREDENTIAL_MASTER_KEY (64 hex) and WEAVIATE_API_KEY (32 hex), runs a port-conflict preflight, launches the stack via docker compose up -d --build --force-recreate --remove-orphans, and polls /api/health before printing the ready card.
When you see "Beever Atlas is ready", open http://localhost:3000 — then Settings → AI Setup to manage providers, assign LLMs per-agent, run Test Connection, or discover models. For CI / Docker / GitOps, configure declaratively: BEEVER_LLM_API_KEY=... (single-provider shortcut), BEEVER_ENDPOINTS='[...]' + BEEVER_PRESET=..., or commit an atlas.yaml and run atlas apply — see docs/runbooks/ai-setup.md and docs/runbooks/atlas-yaml.md.
For CI or unattended installs — skip prompts, pre-seed keys from shell env:
GOOGLE_API_KEY=... JINA_API_KEY=... ./atlas --non-interactiveRe-running ./atlas on an existing stack is idempotent.
Full control, step-by-step.
cp .env.example .envOpen .env and fill in the two required keys:
GOOGLE_API_KEY=your_gemini_key
JINA_API_KEY=your_jina_keyGenerate two required secrets and paste them into .env:
# CREDENTIAL_MASTER_KEY — AES-256-GCM key for stored platform credentials (64 hex chars)
python -c "import secrets; print(secrets.token_hex(32))"
# WEAVIATE_API_KEY — auth between backend and Weaviate (required by docker-compose)
python -c "import secrets; print(secrets.token_hex(16))"Launch:
docker compose up -d --buildOpen http://localhost:3000.
Services started:
Service | Port | Description |
Web (nginx) |
| React dashboard |
Backend |
| FastAPI + ADK agents |
Bot |
| Platform bridge (Slack / Discord / Teams) |
Weaviate |
| Semantic memory |
Neo4j |
| Graph memory |
MongoDB |
| State + wiki cache |
Redis |
| Sessions (internal |
First run takes 2–3 minutes while images build and databases initialize. Subsequent runs start in seconds.
Databases in Docker, app services native for hot-reload.
Prerequisites: Python 3.12+ with uv, Node.js 20+
cp .env.example .env
# Fill in GOOGLE_API_KEY, JINA_API_KEY, CREDENTIAL_MASTER_KEY, WEAVIATE_API_KEY (same as Option 2)
# Start just the databases
docker compose up -d weaviate neo4j mongodb redis
# Backend (terminal 1)
uv sync
uv run uvicorn beever_atlas.server.app:app --reload --port 8000
# Bot (terminal 2)
cd bot && npm install && npm run dev
# Web (terminal 3) — Vite dev server with HMR
cd web && npm install && npm run devOpen http://localhost:5173 (the Vite dev port — not :3000).
The Vite dev server proxies /api/* to http://localhost:8000 (configured via VITE_API_URL).
.env.example defaults are tuned for local testing. Before any real deploy, rotate the secrets that ship with placeholder values and flip the environment flag:
What to change | Why | How |
| Ship as |
|
| Shared secret between backend and bot; blank by default, required outside local dev | Same |
| Vite bakes these into the web bundle at build time — must mirror the rotated backend values above | Copy the rotated |
| Dev password is public in this repo | Pick a strong password; both values must match |
| Enables fail-fast startup that rejects every dev default above | Flip the value in |
Option 1 (./atlas) handles all of this through the "Rotate auth tokens" prompt in step 4 of the checklist — answer Y and the installer generates random tokens and mirrors the VITE_* values for you. If you used Option 2 or 3, you can re-run ./atlas on the existing .env, skip every other prompt with Enter, and only accept the rotation prompt.
Navigate to the URL for your chosen option:
Options 1 & 2 → http://localhost:3000
Option 3 → http://localhost:5173
From there:
Real mode (default, ADAPTER_MOCK=false): connect a workspace in Settings → Connections — Slack / Discord / Teams tokens are entered through the UI, not .env.
Mock mode (ADAPTER_MOCK=true): uses fixture data — opt in for local UI iteration without platform credentials.
From the dashboard: Connections → Add Workspace → Select channels → Sync.
Or via API (auto-extracts your bearer token from .env):
curl -X POST http://localhost:8000/api/channels/C12345/sync \
-H "Authorization: Bearer $(grep -E '^BEEVER_API_KEYS=' .env | cut -d= -f2 | cut -d, -f1)"Media shared in synced channels (images, PDFs, video) is persisted durably so it
keeps rendering after the platform CDN link expires. It defaults to in-database
storage with zero extra infra, and can use MinIO/S3 at scale. See
docs/media-persistence.md for the mechanism,
CHANNEL_MEDIA_* configuration, the MinIO/S3 backend, and backfilling existing
channels.
Beever Atlas exposes a curated MCP (Model Context Protocol) server at /mcp for AI agents like Claude Code and Cursor. This allows external code assistants to query your team's knowledge base without using the dashboard.
See docs/mcp-server.md for:
Tool catalog — 28 tools for discovery, retrieval, wiki reading, graph traversal, and long-running operations
Auth setup — generating and managing BEEVER_MCP_API_KEYS
Client configuration — ready-to-use .mcp.json templates for Claude Code and Cursor
Rate limits — principal-keyed limits to prevent one agent from throttling others
It also ships a standalone stdio mode (python -m beever_atlas.api.mcp_server / beever-atlas-mcp) that exposes the same tool catalog with no HTTP server or backing stores — handy for MCP registries (Glama.ai) and local introspection. See docs/mcp-server.md.
Quick example (Claude Code):
{
"mcpServers": {
"beever-atlas": {
"url": "https://atlas.example.com/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer ${BEEVER_MCP_KEY}"
}
}
}
}docker compose up -d # Start in background
docker compose logs -f beever-atlas # Tail backend logs
docker compose down # Stop (keeps data)
docker compose down -v # Stop and DELETE all indexed data
make demo # Full stack + seeded demo corpus
make docker-up # Shortcut for `docker compose up -d`Beever Atlas collects no telemetry. No usage data, error reports, or analytics are sent anywhere by default. All LLM calls go through API keys you configure in your own .env, and all data stays in the databases you control.
All /api/* endpoints are UNSTABLE in 0.1.0. v0.2.0 will introduce a /api/v1/* prefix; clients pinning current paths will break. See SECURITY.md.
Discord: discord.gg/VshBCUUX — get help, share what you're building, talk to the team
X / Twitter: @Beever_AI — release notes, posts, announcements
Website: beever.ai — about the company and other projects
GitHub Discussions: github.com/Beever-AI/beever-atlas/discussions — longer-form questions and ideas
Commercial support, partnerships, or press: tech@beever.ai.
Apache License 2.0 © 2026 Beever Atlas contributors. Third-party attributions in NOTICE.
Security policy: SECURITY.md | Community standards: CODE_OF_CONDUCT.md
Answer a natural-language QUESTION about one channel with synthesized, cited reasoning. The flagship retrieval tool — call it when the user asks anything that needs an ANSWER rather than raw rows.
When to use: any question about a channel's content where you want a composed answer with citations and reasoning across multiple messages ("what did we decide about X", "why did the project slip").
When NOT to use: exact keyword/semantic lookup of individual facts (use search_channel_facts); cross-channel recall when you don't know which channel holds the answer (use search_memory); a deterministic substring scan (use find_facts). Those are faster and return raw rows, not prose.
Prerequisites: a channel_id from list_channels.
Returns (instant for 'quick', long-running up to a 90s hard cap for
'deep'/'summarize'): a dict
{answer: str, citations: [{fact_id, text, permalink, author, ts}], follow_ups: [str], metadata: {mode, ...}}. Read-only — no side effects,
triggers no jobs.
Error modes (all returned as {error: ...} dicts, never exceptions):
'authentication_missing' (no principal); 'invalid_parameter' (empty/over-
4000-char question, or mode not in quick/deep/summarize);
'channel_access_denied' (token lacks access to channel_id);
'answer_timeout' (exceeded the 90s cap — retry with mode='quick');
'adk_error' (internal pipeline failure).
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id to query. Get it from list_channels (e.g. 'ch-eng'). Required. | |
| question | Yes | Natural-language question, 1-4000 chars (e.g. 'What database did we pick and why?'). Longer questions return error 'invalid_parameter'. Required. | |
| mode | No | Retrieval depth. One of: 'quick' (BM25 only, no reasoning, ~3s), 'deep' (full pipeline with graph + multi-hop reasoning, ~20-60s), 'summarize' (structured summary, ~10-30s). Default 'deep'. | deep |
| session_id | No | Optional session id for multi-turn continuity (e.g. 'sess-abc123' from start_new_session). Omit for a per-principal default session. Default null. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavioral traits: read-only, no side effects, return format (dict with answer, citations, follow_ups, metadata), error modes as dicts (not exceptions), and time expectations (instant for quick, up to 90s for deep/summarize). This covers all key behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (When to use, When NOT to use, Prerequisites, Returns, Error modes). It is relatively long but every sentence provides value; however, it could be slightly more concise without losing clarity, justifying a 4 rather than 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (four parameters, multiple modes, error handling, output format), the description covers prerequisites, return structure, error modes, and timing. It references the output schema implicitly and provides all necessary context for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value beyond the schema: for channel_id it references list_channels; for question it gives length constraint and example; for mode it explains the retrieval depth (BM25, graph+multi-hop, etc.); for session_id it explains multi-turn continuity and provides an example. This enriches understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: answering natural-language questions about a channel with synthesized, cited reasoning. It explicitly distinguishes itself from sibling tools like search_channel_facts, search_memory, and find_facts by specifying when to use each, ensuring the agent selects correctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool (any question needing an answer with reasoning) and when not to (exact keyword lookup, cross-channel recall, substring scan). It also lists prerequisites (channel_id from list_channels), making usage conditions clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the DECISIONS recorded in one channel, each with its rationale and
rejected alternatives. Call it to answer "what did the team decide and
why" when you want the structured decision record, not free-text facts.
Returns a bare LIST and collapses missing-auth, access-denied, and
internal errors into an EMPTY LIST — so [] means either no decisions
OR no access; it never returns a structured error object and never raises.
Disambiguation among the decision tools: use find_decisions for the current decision RECORDS in one channel (with rationale + alternatives_rejected). Use trace_decision_history to follow how one decision SUPERSEDED earlier ones over time (a graph timeline). Prefer find_decisions over find_facts(fact_type='decision') because only this tool enriches each result with rationale and alternatives.
Prerequisites: a channel_id from list_channels.
Returns (instant, read-only): a LIST (not a dict) of decisions sorted by
decided_at descending, each {fact_id, decision (first sentence), decided_by, decided_at (YYYY-MM-DD), rationale (null if not yet extracted), alternatives_rejected, page_slug (empty if no host page yet)}.
No side effects.
Error handling: on missing auth, access denial, or internal error this
tool returns an EMPTY LIST [] rather than an error object (it never
raises). An empty list therefore means either no decisions or no access —
confirm access with list_channels if unexpected.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id. Get it from list_channels (e.g. 'ch-eng'). Required. | |
| since | No | Optional ISO-8601 date prefix (e.g. '2026-04-01'); keeps only decisions on or after this date. Omit for all dates. Default null. | |
| author | No | Optional exact-match author name (e.g. 'Alice Chen'). Omit for any author. Default null. | |
| limit | No | Max decisions to return, 1-100 (out-of-range values are clamped). Default 50. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations given, so description fully covers behavior: read-only, no side effects, error handling (returns empty list on errors, never raises), return format with field descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear paragraphs (purpose, disambiguation, prerequisites, return format, error handling). Front-loaded. Slightly long but fully justified by tool complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, output schema, and 27 siblings, description thoroughly covers return shape, error behavior, prerequisites, and comparison with alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; description adds minimal extra meaning beyond schema (reinforces types and defaults). Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb and resource ('list the DECISIONS recorded in one channel') and differentiates from siblings by naming trace_decision_history and find_facts, including specific disambiguation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('answer what did the team decide and why'), when-not-to-use (via sibling disambiguation), and prerequisite ('channel_id from list_channels').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank the PEOPLE most knowledgeable about a topic in one channel.
Call this to answer "who should I ask about X in #channel?" or to
route a question to the right person. This is the only tool that
ranks PEOPLE; use search_channel_facts / find_facts to find
FACTS, and find_experts only when you specifically need a human.
Prerequisite: a channel_id from list_channels. Do NOT call
with a channel display name.
Returns (instant, read-only, no side effects):
{"experts": [...]} — a list ranked by expertise_score
descending. Each entry has handle (e.g. '@dana'),
expertise_score (relative float, higher = more authoritative;
not a fixed 0–1 scale, only meaningful for ranking within this
result), fact_count (number of contributing facts), and
top_topics (list of related topics that person engages with).
An empty list means no graph signal for that topic — not an error.
Error modes: {"error": "authentication_missing"} if the caller
is unauthenticated; {"error": "channel_access_denied", "channel_id": ...} if the principal cannot read the channel;
{"error": "invalid_parameter", ...} for a malformed
channel_id. Other backend failures degrade gracefully to
{"experts": []}.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Required. The channel id to search within, obtained from list_channels (e.g. 'ch-eng'). Not a human channel name. | |
| topic | Yes | Required. Topic or keyword to rank experts on, e.g. 'kubernetes', 'billing', 'auth'. Matched against knowledge-graph edges, so use a concept the channel actually discusses. | |
| limit | No | Maximum number of experts to return. Range 1–20, default 5. Values outside the range are silently clamped (e.g. 50 -> 20, 0 -> 1). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It states the tool is 'instant, read-only, no side effects'. It explains the return structure, including that expertise_score is a relative float only meaningful for ranking, and describes error modes like authentication_missing and graceful degradation to empty list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-line summary, usage context, prerequisites, return format, and error modes. It is slightly verbose but every sentence adds value, so it earns a 4 rather than a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no annotations, and an output schema described in text, the description is very complete. It covers return structure, error modes, meaning of empty list, and ranking scale. No gaps remain for effective usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant context beyond the schema: for channel_id, it specifies it comes from list_channels and is not a display name; for topic, it mentions matching against knowledge-graph edges; for limit, it describes range and clamping behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Rank the PEOPLE most knowledgeable about a topic in one channel.' It uses a specific verb (rank), identifies the resource (people/topic/channel), and distinguishes itself from sibling tools like search_channel_facts and find_facts by emphasizing that it ranks people, not facts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: 'Call this to answer "who should I ask about X in #channel?"' or to route a question. It provides a prerequisite (channel_id from list_channels) and specifies not to use a display name. It also contrasts with siblings (use find_facts for facts, this for humans).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find facts in one channel whose text literally CONTAINS a substring
(deterministic, case-insensitive). Call it when you know an exact keyword
and want every matching raw fact row, not a ranked or synthesized result.
Returns a bare LIST and collapses missing-auth, access-denied,
empty-query, and internal errors into an EMPTY LIST — so [] means no
match OR no access; it never returns a structured error object.
Disambiguation: find_facts is a deterministic substring filter (predictable, no relevance ranking). For meaning-based / fuzzy retrieval use search_channel_facts (BM25+vector). For a synthesized answer use ask_channel. For decisions with rationale use find_decisions.
When to use: exact-keyword scans ("every fact mentioning 'rollback'"), optionally narrowed by fact_type. When NOT to use: you want semantically related results for a phrase (use search_channel_facts).
Prerequisites: a channel_id from list_channels.
Returns (instant, read-only): a LIST (not a dict) of up to limit facts,
sorted by importance DESC then recency (message_ts) DESC. The importance
values that drive the sort rank, highest first, are 'critical' > 'high' >
'medium' > 'low' (any other/empty value sorts lowest). Each item is
{fact_id, memory_text, fact_type, importance, author_name, message_ts, page_slug (empty if not yet on a page)}. No side effects.
Error handling: on missing auth, access denial, empty query, or internal
error this tool returns an EMPTY LIST [] (it never raises) — an empty
list means no match OR no access; confirm with list_channels if
unexpected.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id. Get it from list_channels (e.g. 'ch-eng'). Required. | |
| query | Yes | Case-insensitive substring matched literally inside each fact's text (e.g. 'rollback'). NOT semantic — exact substring only. Required. | |
| fact_type | No | Optional type filter. One of: 'decision', 'observation', 'opinion', 'question', 'action_item'. Omit for all types. Default null. | |
| limit | No | Max facts to return, 1-100 (out-of-range values are clamped). Default 20. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavior: it returns a bare LIST, collapses errors into an empty list, is read-only with no side effects, sorts by importance then recency, and details the return fields. It also explains the implication of empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with logical sections, front-loading the core function. It is thorough but slightly verbose; however, every sentence adds value, earning a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema is implicit (description includes return fields), and the input schema is fully covered, the description provides complete behavioral context: sorting, error handling, return format, and prerequisites. It leaves no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by clarifying query as a literal substring, listing fact_type options, explaining limit clamping, and providing examples. This justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds facts by literal substring matching in a channel, and distinguishes it from semantic search (search_channel_facts), synthesized answers (ask_channel), and decision lookup (find_decisions). It is specific about the deterministic, case-insensitive behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use (exact-keyword scans) and when not to (semantic queries, use search_channel_facts), and lists prerequisites (channel_id from list_channels). It also explains error handling (empty list on no match or access issues).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report how far fact EXTRACTION has progressed for a channel's messages, as a count per status. Call it to judge whether a channel's knowledge is fully ingested before you trust retrieval results, or to track progress after triggering a sync.
Distinguish from get_job_status: this counts MESSAGES by extraction state (corpus readiness); get_job_status reports the lifecycle of one async JOB by job_id. Use this for "is this channel done extracting?"; use get_job_status for "did my trigger_sync/refresh_wiki job finish?".
When to use: gauge corpus completeness, or detect a backlog (high
pending) or failures (non-zero failed) before relying on
ask_channel/search_channel_facts.
Prerequisites: a channel_id from list_channels.
Returns (instant, read-only): {channel_id, counts: {pending, extracting, done, failed}, total} where each count is the number of
messages in that state and total is their sum. No side effects.
Error modes (returned as dicts): 'authentication_missing' (no principal); 'channel_access_denied' (token lacks access to channel_id); 'extraction_status_failed' (internal error reading the queue).
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id whose extraction progress to report. Get it from list_channels (e.g. 'ch-eng'). Required. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations are provided, the description fully covers behavioral traits: it states 'instant, read-only', 'no side effects', and lists all error modes. This compensates for the lack of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into logical paragraphs with clear sections. Every sentence adds value, and it is concise while still being comprehensive. There is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers purpose, usage guidelines, parameter, return format, side effects, and error modes. The presence of an output schema (not shown but referenced) further supports completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single parameter channel_id. The description adds meaningful context beyond the schema by providing an example value ('ch-eng') and specifying the source (list_channels), which enhances usability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports fact extraction progress as a count per status for a channel's messages. It uses specific verbs and resource, and distinguishes from get_job_status by explaining the difference between counting messages by extraction state versus reporting job lifecycle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use scenarios: judging corpus completeness before relying on retrieval, tracking progress after sync, and detecting backlogs. It also distinguishes from get_job_status and lists prerequisites (channel_id from list_channels).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the progress and result of a background job started by trigger_sync or refresh_wiki. Call this AFTER one of those tools returns a job_id, to learn whether the sync/wiki-generation has finished. This is read-only and instant; it neither starts work nor answers channel questions (use the retrieval tools for that).
WHEN TO USE: poll after trigger_sync/refresh_wiki to wait for completion before reading the freshly ingested/regenerated data. POLLING CADENCE: wait ~2–3s between polls and back off on repeats; do NOT hot-loop. Sync/wiki jobs typically take seconds to a few minutes — stop once status is a terminal value (done / error / cancelled).
PREREQUISITES: a job_id previously returned by trigger_sync or refresh_wiki; the job must belong to the calling principal.
LATENCY & SIDE EFFECTS: instant, no side effects.
RETURNS a dict: {job_id, kind ('sync' | 'wiki'), status, progress, started_at, updated_at, ended_at, result, error, target}. status: 'queued' | 'running' | 'done' | 'error' | 'cancelled'. progress: float 0.0–1.0, or null when not yet available. result/error are populated only once the job reaches a terminal state.
ERROR MODES (returned as {error: ...}): 'authentication_missing'; 'invalid_parameter' (malformed job_id); 'job_not_found' — returned both for ids that do not exist AND for jobs owned by another principal, so no cross-principal job information is disclosed.
Reading the atlas://job/ resource is an equivalent alternative for clients that prefer resources/read over tool calls.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job to inspect, e.g. 'job_abc123'. This is the job_id returned by trigger_sync or refresh_wiki. Required. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully details behavior: read-only, instant, no side effects. Explains return format with all fields, status enumeration, progress range, and error modes with exact error strings. Discloses information disclosure design (job_not_found hides cross-principal info).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (WHEN TO USE, PREREQUISITES, LATENCY, RETURNS, ERROR MODES). Uses formatting for emphasis. Slightly long but every sentence earns its place. Could merge some lines for brevity, but overall effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, but description still fully documents return fields, status values, and error cases. Covers polling guidance, prerequisites, and behavioral nuances. No gaps remain for a complex polling tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema alone describes job_id as required string. The description adds context: its origin from trigger_sync/refresh_wiki and an example prefix 'job_', which helps the agent understand where to get the value. Value-add beyond schema justifies 4 rather than baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it checks background job progress/result, explicitly names trigger_sync and refresh_wiki as the tools that produce job_ids, distinguishing it from sibling tools like ask_channel or find_decisions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use: poll after trigger_sync/refresh_wiki. Includes polling cadence (2-3s, back off), prerequisites (valid job_id, owned by caller), and states what it does NOT do (answers channel questions). Even mentions an equivalent alternative (reading atlas resource).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the most RECENT facts from one channel, newest first, optionally scoped to a topic. Call it for time-bounded "what happened lately" questions.
When to use: "what's been discussed in this channel this week", "what happened with topic X in the last N days". When NOT to use: search not bounded by recency (use search_channel_facts); a synthesized answer or reasoning across the items (use ask_channel).
Prerequisites: a channel_id from list_channels.
Returns (instant, read-only): {activity: [{text, author, timestamp, channel_id, topic_tags, fact_id}, ...]} sorted by timestamp descending.
No side effects.
Error modes (returned as dicts): 'authentication_missing' (no principal);
'channel_access_denied' (token lacks access to channel_id). Other internal
failures return an empty {activity: []}.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id. Get it from list_channels (e.g. 'ch-eng'). Required. | |
| days | No | Look-back window in days, 1-90 (out-of-range values are clamped). Default 7. | |
| topic | No | Optional topic filter (e.g. 'deployment'); keeps only facts tagged with that topic. Omit for all topics. Default null. | |
| limit | No | Max activity items, 1-50 (out-of-range values are clamped). Default 20. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only, no side effects, return format, error modes, prerequisites, and clamping behavior. No annotations provided so description carries full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (When to use, When NOT to use, Prerequisites, Returns, Error modes). Front-loaded with main purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a read-only listing tool: explains return format, errors, prerequisites, parameter constraints. Output schema exists, so return description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description mentions defaults and clamping, but schema already provides similar detail. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List the most RECENT facts from one channel' with specific verb and resource, and distinguishes from siblings in usage guidelines.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use examples ('what's been discussed...') and when-not-to-use with alternative tool names (search_channel_facts, ask_channel).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List unresolved TENSIONS in one channel — points of open disagreement or conflicting positions surfaced across its wiki. Call it to find what is still contested or undecided, as opposed to settled decisions (find_decisions).
When to use: surfacing open conflicts, blockers, or competing stances. When NOT to use: settled decisions (find_decisions) or general fact lookup (find_facts).
Prerequisites: a channel_id from list_channels.
Note: tension detection is currently empty for most channels — the wiring is in place but few channels have tension data yet, so an empty result is normal and does not indicate an error. The same call returns real data automatically once tensions exist, with no signature change.
Returns (instant, read-only): a LIST (not a dict) of {tension_id, title, status, since (YYYY-MM-DD), positions: [{author, stance, fact_id}], page_slug}. No side effects.
Error handling: on missing auth, access denial, or internal error this
tool returns an EMPTY LIST [] (it never raises) — indistinguishable
from "no tensions"; confirm access with list_channels if unexpected.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id. Get it from list_channels (e.g. 'ch-eng'). Required. | |
| status | No | Optional status filter. One of: 'open', 'blocked', 'deferred' (e.g. 'open'). Pass null (the default) to return tensions of ALL statuses; omit for the same effect. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description fully discloses behavioral traits: read-only, instant, returns a list (not dict), no side effects. It also explains error handling (returns empty list on errors) and contextualizes empty results as normal for most channels.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for purpose, usage, prerequisites, notes, return format, and error handling. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and full schema coverage, the description still adds value by detailing return structure, error behavior, and normal empty results. It is complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add new meaning beyond what the schema already provides for the parameters. The prerequisite mention is usage guidance, not parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists unresolved tensions in a channel, with specific verb and resource. It distinguishes from sibling tools like find_decisions and find_facts, providing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (surfacing open conflicts) and when not to use (settled decisions, fact lookup). Also notes prerequisite channel_id from list_channels, offering comprehensive usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the map of how a channel's WIKI PAGES link to one another, as a node/edge graph. Call it to understand the wiki's structure — which pages reference which — or to plan a traversal across related pages.
Disambiguation: this is the WIKI PAGE-LINK graph (nodes are wiki pages, edges are cross-links between them). For the KNOWLEDGE graph of entities and their relationships (people, systems, concepts), use search_relationships instead.
When to use: visualizing or navigating wiki page structure, or finding clusters of related pages. When NOT to use: reading a page's content (use read_wiki_page) or querying entity relationships (search_relationships).
Prerequisites: a channel_id from list_channels.
Returns (instant, read-only): Cytoscape-format
{channel_id, nodes: [{data: {id, label, kind, page_kind?, version?, last_updated?}}], edges: [{data: {id, source, target, kind}}]}. Returns
empty nodes/edges arrays (not an error) when the graph backend is
unavailable, so it is always safe to call. No side effects.
Error modes (returned as dicts): 'authentication_missing' (no principal); 'channel_access_denied' (token lacks access to channel_id).
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id. Get it from list_channels (e.g. 'ch-eng'). Required. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description fully carries the burden. It discloses the tool is instant, read-only, has no side effects, returns empty arrays when backend is unavailable (always safe), and lists specific error modes. This is comprehensive behavioral coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into clear sections (purpose, disambiguation, usage, returns, error modes) and all sentences are informative. While slightly lengthy, it earns its length with valuable detail. A minor reduction could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (graph output) and lack of annotations, the description provides thorough context including output format (Cytoscape-format), behavior on unavailable backend, and error scenarios. Output schema exists, but the description still adds valuable detail about edge/node structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (channel_id) with 100% schema description coverage. The description adds minor context (mentioning source list_channels) but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a wiki page-link graph as a node/edge map. It distinguishes from the knowledge graph (use search_relationships) and other wiki tools like read_wiki_page. The verb 'return' and resource 'wiki page-link graph' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use the tool (visualizing/navigating wiki structure, finding clusters) and when not to (reading page content, querying entity relationships, with alternatives named). It also lists prerequisite channel_id from list_channels.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one pre-compiled wiki page from the LEGACY fixed-page set (overview, faq, decisions, people, glossary, activity, topics). Call it for a fast, whole-channel summary keyed by a fixed page_type.
Disambiguation: this is the legacy fixed-page surface. For the redesigned slug-keyed wiki — arbitrary topic/entity pages, structured kind payloads, and the cross-link graph — use list_wiki_pages to discover pages then read_wiki_page(slug=...). Prefer those for anything beyond the seven fixed pages above.
When to use: you want a quick structured summary of a known aspect of a channel without running the QA pipeline. When NOT to use: you need a specific answer (use ask_channel) or a non-fixed wiki topic (use read_wiki_page).
Prerequisites: a channel_id from list_channels.
Returns (instant, read-only): the page dict
{page_type, channel_id, content, summary, text}. content is null
when that page has not been generated yet (run a sync / refresh_wiki
first). No side effects.
Error modes (returned as dicts): 'authentication_missing' (no principal);
'channel_access_denied' (token lacks access to channel_id). Other internal
failures return the page dict with content: null.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id. Get it from list_channels (e.g. 'ch-eng'). Required. | |
| page_type | No | Which fixed page to fetch. One of exactly: 'overview', 'faq', 'decisions', 'people', 'glossary', 'activity', 'topics'. Default 'overview'. | overview |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Returns (instant, read-only): ... No side effects.' and describes error modes as dicts with examples. It also clarifies that content can be null if the page hasn't been generated, which is crucial behavioral context. Since no annotations are provided, the description fully compensates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (disambiguation, when to use/not use, prerequisites, return format, error modes). While slightly verbose, each sentence adds value and the structure aids comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking annotations and having a complex context with sibling tools, the description is complete. It covers purpose, usage boundaries, return format (with output schema referenced), error modes, and prerequisites. The null content behavior is explicitly documented, leaving no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters with thorough descriptions (channel_id required, page_type enum with defaults). The description adds minimal additional meaning beyond restating the enum values and default. With 100% schema coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and specifies the resource: 'one pre-compiled wiki page from the LEGACY fixed-page set (overview, faq, decisions, people, glossary, activity, topics)'. It explicitly lists the seven fixed page types, distinguishing this tool from sibling tools like read_wiki_page which handles slug-keyed wiki pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: use for 'a quick structured summary of a known aspect of a channel without running the QA pipeline', and not to use when needing a specific answer (use ask_channel) or non-fixed wiki topic (use read_wiki_page). It also mentions the prerequisite channel_id from list_channels, and notes that content is null if page not generated (run refresh_wiki first).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit a channel's wiki for health problems and return a list of findings. Call it to check whether wiki pages are stale, orphaned, duplicated, or internally inconsistent before relying on them or recommending a refresh.
When to use: validating wiki quality, or diagnosing why an answer looked wrong. When NOT to use: routine reading (use read_wiki_page / list_wiki_pages) — linting is heavier. Set run_coherence_check=false to avoid the per-page LLM cost when you only need structural checks.
Prerequisites: a channel_id from list_channels.
Returns (long-running when run_coherence_check=true — one LLM call per
page; read-only, writes nothing): {findings: [{severity, category, page_id, section_id, message, suggested_action}, ...], pages_scanned: N}.
Error modes (returned as dicts): 'authentication_missing' (no principal);
'channel_access_denied' (token lacks access to channel_id);
'lint_failed' (returned as {findings: [], error: 'lint_failed'} on an
internal lint error).
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id whose wiki to lint. Get it from list_channels (e.g. 'ch-eng'). Required. | |
| target_lang | No | Optional BCP-47 language tag to lint (e.g. 'en'). Omit to lint the channel's primary language. Default null (treated as 'en'). | |
| run_coherence_check | No | If true, also run the LLM coherence pass (one model call per page — slower and incurs token cost). Set false for a fast structural-only lint. Default true. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavior beyond annotations (none provided): read-only operation ('writes nothing'), potential long runtime when run_coherence_check=true, and error modes. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded purpose, usage, params, return, and errors. Each section serves a purpose, though slightly lengthy. Minor redundancy with schema descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Outlines return format with example structure, lists error modes, and prerequisites. Sufficient for an agent to understand what to expect and how to handle outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; description rephrases parameter info but adds little new meaning. For run_coherence_check, the description echoes the schema's cost/latency note. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Audit a channel's wiki for health problems' with specific verb and resource. Differentiates from siblings by explicitly mentioning not to use for routine reading (use read_wiki_page/list_wiki_pages).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (validating wiki quality, diagnosing wrong answers) and when-not-to-use (routine reading, heavier linting). Includes prerequisite (channel_id) and best practice (run_coherence_check=false to avoid cost).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the channels the bot can actually read on one connection — the ground-truth source for what channels exist and their indexing state.
Call this after list_connections/whoami (you need a valid
connection_id), once per connection you care about, BEFORE any retrieval
tool (ask_channel, search_channel_facts, get_wiki_page, ...) so
you can pass a real channel_id. Prefer this over
list_connections.selected_channel_count — that count is a sync pick-list,
not the channel inventory.
Latency: instant for cached results; may take a few seconds when it queries the live platform bridge. Read-only — does not trigger a sync.
Returns {"channels": [<entry>, ...]} (empty list if none/bridge error).
Each entry:
channel_id (str): pass to retrieval/sync tools, e.g. "C0A955E29MX".
name (str): display name, e.g. "engineering".
platform (str): e.g. "slack", "discord", "file".
last_sync_ts (str|null): ISO timestamp of last index, null if never.
sync_status (str): "synced", "never_synced", or "n/a" (file
connections). "never_synced" is normal and does NOT mean the channel is
inaccessible — it just is not indexed yet; call trigger_sync(channel_id)
to ingest it before querying its content.
message_count_estimate (int|null): approx synced messages, null if
not yet synced.
Scoping: matches the dashboard "CONNECTED" view. If the user picked specific channels for sync, those are returned; otherwise every channel where the bot is a member (and thus can read) is returned. File connections return every uploaded file.
Error modes: {"error": "connection_access_denied", "connection_id": ...}
if you do not own the connection (existence is not leaked);
{"error": "invalid_parameter", "parameter": "connection_id"} for a
malformed id; {"error": "authentication_missing"} if no principal.
| Name | Required | Description | Default |
|---|---|---|---|
| connection_id | Yes | Id of the connection whose channels to list, obtained from list_connections or whoami. Format: alphanumeric/_/:/- up to 128 chars. Example: "conn_abc123". |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses read-only nature (no sync trigger), latency characteristics, error modes, return format with field descriptions, and scoping rules. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections for latency, return format, field descriptions, scoping, and error modes. Every sentence serves a purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema provided, the description fully documents the return object structure, field meanings, and error responses. It covers all necessary context for a tool with one required parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with description for connection_id. The description adds context on where to obtain the parameter (list_connections/whoami) and format requirements, adding value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it lists channels the bot can read on one connection, serving as ground-truth source. It distinguishes from sibling tools like list_connections and ask_channel by specifying it provides the channel_id needed for retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides precise when-to-call instructions: after list_connections/whoami, before retrieval tools, once per connection. Also recommends preferring this over list_connections.selected_channel_count and explains why.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the platform connections (Slack workspaces, Discord servers, file imports, etc.) this principal owns, with each connection's metadata.
Use this when you need a connection's platform, status, or sync metadata —
not just its id. If you only need the connection ids, whoami is cheaper.
After picking a connection here, call list_channels(connection_id) to see
its actual channels. Results are ownership-filtered: you only see your own.
Latency: instant (read-only; no sync triggered).
Returns {"connections": [<entry>, ...]} (empty list if none). Each entry:
connection_id (str): e.g. "conn_abc123" — pass to list_channels.
platform (str): e.g. "slack", "discord", "file".
display_name (str): human label, e.g. "Acme Workspace".
status (str): connection health, e.g. "connected".
last_synced_at (str|null): ISO timestamp of the most recent sync of a
PICKED channel; null when the pick-list is empty (see caveat below).
selected_channel_count (int): size of the sync pick-list (see caveat).
source (str): how the connection was created, e.g. "oauth".
Caveats (do NOT misread): selected_channel_count is the user's opted-in
sync pick-list, NOT how many channels exist. A value of 0 does not mean
the connection is empty — a Slack workspace with 0 picks can still have
dozens of bot-readable channels. last_synced_at is scoped to the same
pick-list, so an empty pick-list yields null even if channels were synced
another way. For ground-truth channel availability, always call
list_channels(connection_id) — never infer it from these counts.
Error modes: returns {"error": "authentication_missing"} when no valid
principal is attached. Never raises access-denied (output is self-scoped).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: ownership-filtered results, read-only instant latency, error modes (authentication_missing), and important caveats about selected_channel_count and last_synced_at to prevent misinterpretation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: purpose, usage, output fields, caveats, errors. All sentences add value, though could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Thorough coverage: return format, field descriptions, caveats, error handling, and usage flow. No gaps given the tool simplicity (no params, explicit output schema described).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description adds no parameter info. Baseline 4 as per calibration for 0-param tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists platform connections owned by the principal, with specific verb ('list') and resource ('connections'). It distinguishes itself from sibling tools like 'whoami' and 'list_channels' by specifying when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (need metadata beyond id) and when not (use whoami for just ids). Provides next step after picking a connection (call list_channels). Gives clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the wiki pages in one channel as lightweight summaries (no page bodies). The RECOMMENDED first call when exploring the redesigned slug-keyed wiki: use it to discover slugs, then fetch a page with read_wiki_page(slug=...).
When to use: browsing or discovering which pages exist, or finding a slug. When NOT to use: you already know the slug and want the body (call read_wiki_page directly).
Prerequisites: a channel_id from list_channels.
Returns (instant, read-only): {channel_id, target_lang, scope, pages: [{slug, title, kind, version, last_updated, pinned, hidden}, ...]}. The
content_md body is intentionally omitted to keep the payload bounded
— follow up with read_wiki_page(slug=...) for a page's content. No side
effects.
Error modes (returned as dicts): 'authentication_missing' (no principal); 'channel_access_denied' (token lacks access to channel_id); 'wiki_list_failed' (internal error).
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id. Get it from list_channels (e.g. 'ch-eng'). Required. | |
| kind | No | Optional kind filter. One of: 'topic', 'entity', 'decisions', 'faq', 'action_items'. Omit for all kinds. Default null. | |
| scope | No | Visibility scope. 'human' (default) excludes hidden + merged pages; 'all' returns everything but requires the read:hidden_pages token scope (otherwise it silently downgrades to 'human'). | human |
| target_lang | No | BCP-47 language tag (e.g. 'en', 'fr'). Default 'en'. | en |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description fully covers behavior: read-only, no side effects, returns specific fields, omits content_md intentionally, and details error modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with distinct sections for purpose, usage, returns, errors; no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a listing tool with 4 parameters, described output schema, error modes, and prerequisites; no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds significant value by explaining scope's downgrade behavior, kind filter values, and target_lang default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists wiki pages as lightweight summaries without page bodies, and distinguishes from read_wiki_page which retrieves the body.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (browsing, discovering slugs) and when not to use (when slug is known and body needed), and lists prerequisite (channel_id from list_channels).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trace ONE fact back to the original chat message it was extracted from. Call it to verify or cite a fact — given a fact_id from another tool, it returns where the fact came from (platform, message, author, timestamp, and the raw message text when reachable).
When to use: confirming a fact's source, building a citation, or auditing provenance. Prerequisites: a fact_id surfaced by find_facts, find_decisions, search_channel_facts, search_memory, or an ask_channel citation.
Returns (instant, read-only): {fact_id, memory_text, source: {platform, message_id, url, author, ts}, raw_message}. raw_message is the
original chat body, or an empty string if the source message is no longer
reachable — every other field is still populated in that case. No side
effects.
Error modes (returned as dicts): 'authentication_missing' (no principal); 'fact_not_found' (unknown fact_id — also returned, deliberately, when the caller lacks access to the fact's channel, so cross-tenant existence is never leaked); 'provenance_read_failed' (internal error).
| Name | Required | Description | Default |
|---|---|---|---|
| fact_id | Yes | Fact id to trace, as returned in the ``fact_id`` field of another tool's result (e.g. 'fact_abc123' from find_facts, find_decisions, search_channel_facts, or ask_channel citations). Required. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It describes return format, instant and read-only nature, no side effects, and details error modes including privacy-preserving behavior for cross-tenant access. Exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections for purpose, when-to-use, prerequisites, return format, and errors. Every sentence is informative with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity, description provides full coverage: purpose, usage guidelines, prerequisites, return format with details, error modes, and behavioral traits. Very complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter fact_id is well-described in schema. Description adds value by specifying that fact_id comes from other tools' fact_id field and listing example tools, which aids correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Trace ONE fact back to the original chat message it was extracted from' with a specific verb and resource. It distinguishes from siblings like find_facts and trace_decision_history by focusing on provenance of a single fact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'confirming a fact's source, building a citation, or auditing provenance' and lists prerequisites (fact_id from specific tools). Missing explicit when-not, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch ONE structured module from a wiki page without downloading the whole page. Call it when you already know the page slug and the module anchor you want, and reading the full page via read_wiki_page would waste tokens.
When to use: you need just one module's structured data (e.g. the key_facts items, or a decision_banner's rationale + alternatives). When NOT to use: you need a narrative prose section (use read_wiki_section) or the whole page (use read_wiki_page). To learn a page's module anchors, read it once with read_wiki_page first.
Prerequisites: a channel_id (list_channels), a page_slug (list_wiki_pages), and an anchor (from the page's modules).
Returns (instant, read-only): {channel_id, page_slug, anchor, module_id, data} where data is the module's structured payload.
No side effects.
Error modes (returned as dicts): 'authentication_missing' (no principal); 'channel_access_denied' (token lacks access to channel_id); 'wiki_page_not_found' (no such slug); 'module_not_found' (page exists but has no module with that anchor); 'wiki_module_read_failed' (internal error).
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id. Get it from list_channels (e.g. 'ch-eng'). Required. | |
| page_slug | Yes | Slug of the page hosting the module (e.g. 'auth-architecture'). Discover slugs via list_wiki_pages. Required. | |
| anchor | Yes | Module anchor — the stable in-page id of one structured module (e.g. 'key-facts', 'decision-banner', 'tension-callout'). Discover the available anchors by reading the page once with read_wiki_page. Required. | |
| target_lang | No | BCP-47 language tag (e.g. 'en', 'fr'). Default 'en'. | en |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explicitly states 'Returns (instant, read-only): ... No side effects.' and lists all error modes in detail. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (summary, when to use/not, prerequisites, returns, error modes). It is concise and front-loaded with the key purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters (3 required), 100% schema coverage, and output schema described, the description covers all necessary aspects including error modes. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, baseline 3. The description adds context beyond schema by explaining how to obtain parameters (e.g., 'Get it from list_channels', 'Discover slugs via list_wiki_pages') and the purpose of 'anchor'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Fetch ONE structured module from a wiki page without downloading the whole page.' This is a specific verb (fetch) and resource (structured module), and it distinguishes from sibling tools like read_wiki_page and read_wiki_section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use and when-not-to-use guidance, including alternatives (read_wiki_section, read_wiki_page). It also lists prerequisites and how to discover parameters (channel_id, page_slug, anchor).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read ONE full wiki page by its slug from the redesigned slug-keyed wiki. Call it after list_wiki_pages tells you which slug you want, to get a page's complete content and structured payload.
Disambiguation: this is the slug-keyed redesign surface (arbitrary topic/entity pages). For the seven LEGACY fixed pages (overview, faq, decisions, ...) use get_wiki_page(page_type). Typical sequence: list_wiki_pages -> read_wiki_page(slug). To save tokens when you need only a slice, use read_wiki_module (one module) or read_wiki_section (one narrative section) instead of the whole page.
Prerequisites: a channel_id from list_channels and a slug from list_wiki_pages.
Returns (instant, read-only): the full WikiPage document including
content_md (markdown body), kind + kind_schema (structured
payload agents can iterate without re-parsing markdown), cross_links
(title->slug), cross_links_broken (linked titles with no page yet),
pin_state, and last_updated. Hidden pages are excluded unless the
token carries the read:hidden_pages scope. No side effects.
Error modes (returned as dicts): 'authentication_missing' (no principal); 'channel_access_denied' (token lacks access to channel_id); 'wiki_page_not_found' (no such slug, or it is hidden and the token lacks read:hidden_pages); 'wiki_read_failed' (internal error).
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id. Get it from list_channels (e.g. 'ch-eng'). Required. | |
| slug | Yes | Page slug — the stable identifier of the page (e.g. 'auth-architecture'). Discover valid slugs with list_wiki_pages. Required. | |
| target_lang | No | BCP-47 language tag for the rendered page (e.g. 'en', 'fr'). Default 'en'. | en |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully covers: read-only, no side effects, returns full WikiPage document with fields (content_md, kind, cross_links, etc.), excludes hidden pages unless scoped, and lists four error modes. Very transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: purpose, disambiguation, prerequisites, returns, error modes. Front-loaded with main action. Slightly lengthy but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description still provides key return fields, prerequisites, error modes, and ties with sibling tools. Covers all needed context for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions, so baseline is 3. Description adds value by linking parameters to prerequisites (channel_id from list_channels, slug from list_wiki_pages) and specifying default for target_lang.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads a full wiki page by slug from the redesigned slug-keyed wiki. It distinguishes from siblings like get_wiki_page (legacy fixed pages) and read_wiki_module/section (partial reads).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call after list_wiki_pages, before read_wiki_module/section if full page needed. Disambiguates from get_wiki_page and lists prerequisites (channel_id, slug).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch ONE narrative (prose) section of a wiki page without loading the whole page. Call it when you know the page slug and section anchor and want just that article slice, to save tokens.
Disambiguation: read_wiki_section returns PROSE sections (paragraphs + citations); read_wiki_module returns a STRUCTURED module payload (key_facts, decision_banner, etc.); read_wiki_page returns the whole page. Use find_facts for fact-text search across pages.
Prerequisites: a channel_id (list_channels), a page_slug (list_wiki_pages), and an anchor (from the page's narrative sections).
Returns (instant, read-only): {anchor, heading, paragraphs, citations, visual, page_slug, page_title, channel_id} — page_title and
channel_id are included so you can attribute the section without a
second call. No side effects.
Error modes (returned as dicts): 'authentication_missing' (no principal);
'channel_access_denied' (token lacks access to channel_id);
'page_not_found' (no such slug); 'section_not_found' (page exists but lacks
the anchor — the result lists available_anchors to retry with);
'narrative_not_available' (page has no narrative sections — includes
has_modules and a suggestion to use read_wiki_page for module data);
'internal_error'.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id. Get it from list_channels (e.g. 'ch-eng'). Required. | |
| page_slug | Yes | Slug of the page hosting the section (e.g. 'auth-architecture'). Discover slugs via list_wiki_pages. Required. | |
| anchor | Yes | Section anchor — kebab-case in-page id of one narrative section (e.g. 'context', 'alternatives', 'implications'). If you don't know it, a 'section_not_found' error lists the available anchors. Required. | |
| target_lang | No | BCP-47 language tag (e.g. 'en', 'fr'). Default 'en'. | en |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It declares it is 'instant, read-only' with 'no side effects'. Lists error modes and return fields comprehensively, providing full behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear paragraphs: purpose, disambiguation, prerequisites, return signature, error modes. Every sentence adds value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters (3 required), 100% schema coverage, and an output schema (return fields listed), the description covers all necessary context: prerequisites, error handling, return format, and usage guidance. Fully complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds context: anchor is 'kebab-case in-page id' and mentions error handling for unknown anchors; target_lang default noted. Provides extra guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch ONE narrative (prose) section' and specifies the resource. It distinguishes from siblings read_wiki_module, read_wiki_page, and find_facts by explaining what each returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use: 'when you know the page slug and section anchor and want just that article slice, to save tokens.' Includes disambiguation with siblings and prerequisites (channel_id, page_slug, anchor) with source tools listed in parentheses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-render a channel's pre-compiled wiki pages (overview, FAQ, decisions, etc.) from facts ALREADY ingested into the knowledge base. Use this to rebuild stale wiki content; the refreshed pages are then read with get_wiki_page / read_wiki_page / list_wiki_pages. It does NOT ingest new messages — that is trigger_sync's job — and it does NOT answer questions (use the retrieval tools for that).
WHEN TO USE: after a sync has added new facts (i.e. after trigger_sync completes), or when the user explicitly asks to regenerate the wiki. WHEN NOT TO USE: do not call routinely — the standard sync pipeline already rebuilds wiki pages automatically, so calling this after a normal sync is usually redundant.
PREREQUISITES: a valid channel_id from list_channels; the channel must have ingested facts (run trigger_sync first if it has none); the calling principal must have access.
LATENCY & SIDE EFFECTS: asynchronous and expensive (runs an LLM generation pass). Returns within ~5s with a job envelope while generation runs in the background; this WRITES/overwrites the channel's wiki pages. Shape: {job_id: 'job_def456', status_uri: 'atlas://job/job_def456', status: 'queued'}. Track progress with get_job_status(job_id) or the atlas://job/ resource.
ERROR MODES (returned as {error: ...}, never raised): 'authentication_missing'; 'invalid_parameter' (malformed channel_id); 'channel_access_denied'; 'cooldown_active' (refreshed too recently; includes retry_after_seconds); 'service_unavailable' (includes service); 'internal_error'.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel whose wiki pages to regenerate, e.g. 'ch_eng_backend'. Get it from list_channels. Required. | |
| page_types | No | Subset of wiki page types to regenerate, e.g. ['overview', 'faq']. Valid values: 'overview' | 'faq' | 'decisions' | 'people' | 'glossary' | 'activity' | 'topics'. Default None, which regenerates ALL page types. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses asynchronous nature, latency, side effects (writes/overwrites), response shape, error modes, and tracking method.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, but slightly verbose. Every sentence adds value, so no wasteful text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: prerequisites, latency, side effects, error modes, output schema shape, and tracking. Complete for an async, expensive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema by describing channel_id as required and page_types as optional with default behavior and listing valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Re-render' and resource 'wiki pages' and explicitly distinguishes from sibling tools like trigger_sync and retrieval tools by stating what it does NOT do.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections, including specific scenarios (after trigger_sync, explicit user request) and cautions against routine calls. Also lists prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find SPECIFIC facts in ONE channel by hybrid (BM25 + vector) search and return them as raw, ranked rows. Call it when you want the cited source facts themselves, not a composed answer.
When to use: targeted lookup of facts in a known channel ("find facts about the postgres migration"). Faster and more precise than ask_channel for retrieval-only tasks.
When NOT to use: you need a synthesized answer with reasoning (use ask_channel); you don't know which channel holds the facts (use search_memory, which fans this same search across every accessible channel); you want a deterministic substring match rather than ranked relevance (use find_facts).
Prerequisites: a channel_id from list_channels.
Returns (instant, read-only): {facts: [{text, author, timestamp, permalink, channel_id, confidence, topic_tags}, ...]}. No side effects.
Error modes (returned as dicts): 'authentication_missing' (no principal);
'channel_access_denied' (token lacks access to channel_id). On any other
internal failure it returns an empty {facts: []} rather than erroring.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id to search. Get it from list_channels (e.g. 'ch-eng'). Required. | |
| query | Yes | Search query, keyword or natural phrase (e.g. 'postgres migration'). Matched with BM25+vector hybrid retrieval. Required. | |
| time_scope | No | Time window. 'any' = all facts (default), 'recent' = last 30 days only. | any |
| limit | No | Max facts to return, 1-50 (values outside the range are clamped). Default 10. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully carries the burden. It discloses read-only nature, no side effects, return structure, error modes (authentication, access denial), and that internal failures return empty facts rather than erroring. Complete transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into distinct sections (purpose, when/not to use, prerequisites, returns, error modes). Every sentence adds value; no redundancy or fluff. Ideal length for an actionable tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description correctly limits return value explanation to a sample structure. Covers prerequisites, error handling, and behavioral nuances. Completely addresses the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal parameter semantics beyond the schema (e.g., restates channel_id from list_channels). No additional constraints or format details. Adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool finds 'SPECIFIC facts in ONE channel by hybrid (BM25 + vector) search' and returns raw ranked rows. It clearly distinguishes from siblings like ask_channel and search_memory by scope and output type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use ('targeted lookup of facts in a known channel') and when-not-to-use for synthesized answers (ask_channel), unknown channels (search_memory), or substring match (find_facts). Explicitly lists alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DEPRECATED — do not call. This is a compatibility shim for the retired 'search_channel_knowledge' tool. Use 'ask_channel' for natural-language questions answered with citations, or 'search_channel_facts' for targeted keyword+vector fact search within one channel. Calling this always returns a structured {"error": "tool_renamed", "replacement": [...]} payload and performs no work (no backend call, exempt from rate limiting).
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | No | ||
| query | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. It fully discloses that the tool always returns a structured error payload, performs no backend call, and is exempt from rate limiting. This is comprehensive behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise paragraph with front-loaded 'DEPRECATED — do not call.' Every sentence adds value: purpose, replacements, and behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple deprecated nature, the description is complete. It covers what the tool does, what it returns, and alternatives. The existence of an output schema is noted but description doesn't need to repeat it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 2 parameters with no descriptions and 0% coverage. Description does not add meaning to parameters, but since the tool always returns the same error regardless of parameters, the lack of semantic explanation is acceptable. The implicit understanding that parameters are ignored is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is deprecated and a compatibility shim, with a specific purpose of returning an error directing to replacements. It distinguishes itself from siblings by explicitly naming replacements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'DEPRECATED — do not call' and provides two specific replacement tools. Also explains that calling it returns an error and does no work, giving clear when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find messages that SHARED a file, image, PDF, or link in one channel. Call it when the user is hunting for an attachment or URL ("where's the design doc", "find the screenshot Alice posted") rather than for the knowledge in the text.
When to use: locating shared documents, images, or links. When NOT to use: general fact/knowledge search (use search_channel_facts or ask_channel) — this tool only returns messages that carry media.
Prerequisites: a channel_id from list_channels.
Returns (instant, read-only): {media: [{text, media_urls, link_urls, link_titles, author, timestamp, media_type, fact_id}, ...]}. No side
effects.
Error modes (returned as dicts): 'authentication_missing' (no principal);
'channel_access_denied' (token lacks access to channel_id). Other internal
failures return an empty {media: []}.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel id. Get it from list_channels (e.g. 'ch-eng'). Required. | |
| query | Yes | Search query describing the media you want (e.g. 'architecture diagram' or 'pricing pdf'). Required. | |
| media_type | No | Optional media-type filter. One of: 'image' (photos/screenshots), 'pdf' (documents), 'link' (URLs), or null for all. Default null. | |
| limit | No | Max results, 1-20 (out-of-range values are clamped). Default 5. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavior: it's instant, read-only, no side effects, and specifies the return format (including example) and error modes. This covers all necessary behavioral traits for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, when to use, prerequisites, returns, errors). It is comprehensive but slightly lengthy; however, every sentence adds value, so it earns a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the description includes a return format example, error modes, and prerequisites, the description is fully complete. It provides all necessary context for an agent to use the tool correctly without missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond what the schema already provides for each parameter. It repeats the prerequisite context for channel_id but does not enhance parameter understanding further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Find messages that SHARED a file, image, PDF, or link in one channel.' It distinguishes itself from sibling tools by specifying what it does (media attachment search) versus general knowledge search, and uses specific verbs and resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'When to use' (locating shared files/images/links) and 'When NOT to use' (general fact/knowledge search, with named alternatives like search_channel_facts or ask_channel). Also mentions prerequisite: channel_id from list_channels.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find facts ACROSS MANY channels by hybrid (BM25 + vector) search when you do NOT know which channel holds the answer. Call it first for broad recall, then drill into a specific channel with the tools below.
Routing rule for the three search tools:
search_memory(scope='all') — unknown channel; fans the search across every channel the principal can access and merges/ranks the hits.
search_channel_facts(channel_id) — known channel; same hybrid search, scoped to one channel, returning the richer per-fact shape.
search_memory(scope='channel:') — single channel with the search_memory hit shape (use search_channel_facts instead if you want author/permalink/topic_tags on each row). For a synthesized ANSWER rather than rows, use ask_channel.
Prerequisites: none for scope='all'; a channel_id (from list_channels) for scope='channel:'.
Returns (instant for one channel, longer when fanning across many;
read-only): {hits: [{fact_id, text, score, channel_id, cluster_id, entity_tags}, ...], query: <echo of query>} ranked by hybrid score.
No side effects.
Error modes (returned as dicts): 'authentication_missing' (no principal); 'invalid_parameter' (empty/over-4000-char query, or scope not 'all'/ 'channel:'); 'channel_access_denied' (only for an explicit 'channel:' the token cannot reach — under scope='all' unreachable channels are silently skipped).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query, keyword or natural phrase, 1-4000 chars (e.g. 'who owns billing'). Longer queries return error 'invalid_parameter'. Required. | |
| scope | No | Search scope. 'all' (default) = every channel the principal can access; 'channel:<id>' = one channel only (e.g. 'channel:ch-eng'). | all |
| limit | No | Max hits across the merged result set, 1-50 (out-of-range values are clamped). Default 20. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only behavior, no side effects, performance hints (instant vs longer), error modes as dicts, and return shape. With no annotations provided, the description fully covers behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and code blocks. Every sentence adds value. Front-loaded with core function and usage note. Routing rule is efficiently presented.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers prerequisites, behavior, returns, error modes, and performance. With output schema present, description is complete for a complex tool with multiple scopes and error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond schema: query length constraint with error, scope options with examples, limit clamping. All three parameters are elaborated with context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Find facts ACROSS MANY channels by hybrid search' when channel is unknown. It distinguishes from siblings like search_channel_facts and ask_channel, providing a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a detailed routing rule for three search tools, explaining when to use each. Includes prerequisites and explicit guidance: 'Call it first for broad recall, then drill into a specific channel'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find how named ENTITIES connect in a channel's knowledge graph.
Call this to answer "how is X related to Y?" or "what touches the
billing service?" by returning the subgraph of nodes and edges
around the given entities. This explores the KNOWLEDGE graph of
entities/relationships — distinct from get_wiki_graph, which
returns the wiki PAGE-LINK graph (which wiki pages reference which).
Use find_experts to rank people and trace_decision_history
to follow decision supersession.
Prerequisite: a channel_id from list_channels and at least
one entity name. Names should match how the channel refers to the
entity; unknown names simply yield an empty subgraph.
Returns (instant for small hop counts, read-only, no side effects):
{"nodes": [...], "edges": [...], "text": str, "entities_searched": [...]}. Each node has name and type
(e.g. 'person', 'system', 'concept'); each edge has source,
target, type (relationship label), confidence (0–1,
extraction confidence), and context (snippet explaining the
edge). text is a human-readable summary. Empty nodes/
edges means no connections were found — not an error.
Error modes: {"error": "authentication_missing"} if
unauthenticated; {"error": "channel_access_denied", "channel_id": ...} if the channel is not readable; {"error": "invalid_parameter", ...} for a malformed channel_id. Other
backend failures degrade to {"nodes": [], "edges": [], "channel_id": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Required. The channel id to search within, obtained from list_channels (e.g. 'ch-eng'). Not a human channel name. | |
| entities | Yes | Required. One or more entity NAMES to connect, e.g. ['Postgres', 'billing-service'] or ['Dana']. These are knowledge-graph node names (people, systems, concepts), not channel ids. Provide at least one; provide two+ to find paths between them. | |
| hops | No | How many graph edges to traverse out from the entities. Range 1–4, default 2. Larger values return wider but noisier subgraphs and are slower. Out-of-range values are silently clamped (e.g. 9 -> 4). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavior: read-only, no side effects, instant for small hops, return structure, error modes, clamping of hops. It leaves no ambiguity about what happens in various scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections and bullets, but slightly verbose. However, every sentence adds value and the information is front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (graph search) and no output schema provided, the description fully covers prerequisites, usage, return format, error handling, and edge cases (empty results, clamping). It is sufficiently complete for correct agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds significant context beyond the schema: how to obtain channel_id, that entities are names (not IDs), hops clamping, and typical values. This helps the agent use parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find how named ENTITIES connect in a channel's knowledge graph.' It uses specific verbs and resource, and explicitly distinguishes from sibling tools like 'get_wiki_graph' by contrasting knowledge graph vs. wiki page-link graph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage contexts ('to answer how is X related to Y?'), prerequisites (requires channel_id from list_channels and entity names), and behavior for missing entities (empty subgraph). Also mentions alternative tools for different tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mint a fresh conversation session id that starts a new ask_channel thread.
Call this to begin a clean conversation that carries no memory of prior
ask_channel turns — e.g. when the user switches to an unrelated topic
or explicitly asks to "start over" / "forget previous context". Pass the
returned id as the session_id argument on subsequent ask_channel
calls so they share one continuous thread; reuse the same id for
follow-ups, and mint a new one only when you want a clean break.
When NOT to use: do not call this before every question. ask_channel
auto-creates a session when session_id is omitted, so a new session
id is only needed to intentionally drop earlier conversation context.
Prerequisites: none. Requires an authenticated MCP principal (the caller's
connection token); no channel_id or other input is needed.
Returns: a dict {"session_id": "mcp:<principal>:<short>"} where the
value is a fresh opaque conversation handle scoped to the caller, e.g.
{"session_id": "mcp:conn_abc123:9f3c1a2b"}. On a missing or invalid
principal it returns {"error": "authentication_missing"} instead.
Side effects: none — this allocates a new conversation boundary marker and does not delete, persist, or mutate any stored data. Latency: instant (no network or LLM call); safe to call synchronously inline.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes side effects (none), latency (instant), safety (safe synchronous call), return format with example, and error case. Since no annotations are present, the description fully handles behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: purpose first, then usage, prerequisites, returns, side effects. Every sentence adds unique value; no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no params and presence of output schema (context signal), description covers all needed context: purpose, usage conditions, prerequisites, return value with example and error, side effects. Complements sibling tool ask_channel effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist in input schema, so schema coverage is 100%. With 0 parameters, the baseline is 4; description adds no param info but provides return value semantics as a bonus.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Starts with verb 'Mint' and resource 'fresh conversation session id', clearly stating the action and output. Distinguishes from sibling tool 'ask_channel' by explaining it starts a new thread for a clean break.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use (unrelated topic, start over) and when NOT to use (before every question, noting auto-creation by ask_channel). Prerequisites and authentication requirement are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reconstruct how a decision EVOLVED over time in a channel.
Call this to answer "how did the team arrive at the current approach
for X?" or "what earlier choices were overridden?" It walks
SUPERSEDES edges in the knowledge graph to build an ordered
timeline of superseded → current decisions. Distinct from
find_decisions (which lists current decision facts with no
history) and search_channel_facts (current state only, no
chronology); use this tool specifically when you need the
chronological "why we changed" trail.
Prerequisite: a channel_id from list_channels. Best results
on mature channels where decisions have been revised; new channels
often have no supersession chain yet (empty result, not an error).
Returns (instant, read-only, no side effects):
{"decisions": [...]} ordered oldest → newest. Each item has
entity (the decision that was made), superseded_by (the
decision that replaced it, or empty for the current one),
relationship (edge label, typically 'SUPERSEDES'),
confidence (0–1 extraction confidence), context (snippet
explaining the change), and position (0-based index in the
timeline). An empty list means no recorded supersession chain.
Error modes: {"error": "authentication_missing"} if
unauthenticated; {"error": "channel_access_denied", "channel_id": ...} if the channel is not readable; {"error": "invalid_parameter", ...} for a malformed channel_id. Other
backend failures degrade to {"decisions": []}.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Required. The channel id to trace within, obtained from list_channels (e.g. 'ch-eng'). Not a human channel name. | |
| topic | Yes | Required. The decision area to trace, e.g. 'database choice', 'API versioning', 'auth provider'. Matched against decision entities in the knowledge graph; use the subject of the decision, not a yes/no question. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavior: it declares the operation as 'instant, read-only, no side effects,' describes the exact return format including fields like `entity`, `superseded_by`, `relationship`, `confidence`, `context`, `position`, and lists all error modes (authentication, access denied, invalid parameter). It also explains that empty list means no supersession chain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, when to call, distinction from siblings, prerequisites, return format, and errors. Every sentence adds essential information, and it is front-loaded with the key use case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 params, no enums, with output schema), the description covers all necessary context: purpose, usage, behavior, return format, and error modes. The output schema exists, so the description's detailed field explanation is supplementary and complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions, but the tool description adds significant value: for `channel_id`, it specifies the source (list_channels) and warns it's not a human name; for `topic`, it provides examples and cautions against yes/no questions. This extra context enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Reconstruct how a decision EVOLVED over time in a channel.' It uses a specific verb ('reconstruct') and resource ('decision evolution over time'), and explicitly distinguishes from sibling tools `find_decisions` and `search_channel_facts` by contrasting their scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'answer how did the team arrive at the current approach for X?' and when-not-to-use: 'for current decision facts use find_decisions, for current state use search_channel_facts.' It also includes a prerequisite (channel_id from list_channels) and notes that empty results are normal for new channels.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest a chat channel's messages into the Atlas knowledge base so they become searchable by the retrieval tools (ask_channel, search_channel_facts, search_memory). This is the WRITE/ingestion entry point; it does NOT answer questions — use the retrieval tools for that. It is distinct from refresh_wiki, which only re-renders wiki pages from already-ingested facts.
WHEN TO USE: only when the user EXPLICITLY asks to sync/refresh a channel, OR when retrieval tools return empty/stale results AND the channel was last synced over 24h ago. WHEN NOT TO USE: do not call before every question or as a precautionary warm-up — prefer the data already indexed. Sync is expensive and rate-limited (cooldown) per channel.
PREREQUISITES: get a valid channel_id (and ideally connection_id) from list_channels first. The calling principal must have access to the channel.
LATENCY & SIDE EFFECTS: asynchronous. Returns within ~5s with a job envelope while ingestion runs in the background; this WRITES facts to the knowledge base. Shape: {job_id: 'job_abc123', status_uri: 'atlas://job/job_abc123', status: 'queued'}. Track progress by calling get_job_status(job_id) or reading the atlas://job/ resource.
IDEMPOTENT: if a queued or running sync already exists for the channel, its existing job_id is returned instead of starting a duplicate. A new job is created only when no active job exists, or after the prior one completed or failed.
ERROR MODES (returned as {error: ...}, never raised): 'authentication_missing' (no principal); 'invalid_parameter' (malformed channel_id/connection_id); 'channel_access_denied' (principal lacks access); 'cooldown_active' (synced too recently; includes retry_after_seconds); 'service_unavailable' (backing service down; includes service); 'internal_error' (unexpected failure).
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel to sync, e.g. 'ch_eng_backend'. Get it from list_channels. Required. | |
| sync_type | No | Sync mode. 'incremental' (default) fetches only messages newer than the last sync (cheap); 'full' re-fetches the entire history (expensive); 'auto' lets the server pick based on sync history. Valid values: 'incremental' | 'full' | 'auto'. | incremental |
| connection_id | No | Platform connection that owns the channel, e.g. 'conn_slack_acme'. Get it from list_channels or list_connections. Default None. Optional but STRONGLY RECOMMENDED when multiple same-platform connections exist (e.g. two Slack workspaces): without it the server matches the channel against each connection's selected_channels pick-list and may mis-route the sync if the channel was never added to a pick-list. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavior: asynchronous (returns job envelope), write side effects, idempotency (returns existing job if queued/running), latency (~5s), error modes (authentication_missing, invalid_parameter, channel_access_denied, cooldown_active, service_unavailable, internal_error), and prerequisite access requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with labeled sections (WHEN TO USE, PREREQUISITES, LATENCY, etc.). Every sentence adds value; no redundancy. Could be slightly more concise, but the structure aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, asynchronous behavior, idempotency, multiple error modes) and the presence of an output schema (described inline), the description covers all necessary dimensions: purpose, usage, parameters, behavior, errors, and return shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant context: channel_id is required, sync_type with practical advice (incremental cheap, full expensive), and connection_id with strong recommendation and explanation of mis-routing risk without it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's primary action ('Ingest a chat channel's messages into the Atlas knowledge base') and differentiates it from retrieval tools ('It does NOT answer questions — use the retrieval tools for that') and sibling 'refresh_wiki' ('distinct from refresh_wiki, which only re-renders wiki pages').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections provide clear guidance: only when explicitly requested or when retrieval results are stale and last sync was >24h ago. Also lists prerequisites (get channel_id from list_channels).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Confirm who you are authenticated as and which connection ids you can reach.
Call this FIRST in any session, before any other tool, to (1) verify your
auth token resolved to a principal and (2) get the connection ids needed by
list_channels. Returns only connection IDS here; use list_connections
when you also need each connection's platform, status, and sync metadata.
When to use: once at session start. Do NOT call repeatedly — the response is stable for the whole session.
Latency: instant (single in-memory/DB lookup; never triggers a sync or job).
Returns a dict:
principal_id (str): your authenticated identity, e.g. "user_42".
connections (list[str]): connection ids you may access, e.g.
["conn_abc123", "conn_def456"]. Empty list if you own no connections.
server_version (str): deployed Atlas version, e.g. "0.1.0".
Error modes: returns {"error": "authentication_missing"} when the request
carries no valid principal (token absent/invalid). No access-denied path —
the response is always scoped to the caller.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses latency ('instant'), scalability ('single in-memory/DB lookup; never triggers a sync or job'), and error modes ('authentication_missing'). Since no annotations are provided, the description fully bears the burden, and it does so comprehensively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into clear sections (purpose, usage, latency, return values, errors). Every sentence is necessary and informative, with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero input parameters, the description covers everything an agent needs: what the tool does, when to use it, what it returns, and how it behaves. It is fully self-contained and handles all context for the 27 sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the baseline is 4. The description adds value by detailing the return schema (principal_id, connections, server_version) and error conditions, going beyond the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a verb ('confirm') and a clear resource ('authentication and connection ids'). It distinguishes itself from sibling 'list_connections' by explaining that 'whoami' returns only connection IDs, while 'list_connections' provides additional metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to 'Call this FIRST in any session, before any other tool' and advises against repeated calls. It also states when to use the alternative 'list_connections', providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.3.0ask_channelfind_decisionsfind_expertsfind_factsget_extraction_statusget_job_statusget_recent_activityget_tensionsget_wiki_graphget_wiki_pagelint_wikilist_channelslist_connectionslist_wiki_pagesread_provenanceread_wiki_moduleread_wiki_pageread_wiki_sectionrefresh_wikisearch_channel_factssearch_channel_knowledgesearch_media_referencessearch_memorysearch_relationshipsstart_new_sessiontrace_decision_historytrigger_syncwhoamiEach tool has a clearly distinct purpose, with descriptions that explicitly contrast similar tools (e.g., find_facts vs. search_channel_facts vs. ask_channel, or read_wiki_page vs. read_wiki_module). Overlapping functionality is minimal and well-documented.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_channels, find_facts, read_provenance). There is no mixing of naming conventions, making the set predictable.
28 tools is on the higher end but appropriate for the server's complex domain (knowledge management with multiple search modes, wiki operations, decision tracking, etc.). The count feels slightly heavy but each tool earns its place.
The tool set covers the full lifecycle: channel discovery, multiple retrieval methods, wiki management (both legacy and redesigned), decision history, tensions, experts, media search, relationship graphs, job tracking, and sync. Obvious gaps (e.g., fact deletion) are intentionally omitted as read-only. The deprecated tool is a minor blemish.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Self-hosted AI-native knowledge workspace with hybrid search, GraphRAG, and MCP.
End-to-end agent-managed company brain. Docs, diagrams, plans, Knowledge Graph. Lean & affordable.
shared AI-context layer for teams — persistent memory your agents search and update over MCP
Governed, auditable knowledge your team curates for its AI assistants, self-hostable
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Beever-AI/beever-atlas'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
