Tribal is an MCP server for semantic memory, enabling agents to store, search, and explore engineering knowledge. Its capabilities include:
Set session context: Declare model identity, provider, and active project.
Ingest knowledge: Submit raw text for asynchronous extraction into structured items (facts, heuristics, procedures, decision records) with duplicate detection and relationship identification.
Discover knowledge: Perform semantic searches with natural language queries, filters (tags, kind, time, project), pagination, and optional evidential profiles.
Explore relationships: Traverse the knowledge graph around an item (supports, contradicts, supersedes, derived-from) with control over direction and depth.
Get items by ID: Directly retrieve specific knowledge items.
Rate retrieval quality: Provide feedback on retrieval sessions to improve future searches.
Check ingest job status: Poll or wait for completion of async ingest jobs.
Manage reindexing: Start, cancel, or prune embedding reindexes to change models or reclaim storage.
Enables the MCP server to use Ollama as a local provider for embeddings and inference, powering semantic compression and graph-based knowledge retrieval.
Enables the MCP server to use OpenAI as a cloud provider for embeddings and inference, powering semantic compression and graph-based knowledge retrieval.
Semantic compression for project knowledge.
Tribal captures the engineering knowledge that does not get written down in code or tickets. The reasoning behind a load-bearing decision, the heuristic someone keeps reaching for, the breakthrough that closed a gnarly bug. It runs as a Model Context Protocol server, ingests text on demand, and exposes a graph of items connected by what they support, contradict, or refine. Your agent harness talks to it the same way it talks to any other MCP tool.
Tribal is not trying to remember everything. It preserves what remains useful after the work is done.
Start with the skills. Tribal runs inside your agent, and the skills teach it to install, verify, wire, and troubleshoot Tribal. Installing them and letting the agent drive is the most reliable path:
npx skills add tribal-memory/skillsThen ask your agent to set Tribal up. The steps below are what the skills walk it through, or what to run by hand. The agent can help either way.
If you plan to use a cloud provider (OpenAI or Anthropic), export its API key in your shell before you launch the agent harness, so the harness and the Tribal binary it spawns inherit it. A key exported into a terminal the harness is already running in is not picked up until you relaunch. Setting it up front removes a lot of the early configuration friction.
Install Tribal using whichever path fits your environment. Pick one:
Homebrew (macOS)
brew install tribal-memory/homebrew-tap/tribalShell installer (macOS or Linux)
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/tribal-memory/tribal/releases/latest/download/tribal-installer.sh | shDocker Compose (bundled Postgres)
tag=$(curl -fsSL https://api.github.com/repos/tribal-memory/tribal/releases/latest | jq -r .tag_name)
mkdir tribal-docker && cd tribal-docker
curl -fsSL "https://raw.githubusercontent.com/tribal-memory/tribal/$tag/docker-compose.yml" -o docker-compose.yml
docker compose upThe compose file pins the image to a specific release, so fetch it from a release tag rather than reusing an old checkout. The stack bundles its own Postgres and bootstraps itself on first start. To point a stage at a cloud provider instead of a local Ollama, configure .env before the first docker compose up; the installing-tribal skill walks through it.
For the Homebrew and shell-installer paths, bootstrap from inside a git repository. This runs setup, registers the repository as a project, mints a bearer token, and prints the MCP config snippet your harness will need:
tribal bootstrapRelated MCP server: longmem
Postgres 14 or higher with the pgvector extension.
A provider for embeddings and inference. Either a local Ollama installation with the required models, or API keys for a supported cloud provider set in your environment.
tribal bootstrap never calls a provider, but it does validate configuration, so a configured cloud provider's API key must already be in your environment when you run it. Provider reachability for ingest is verified separately by tribal check --providers.
tribal bootstrap is the canonical first run. It asks the local manager to initialise the configured database, apply model and graph settings, optionally register a working tree, and ensure a namespaced default credential. It is safe to run again against the same durable state:
tribal bootstrapFlags worth knowing:
--project-path DIRECTORY includes project registration in the bootstrap composition. Omit it when initialising an unscoped deployment.
--transport stdio|http|sse chooses the integration receipt's connection shape. Omission follows the configured transport.
--auth oauth|persisted-bearer selects network authentication. Exporting a bearer is explicit and is not available for stdio.
--json emits a structured JSON record of everything that happened. Useful for scripting and for piping into the diagnostic flow described below.
Bootstrap composes the same typed manager capabilities available under tribal database, tribal project, tribal token, and tribal integration; those commands never open the database or credential store independently.
tribal check runs the core diagnostic suite: configuration, database reachability, migration state, project resolution, token validity, advertised URL reachability, and binary uniqueness on PATH. It exits non-zero if any check fails.
tribal checkAdd --providers to extend the suite with fatal probes of the embedding and inference providers. Run this before your first ingest to confirm the system can do real work:
tribal check --providersFor scripted consumers, --json emits a structured record. Every failed check includes a remediation field with the exact next step:
tribal check --jsonThe canonical MCP config for any compatible harness comes from tribal integration mcp-config. On a local HTTP or SSE deployment the default OAuth document is URL-only. Pass --auth persisted-bearer to make the secret-bearing export explicit for a harness that only supports an Authorization header. The stdio document carries no token and starts explicitly unscoped or with the selected project context.
For per-harness translations, ask your agent to invoke the installing-tribal skill. It walks through wiring Tribal into your harness and produces the exact command to run.
Day-to-day use happens through your harness. Once the MCP server is wired up, the harness can ingest knowledge, query it, traverse the graph, and rate retrieval quality.
The using-tribal skill teaches your harness when and how to call each tool, and how to phrase ingests so they survive in the graph long after the work is done. It activates whenever the harness sees a signal that prior context might be relevant, or that something worth preserving has just happened.
Most operational issues fall into a small set of patterns:
Port already in use. Tribal exits with the conflicting address in the error message. Free the port, or switch to --transport stdio to bypass network binding.
Bad credentials state. Re-run tribal bootstrap; the manager recovers or replaces the namespaced pending/stable credential pair transactionally.
Corrupted Docker volume. Stop the stack with docker compose down -v, then docker compose up. The volume is recreated on the next start.
Stale project context. If TRIBAL_PROJECT_ID is set in your environment to a project that no longer exists, unset it or re-run tribal bootstrap against the current directory's git remote.
Missing provider env vars. tribal check --providers names which provider stage is failing and walks the resolution chain. Set the missing variable and re-run.
Logs are written to standard error. Every command that has a useful structured form supports --json; the structured output is more amenable to parsing than the human stderr stream.
To re-bootstrap cleanly without losing your knowledge graph, run tribal bootstrap again. It will reuse the existing project if the git remote matches, mint a new bearer token, and re-emit the MCP config snippet.
tribal check is the first stop for any operational issue. It surfaces failures with a remediation field describing the next action in plain prose. Pass --json when you need to consume the structured form.
When tribal check reports ok: true and a problem is still visible, the issue is usually network-level rather than Tribal itself. The most common pattern is a VPN or firewall sitting between the binary and the database; MCP errors look like Tribal is down even though the database is what's broken. Confirm connectivity to the configured database before assuming Tribal is at fault.
For runtime failure modes that fall outside the check suite (worker death, transport-layer errors, prompt loading failures), the using-tribal skill bundles a reference covering each pattern. Install it via the Quick start one-liner if you haven't already.
Manual steps, in any order:
Remove the binary. brew uninstall tribal for Homebrew installs, the installer's removal script for the shell-installer path, or docker compose down -v for the containerised path.
Delete the namespaced credential directory at $XDG_CONFIG_HOME/tribal/credentials/.
Drop the Postgres database Tribal was using.
Remove the skills with npx skills remove installing-tribal using-tribal.
Search Tribal's knowledge base using natural language. Returns knowledge items ranked by semantic similarity to your query, with optional structured filters to narrow results.
Use this as your first step when you need context: before starting work on a feature, debugging an issue, or making a design decision. Ask questions the way you'd ask a colleague: "What do I know about connection pooling in this project?" or "Have I seen this async deadlock pattern before?"
Semantic search is the primary mechanism. Filters (project, kind, tags, time) narrow the candidate set but are not required. If you need to understand an item's evidence, contradictions, or derivation chain, follow up with tribal_explore using the item's ID.
Superseded items (replaced by newer understanding) are excluded by default. Set include_superseded to true for the historical picture.
Results include standing (evidential profile) when requested, which summarises each item's support count, contradiction count, observation frequency, and diversity of supporting evidence.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Opaque pagination cursor from a previous response's next_cursor. | |
| include_references | No | Return references (file paths, URLs, concepts) attached to each item. | |
| include_standing | No | Compute and return standing (evidential profile) for each result. Adds minor latency. Recommended when assessing reliability. | |
| include_superseded | No | Include items that have been superseded by newer understanding. Default false. | |
| kinds | No | Filter to specific knowledge kinds. Use sparingly; semantic search naturally ranks relevant kinds higher. Most useful for explicit structural queries like 'show me all decision records for this project'. | |
| limit | No | Maximum number of results to return. | |
| project_id | No | Filter to a specific project. Three-way semantics: omit to use session context project (if set); pass a project ID to filter to that project; pass null to search globally, ignoring session context. | |
| query | Yes | Natural language query. Describe what you're looking for conversationally. The system embeds this and finds semantically similar knowledge items. | |
| tags | No | Filter by tags (AND semantics: items must have ALL specified tags). Tags are lowercase. For OR semantics, make separate queries. | |
| time_range | No | Filter by creation time. Either or both bounds may be specified. |
| Name | Required | Description |
|---|---|---|
| applied_project_id | Yes | The project used for filtering. Set when search was project-scoped (explicit ID or from session context). Null when search was global (no project filter applied, or project_id was explicitly null). |
| embedding_model | Yes | Which embedding model was used for this query. |
| embedding_profile_id | Yes | The active embedding profile that produced these results. Cursors and feedback are bound to it; a reindex changes it. |
| exact | Yes | True if all matching results are included. False if truncated by limit. |
| items | Yes | |
| next_cursor | Yes | Pagination cursor. Null if no more results. |
| trace_id | Yes | Trace ID for this retrieval. Pass to tribal_feedback to rate this session. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains default exclusion of superseded items, behavior of include_standing and its latency, project_id three-way semantics, tag AND logic, and pagination via cursor. No contradictions or hidden 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?
Description is well-structured and front-loaded with core purpose. Each sentence adds value, though slightly longer than minimal. 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?
For a tool with 10 parameters, nested objects, and an output schema, the description is comprehensive: covers usage, filters, pagination, standing, superseded items. No gaps remain.
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%, but description adds significant value: explains natural language embedding, semantic similarity ranking, project_id semantics, tag AND vs OR, and when to use kinds filter sparingly. Go 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 it's for searching Tribal's knowledge base using natural language, with semantic similarity ranking and optional filters. It distinguishes itself from sibling tools like tribal_explore (for exploring item details).
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 'Use this as your first step when you need context... before starting work on a feature, debugging, design decision.' Provides examples of queries and when to use filters vs not. Advises follow-up with tribal_explore for deeper understanding.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Traverse the relationship graph from a specific knowledge item. Use this after tribal_discover to understand an item's context: what supports it, what contradicts it, what it was derived from, or what it supersedes.
Typical workflow:
tribal_discover finds relevant items
Pick an item with interesting standing (high support, or contradictions)
tribal_explore to see the evidence, contradictions, or derivation chain
Direction controls traversal:
"inbound": What do others assert about this item? (supports, contradictions, what supersedes it)
"outbound": What does this item assert about others? (what it's derived from, what it supports)
"both": Full neighbourhood in all directions
Relation types:
"supports": Evidence that reinforces the item
"contradicts": Evidence that challenges the item
"supersedes": A newer item that replaces this one
"derived_from": Provenance. The input used to produce this item
Depth controls hops: depth 1 = direct relations, depth 2 = relations of relations. Higher depth gives more context but more results. Depth is capped at 3 to avoid mixing unrelated evidence across distant graph regions; use multiple targeted calls for deeper investigation.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Maximum traversal hops from anchor. 1 = direct relations only. | |
| direction | No | Traversal direction relative to the anchor item. | inbound |
| include_references | No | Return references attached to each item. | |
| include_standing | No | Compute standing for each returned item. Adds latency at depth > 1. | |
| item_id | Yes | The anchor item to explore from. Typically obtained from a tribal_discover result. | |
| limit | No | Maximum total results across all depths. Closer relations are returned first. | |
| relation_types | No | Filter to specific relation types. Omit to return all types. | |
| session_trace_id | No | Trace ID from a prior tribal_discover call. If provided, this explore is part of the same retrieval session. The returned trace_id will match. Use this to build coherent feedback across discover + explore workflows. |
| Name | Required | Description |
|---|---|---|
| anchor | Yes | |
| anchor_standing | Yes | |
| exact | Yes | True if all reachable items within depth were returned. False if truncated by limit. |
| related_items | Yes | |
| trace_id | Yes | Trace ID. Pass to tribal_feedback if rating this session. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses depth cap at 3, latency implications for include_standing at depth > 1, and ordering of results. It does not mention authentication or rate limits, but it adequately describes behavioral traits for a read-like operation.
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 (overview, workflow, direction, relation types, depth). It is front-loaded with the main action, and each sentence adds necessary information without redundancy. 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 complexity (graph traversal, 8 parameters, sibling tools), the description is highly complete. It integrates the tool into a workflow, explains parameter trade-offs, and sets expectations for depth limits. An output schema exists, so return value details are not needed.
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 adds significant value beyond the schema by explaining the workflow, providing definitions for direction and relation types, and cautioning about depth. This extra context 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's purpose: 'Traverse the relationship graph from a specific knowledge item.' It distinguishes itself from siblings like tribal_discover by describing a typical workflow, and the description is specific about traversing relationships (supports, contradicts, etc.).
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 recommends using this tool after tribal_discover and outlines a clear workflow: discover, pick an item, then explore. It explains parameters like direction and relation types, aiding decision-making. It lacks explicit 'when not to use' instructions but provides sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a quality signal about a retrieval session. Use this when Tribal's knowledge meaningfully helped (or failed to help) your current task.
This is NOT about rating individual items. Item-level signals are captured through the Supports/Contradicts relationship system during ingest. This is about rating the combination of items returned for a query, assembled in a particular way.
Rate "positive" when: Tribal surfaced knowledge that directly informed your approach, saved you from a known pitfall, or provided context that improved your decision-making.
Rate "negative" when: The query should have found relevant knowledge but didn't, or the returned items were irrelevant or misleading for the task at hand.
Feedback builds an organic eval dataset. Be selective: only rate when the signal is clear. If no trace_id is available from the retrieval response, do not submit feedback rather than fabricating a trace_id. Incomplete feedback is noise.
| Name | Required | Description | Default |
|---|---|---|---|
| embedding_profile_id | No | The embedding_profile_id from the tribal_discover response being rated, so the lineage records the profile that produced the results. | |
| explored_anchor_ids | No | IDs of items used as anchors in tribal_explore calls during the session. | |
| notes | No | Optional reasoning. What was good or what was missing? | |
| query_text | Yes | The original discovery query that initiated the retrieval session. | |
| rating | Yes | Was this retrieval session helpful? | |
| returned_item_ids | Yes | IDs of items returned by tribal_discover in the rated session. | |
| trace_id | Yes | Trace ID from the tribal_discover or tribal_explore response being rated. |
| Name | Required | Description |
|---|---|---|
| feedback_id | Yes | ID of the recorded feedback. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden. It discloses that feedback builds an eval dataset, that submission should be selective and only when signal is clear, and that incomplete feedback (missing trace_id) should not be submitted. This goes beyond basic 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 well-structured with a clear lead sentence, followed by explicit guidance. It is slightly long but each sentence is informative. It could be slightly more concise, but overall it is front-loaded and well-organized.
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 has 7 parameters (4 required) and no annotations, the description covers all necessary aspects: purpose, usage, parameter roles, and behavioral expectations. It mentions that feedback forms an eval dataset, which is important context. The description is 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 description coverage is 100% (all parameters described). The description adds context beyond the schema, such as explaining the purpose of embedding_profile_id (for lineage), explored_anchor_ids (anchors used), and notes (optional reasoning). It does not simply repeat schema descriptions but enriches them.
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: 'Record a quality signal about a retrieval session.' It uses specific verbs and resources, and distinguishes itself from sibling tools like tribal_discover and tribal_explore by focusing on the combined retrieval session quality.
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 (when Tribal's knowledge helped or failed), when-not-to-use (not for individual items), and criteria for positive/negative ratings. It also warns against fabricating trace_id and advises to be selective, making it clear how to use the tool correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve one or more knowledge items by their IDs. Use this when you have a specific item ID (from a standing field, a previous session, or a cross-reference) and need the full item.
For semantic search, use tribal_discover. For relationship traversal, use tribal_explore. This tool is for direct lookup when you already know what you want.
The response is keyed by item ID. Missing or unknown IDs map to null.
| Name | Required | Description | Default |
|---|---|---|---|
| include_references | No | Return references attached to each item. | |
| include_standing | No | Compute and return standing (evidential profile) for each item. | |
| item_ids | Yes | One or more knowledge item IDs to retrieve. |
| Name | Required | Description |
|---|---|---|
| items | Yes | Map from requested item ID to result. Keys are the ki_-prefixed IDs from the request. Value is the item with optional standing/references, or null if the ID was not found. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full transparency burden. It reveals response behavior (keyed by ID, missing IDs map to null) and implies read-only usage via 'retrieve.' However, it does not explicitly state side-effect freedom or authorization needs, though the retrieval nature is clear.
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 front-loads the core action, then provides focused usage guidance and response details in just three sentences. Every sentence is necessary and adds value, with no redundancy or filler.
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 has 3 parameters, an output schema, and sibling tools, the description completes the picture by specifying when to use, limitations (direct lookup), and response format. It does not need to explain return values (output schema exists) and covers all essential contextual aspects.
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 extra meaning to parameters beyond what the schema provides (e.g., include_references, include_standing are described in schema). Thus, it meets the baseline without surpassing 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 starts with 'Retrieve one or more knowledge items by their IDs,' clearly stating the verb and resource. It explicitly distinguishes this tool from siblings (tribal_discover for semantic search, tribal_explore for relationship traversal), making its specific purpose unmistakable.
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 usage context: 'Use this when you have a specific item ID ... and need the full item.' It also clearly states when not to use it, directing to alternative tools for semantic search and relationship traversal, leaving no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit raw text for knowledge extraction into Tribal. The system extracts structured knowledge items (facts, heuristics, procedures, decision records), detects duplicates, identifies relationships with existing knowledge, and stores the results.
This is an asynchronous operation. Returns a job_id immediately. Use tribal_job_status to poll for completion.
Use this tool when you've learned something worth preserving: a debugging insight, an architectural decision, a reusable pattern, a gotcha about a library, or any experience that would help you or another agent working on this codebase in the future.
Do NOT use this for storing code snippets, file contents, or documentation. Tribal stores knowledge about work, not the artefacts themselves.
Project, model, and principal are sourced from session context (see tribal_set_context). You only need to provide the content itself.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The raw text to extract knowledge from. Write naturally: describe what you learned, what went wrong, what the fix was, why a decision was made. The system handles structuring. Richer input produces better results: include context, reasoning, and specifics rather than terse summaries. | |
| project_id | No | Override the session's active project for this ingest. Optional; defaults to the project set in session context. |
| Name | Required | Description |
|---|---|---|
| job_id | Yes | Unique identifier for the ingest job. Use with tribal_job_status to track progress. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits: asynchronous operation with immediate job_id return, knowledge extraction and storage. Mentions that project/model/principal come from context. However, no annotations exist, so the description carries full burden; it could mention idempotency or side effects, but the provided info is sufficient for safe use.
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?
Concise with clear structure: main action, async note, usage guidance, exclusions, and context sourcing. Every sentence serves a purpose; 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 complexity (async, multi-step extraction) and existence of an output schema, the description covers essential operational aspects, usage, and parameter context. It does not detail error handling or output structure (covered by schema), but is complete enough for effective use.
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% (baseline 3). The description adds value: explains how to write content naturally for best results, and clarifies project_id as optional override. This goes beyond the schema's basic descriptions.
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 uses specific verbs ('Submit raw text for knowledge extraction') and identifies the resource ('into Tribal'). It explains the system's extraction process (facts, heuristics, etc.) and clearly differentiates from siblings by focusing on ingestion, not discovery, exploration, or other operations.
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 on when to use: 'when you've learned something worth preserving' with concrete examples. Also states when NOT to use: 'Do NOT use this for storing code snippets...'. Recommends polling with tribal_job_status for async completion and notes context sourcing from tribal_set_context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the progress of an ingest job submitted via tribal_ingest.
Job lifecycle: queued → extracting → triaging → relating → completed/failed
Terminal states:
"completed": Pipeline ran to conclusion. Check outcome for details:
"success": All candidates triaged successfully and relations committed.
"partial": Some triage tasks failed permanently; the relation task ran on a subset.
"empty": Relation task ran with zero items to relate (all duplicates or all triage failures). If tasks_failed > 0, the pipeline likely failed at triage; treat as degraded rather than "nothing new".
"failed": Pipeline could not complete. outcome = "failure". Check error context.
Set wait_seconds to block until the job completes or the timeout expires. This collapses ingest + poll into a single round-trip for fast operations. With wait_seconds=0 (default), returns immediately with current status.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job ID returned by tribal_ingest. | |
| wait_seconds | No | If > 0, the server blocks until the job reaches a final status (completed or failed) or the timeout expires, whichever comes first. Returns current status either way. Use this to collapse ingest + poll into fewer round-trips for fast operations. |
| Name | Required | Description |
|---|---|---|
| batch_size | No | Number of knowledge candidates extracted. Set after extraction completes. |
| created_at | Yes | |
| items_created | Yes | New knowledge items stored (novel content). |
| job_id | Yes | |
| observations_created | Yes | Duplicate observations recorded (strengthens existing items). |
| outcome | No | Final result. Only set when status is 'completed' or 'failed'. |
| status | Yes | Current lifecycle state. |
| tasks_completed | Yes | Triage tasks completed successfully. |
| tasks_failed | Yes | Triage tasks that failed permanently. |
| updated_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: job lifecycle (queued → extracting → triaging → relating → completed/failed), terminal states (completed, failed, with sub-outcomes), and wait_seconds blocking behavior. 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 sections for lifecycle, terminal states, and usage. It is somewhat lengthy but all information is relevant and earns its place.
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 (not shown), the description need not detail return format. It comprehensively covers job lifecycle, terminal states, and wait_seconds behavior, leaving no gaps for agent understanding.
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 by explaining the job lifecycle and the effect of wait_seconds beyond schema descriptions, but the schema already describes parameters adequately.
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 that the tool checks the progress of an ingest job submitted via tribal_ingest, with a specific verb ('Check') and resource ('Ingest Job Status'). It distinguishes from sibling tools by focusing on status polling.
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?
Guidance is provided on when to use (after tribal_ingest) and how to use wait_seconds to collapse round-trips. It does not explicitly mention when not to use or alternative tools, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a reindex to a new embedding geometry, naming the target provider, model, and dimension on the command. Reads and writes continue against the active profile while the new space fills; the swap is atomic. An unchanged target is a no-op. Operator-only; the worker drives the run to completion.
| Name | Required | Description | Default |
|---|---|---|---|
| base_url | No | The target endpoint. The provider's default when omitted. | |
| dimensions | No | The target vector dimension, between 1 and the halfvec storage ceiling of 4000. Resolved from the model when omitted. | |
| dry_run | No | When true, resolve the target, validate its credential, and return the item and tag counts without creating a run. | |
| model | Yes | The target embedding model. | |
| provider | Yes | The target embedding provider, for example 'ollama' or 'openai'. |
| Name | Required | Description |
|---|---|---|
| base_url | Yes | The resolved, normalised target endpoint. |
| dimensions | Yes | The resolved target dimension. |
| estimated_items | Yes | The number of items the new geometry must embed. |
| estimated_tags | Yes | The number of tags the new geometry must embed. |
| model | Yes | The resolved target model. |
| outcome | Yes | plan: a dry run; no run was created. created: a new run was queued. unchanged: the target already matches the active profile. already_live: a run is already in progress. lock_contended: another create holds the single-flight lock; retry. |
| provider | Yes | The resolved target provider. |
| run_id | Yes | The run id, present for created and already_live. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses mutation, non-blocking behavior, atomic swap, and no-op condition. It also notes operator-only restriction. The dry_run parameter is documented in the schema but not the description, which is a minor omission.
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 three sentences, front-loaded with the main action, and each sentence adds essential information without redundancy. It is highly efficient.
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 (5 parameters, output schema present), the description covers the key behavioral aspects. It implies asynchronicity via 'worker drives to completion' and the sibling job_status tool fills the gap. The description is sufficient for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds limited value beyond the schema. It mentions naming the target parameters but doesn't elaborate on validation or interaction. The baseline of 3 is appropriate given full schema coverage.
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 starts a reindex to a new embedding geometry, specifying the key parameters (provider, model, dimension). It differentiates from sibling tools like cancel and prune by focusing on initiation.
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 explains that reads/writes continue during reindex, the swap is atomic, and unchanged target is a no-op. It mentions operator-only access and that the worker drives completion. While it could explicitly contrast with alternatives, the context of siblings provides enough guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel the live reindex run, if any. The run is aborted and its building profile is failed at the next task boundary; the active profile, and every read and write against it, is untouched. Reindex is single-flight, so there is at most one live run. Operator-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| cancelled | Yes | Whether a live run was transitioned to aborted. |
| run_id | Yes | The aborted run's id, present only when a run was cancelled. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Explains that the run is aborted, profile failed at next task boundary, active profile untouched, and that it's operator-only. Covers key side effects, though reversibility is not discussed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first states purpose, second adds behavioral details. 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?
Despite no parameters and presence of output schema, the description covers essential behavioral details (cancellation effects, auth requirement, single-flight). No apparent 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?
Zero parameters, baseline score 4. Description adds meaning by stating 'takes no arguments; reindex is single-flight', confirming no input needed.
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 the tool cancels the live reindex run, with specific behavior (abort, fail profile at next task boundary). Distinguishes from siblings like tribal_reindex and tribal_reindex_prune.
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?
Indicates cancellation is conditional ('if any'), and notes reindex is single-flight. Doesn't explicitly state when not to use, but context implies it's for active runs only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reclaim storage from past reindexes. Every non-active complete profile and every failed profile is superseded, and their embeddings are deleted; the active profile and run history are untouched. Operator-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| embeddings_deleted | Yes | The number of item embeddings deleted. |
| profiles_superseded | Yes | The number of profiles transitioned to superseded. |
| tag_embeddings_deleted | Yes | The number of tag embeddings deleted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses the tool's behavior: what gets superseded (non-active complete and failed profiles), what gets deleted (embeddings), and what remains untouched (active profile and run history). 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 extremely concise with two sentences, front-loading the core purpose and adding necessary details without any 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 simplicity (no parameters, straightforward action) and the presence of an output schema, the description is complete. It covers the action, scope, and authorization requirement.
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 tool has zero parameters, and the schema coverage is 100% (trivially). The description adds value by explaining the cleanup process beyond the schema, meeting the baseline of 4 for zero-parameter 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 explicitly states the tool's purpose: reclaim storage by superseding non-active and failed profiles and deleting embeddings. It clearly distinguishes from siblings like tribal_reindex and tribal_reindex_cancel.
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 includes 'Operator-only' to indicate restricted usage, implying it should be used by operators for cleanup. While it doesn't list explicit alternatives or when-not-to-use scenarios, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set or override session-level context for Tribal. Use this at the start of a session to declare your model identity, or when switching to a different project.
Session context is used as the default for all subsequent tool calls. For example, setting a project here means tribal_ingest and tribal_discover will use it automatically without needing project_id on every call.
The server resolves what it can at connection start (project from git remote, principal from auth). Use this tool to fill in what the server cannot infer (model name, provider) or to override what it resolved (e.g., switching projects).
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | The model you are running as. e.g., 'claude-sonnet-4-5-20250514'. Set once at session start. | |
| project_id | No | Override the active project. Use when working in a different project than the one resolved from the git remote. | |
| provider | No | The inference provider. e.g., 'anthropic', 'openai'. Set once at session start. |
| Name | Required | Description |
|---|---|---|
| actor | Yes | |
| principal_key | Yes | |
| project | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It explains that session context becomes default for subsequent calls, how server resolution works, and that this tool fills gaps or overrides. The description is transparent about the tool's impact and limitations.
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 efficiently structured: first sentence defines purpose, then usage guidance, then behavioral explanation. Every sentence adds value and no waste. It is front-loaded with the core 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 low complexity, full schema coverage, and presence of an output schema, the description adequately covers all necessary information. It explains purpose, usage, parameter details, and behavioral implications, leaving 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 valuable context beyond the schema: for 'model' and 'provider' it recommends setting once at session start, and for 'project_id' it clarifies override behavior. This improves usability without being verbose.
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 action ('Set or override session-level context for Tribal') and resource ('session context'). It distinguishes itself from siblings by emphasizing that it configures defaults used by other tribal tools, which is a distinct role from data ingestion or discovery 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?
The description explicitly states when to use the tool ('at the start of a session' or 'when switching projects') and explains the default server inference and when to override. It also implies when not to use it (when server inference suffices), providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a unique and clearly defined purpose. There is no overlap between search, exploration, ingestion, job monitoring, feedback, and administration tools.
All tools follow the 'tribal_verb_noun' pattern consistently, making it easy to infer each tool's function from its name.
With 10 tools, the server is well-scoped for managing a knowledge base. Each tool serves a distinct and necessary role without unnecessary bloat.
The toolset covers the core lifecycle of knowledge management (search, explore, retrieve, ingest, feedback), but lacks explicit tools for updating or deleting individual items, which is a minor gap.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Persistent knowledge graph for AI-augmented teams. Store decisions, findings, and standing rules across agent sessions with semantic search and typed connections. Includes cross-session memory, audit trail, workspace isolation, and secret detection. Built for teams running agents that need to remember. Free until launch with team tier as default, anon trial available.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
Persistent memory for AI agents. EU-hosted, privacy-first, hybrid recall, contradiction detection.
Your AI's memory for what you actually know: recall across your documents, notes, and meetings
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/tribal-memory/tribal'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
