MCP Tools Reference

MCP Tools Reference

TeamLoop provides a comprehensive set of MCP tools for querying, building, and synthesizing temporal knowledge.

Query Tools

teamloop_query

Query your knowledge across connected integrations (GitHub, Notion, Linear).

Parameters:

Parameter	Type	Required	Description
query	string	Yes	The search query
sources	string	No	Comma-separated list: github, notion, linear
mode	string	No	Query mode: current (default) or as_of
as_of	string	No	Date in YYYY-MM-DD format (required when mode is as_of)
retrieval	string	No	Retrieval strategy: hybrid (default) or standard

Retrieval Strategies:

• hybrid (default) — Combines vector semantic search with BM25 full-text search using reciprocal rank fusion (RRF), then refines results with cross-encoder reranking. Catches both semantically similar results and exact keyword matches, with high precision in the top results.
• standard — Vector-only semantic search (legacy behavior).

Example:

Query: "JWT token rotation policy"
Sources: "github,notion"
Mode: "current"
Retrieval: "hybrid"

Returns: Search results with extraction instructions for building your knowledge graph. When using hybrid retrieval, results include a retrieval_metadata field:

Field	Type	Description
method	string	hybrid, vector_only, or text_only
vector_count	int	Candidates from vector search
text_count	int	Candidates from full-text search
fused_count	int	Results after fusion and reranking
reranked	bool	Whether cross-encoder reranking was applied
rerank_model	string	Reranker model used (e.g., rerank-2, cohere.rerank-v3-5:0)

---

teamloop_timeline

Get a temporal timeline showing how knowledge has evolved.

Parameters:

Parameter	Type	Required	Description
query	string	No*	Topic to build timeline for
entity_id	string	No*	Get lineage for specific entity
limit	number	No	Max entries (default: 20)

*Either query or entity_id is required.

Example:

Query: "database architecture"
Limit: 10

Returns: Chronological timeline of decisions, changes, and documents.

---

teamloop_evolution

Track how knowledge evolved over a time range.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Topic to track
from_date	string	Yes	Start date (YYYY-MM-DD)
to_date	string	Yes	End date (YYYY-MM-DD)

Example:

Query: "authentication"
From: "2024-01-01"
To: "2024-12-31"

Returns: Evolution of knowledge grouped by month with supersession events.

---

teamloop_compare

Compare knowledge between two points in time.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Topic to compare
date_a	string	Yes	First date (YYYY-MM-DD)
date_b	string	Yes	Second date (YYYY-MM-DD)

Example:

Query: "infrastructure decisions"
Date A: "2024-01-01"
Date B: "2024-06-01"

Returns: What was added, removed, superseded, or unchanged.

Knowledge Graph Tools

teamloop_save_knowledge

Save extracted entities and relationships to your knowledge graph.

Parameters:

Parameter	Type	Required	Description
entities	array	Yes	Array of entity objects
relationships	array	No	Array of relationship objects

Entity Object:

Field	Type	Required	Description
type	string	Yes	DECISION, PERSON, PROJECT, COMPONENT, DOCUMENT, CHANGE, FACT
name	string	Yes	Entity name
description	string	No	Detailed description
event_date	string	No	When event occurred (YYYY-MM-DD)
rationale	string	No	For decisions: why this was chosen
alternatives	array	No	For decisions: other options considered
status	string	No	Current status
source_url	string	No	Link to original source
source_integration	string	No	github, notion, or linear
source_external_id	string	No	ID in source system

Relationship Object:

Field	Type	Required	Description
source_name	string	Yes	Name of source entity
source_type	string	Yes	Type of source entity
target_name	string	Yes	Name of target entity
target_type	string	Yes	Type of target entity
relationship_type	string	Yes	DECIDED_BY, AUTHORED_BY, PART_OF, RELATES_TO, SUPERSEDES, DEPENDS_ON, IMPLEMENTS

Example:

{
  "entities": [
    {
      "type": "DECISION",
      "name": "Adopt PostgreSQL for main database",
      "description": "Chose PostgreSQL over MySQL for better JSON support",
      "event_date": "2024-03-15",
      "rationale": "Need JSONB for flexible schema",
      "alternatives": ["MySQL", "MongoDB"],
      "status": "active"
    }
  ],
  "relationships": [
    {
      "source_name": "Adopt PostgreSQL",
      "source_type": "DECISION",
      "target_name": "Alice",
      "target_type": "PERSON",
      "relationship_type": "DECIDED_BY"
    }
  ]
}

teamloop_save_facts

Save extracted atomic facts from an entity. Call this after extracting facts from a DOCUMENT or DECISION entity’s description. Each fact becomes an independently searchable unit linked to the parent entity via a PART_OF relationship.

Parameters:

Parameter	Type	Required	Description
parent_entity_id	string	Yes	UUID of the parent entity these facts were extracted from
facts	array	Yes	Array of fact objects

Fact Object:

Field	Type	Required	Description
text	string	Yes	The complete atomic fact as a standalone sentence
attribution	string	No	Person name if the fact is attributed to someone
date	string	No	When the fact occurred (YYYY-MM-DD)

Example:

{
  "parent_entity_id": "abc123-...",
  "facts": [
    {
      "text": "Sarah Chen approved the PostgreSQL migration on January 15, 2026.",
      "attribution": "Sarah Chen",
      "date": "2026-01-15"
    },
    {
      "text": "PostgreSQL was chosen over MongoDB due to pgvector support for embeddings.",
      "attribution": null,
      "date": null
    }
  ]
}

Returns: Summary of facts created and any duplicates skipped.

How it works:

When teamloop_save_knowledge saves a DOCUMENT or DECISION entity with a description longer than 200 characters, the response includes fact extraction instructions telling the host LLM to extract atomic facts and call teamloop_save_facts. This is the primary extraction path (zero LLM cost to TeamLoop).

For entities ingested via teamloop_remember or the REST API, facts are extracted server-side using Bedrock as a fallback.

Facts are stored as entities with type FACT and participate in all search pipelines (hybrid, vector, text) automatically. When a fact surfaces in search results, its parent entity provides additional context via the PART_OF relationship.

---

Cluster Tools

teamloop_list_clusters

List auto-detected entity clusters as suggested subgraphs. Clusters form automatically as entities are saved.

Parameters:

Parameter	Type	Required	Description
min_size	number	No	Minimum entities for a cluster to be shown (default: 3)

Example:

teamloop_list_clusters

Returns: Markdown-formatted list of clusters with labels, entity counts, and date ranges.

---

Foresight Tools

teamloop_foresight

Get active foresight predictions — forward-looking consequences of decisions. Query by topic, decision ID, or list all. Predictions are auto-generated when DECISION entities are saved and auto-fulfilled when matching DECISION/CHANGE entities appear.

Parameters:

Parameter	Type	Required	Description
query	string	No	Search predictions by topic (e.g., “API migration”, “SDK updates”)
decision_id	string	No	Get predictions for a specific decision by UUID
status	string	No	Filter by status: active (default), fulfilled, dismissed, expired, all

If no parameters are provided, all active predictions are returned.

Example:

Query: "API migration"
Status: "active"

Returns: List of predictions with confidence scores, time horizons, status, and source decision links. See the Foresight feature page for full details on prediction lifecycle and auto-fulfillment.

---

Org Profile Tools

teamloop_org_profile

Manage organizational preferences, standards, and constraints. Traits persist across queries and surface in context reconstruction as standing context.

Parameters:

Parameter	Type	Required	Description
action	string	Yes	list, add, remove, or infer
trait	string	For add/remove	The trait text (e.g., “Prefer TypeScript over JavaScript”)
category	string	For add	preference (default), standard, constraint, or deprecation

List active traits:

Action: "list"

Declare a trait:

Action: "add"
Trait: "All new services must use gRPC"
Category: "standard"

Remove a trait:

Action: "remove"
Trait: "All new services must use gRPC"

Infer from decisions:

Action: "infer"

Analyzes DECISION entities from the last 6 months and generates up to 10 traits with supporting decision IDs. Requires 3+ decisions. See the Org Profile feature page for full details on inference, provenance, and context reconstruction integration.

---

Subgraph Tools

teamloop_create_subgraph

Create a curated collection of entities for specific topics.

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Subgraph name
description	string	No	What this subgraph represents
entity_ids	array	No*	Specific entity IDs to include
query	string	No*	Semantic query to find entities
limit	number	No	Max entities when using query (default: 20, max: 50)

*Use either entity_ids or query, not both.

Example:

Name: "Auth System Decisions"
Query: "authentication and authorization"
Limit: 30

---

teamloop_get_subgraph

Retrieve a subgraph with all its entities.

Parameters:

Parameter	Type	Required	Description
subgraph_id	string	No*	The subgraph UUID
name	string	No*	Find by name instead of ID

*Either subgraph_id or name is required.

---

teamloop_expand_subgraph

Find related entities to expand a subgraph.

Parameters:

Parameter	Type	Required	Description
subgraph_id	string	Yes	The subgraph to expand
depth	number	No	Relationship hops (1-3, default: 1)
include_types	array	No	Filter by entity types
auto_add	boolean	No	Automatically add found entities

Example:

Subgraph ID: "abc123..."
Depth: 2
Include Types: ["DECISION", "COMPONENT"]
Auto Add: true

Journal Tools

teamloop_create_journal_entry

Capture thoughts, decisions, or context as journal entries.

Parameters:

Parameter	Type	Required	Description
title	string	Yes	Entry title
content	string	Yes	Entry content
mood	string	No	reflection, planning, decision, note, question
tags	array	No	Categorization tags
link_entity_ids	array	No	Explicit entity links
auto_link	boolean	No	Auto-find related entities (default: true)

Example:

Title: "Thoughts on microservices migration"
Content: "After reviewing the Auth Service and User Service..."
Mood: "planning"
Tags: ["architecture", "q1-planning"]

Synthesis Tools

teamloop_synthesize

Generate documents from a subgraph using templates.

Parameters:

Parameter	Type	Required	Description
subgraph_id	string	Yes	Source subgraph
template_type	string	Yes	brief, prd, or adr
additional_context	string	No	Extra instructions

Template Types:

• brief - Executive summary
• prd - Product Requirements Document
• adr - Architecture Decision Record

Returns: Job ID for polling completion.

---

teamloop_get_synthesis_job

Check status and get output of a synthesis job.

Parameters:

Parameter	Type	Required	Description
job_id	string	Yes	The synthesis job ID

Returns: Job status (pending, processing, completed, failed) and output when complete.

---

teamloop_cancel_synthesis_job

Cancel a pending or in-progress synthesis job.

Parameters:

Parameter	Type	Required	Description
job_id	string	Yes	The synthesis job ID

Agent Memory Tools

teamloop_remember

Store a fact, decision, or insight in natural language. TeamLoop automatically extracts entities, relationships, and temporal context using LLM-powered extraction.

Parameters:

Parameter	Type	Required	Description
content	string	Yes	What to remember, in natural language
tags	array	No	Tags for categorization (e.g., ["auth", "architecture"])
context	string	No	Additional context (e.g., “from sprint planning meeting”)

Example:

Content: "We decided to use JWT for auth because mobile apps need
stateless tokens. Sarah proposed this on March 15."
Tags: ["auth", "architecture"]

Returns: Summary of entities created, relationships found, and any conflicts detected with existing decisions. For DOCUMENT and DECISION entities with long descriptions (> 200 chars), facts are automatically extracted server-side.

---

teamloop_recall

Recall what you know about a topic. Returns a synthesized summary from your knowledge graph — not raw search results. Does not query external integrations.

Parameters:

Parameter	Type	Required	Description
topic	string	Yes	What to recall
scope	string	No	all (default), recent (last 30 days), decisions (only decisions)
time_context	string	No	Natural language time filter (e.g., “since January”, “last month”)

Example:

Topic: "authentication decisions"
Scope: "decisions"
Time context: "since January"

Returns: Coherent paragraph summary with temporal context and source counts.

---

teamloop_get_context

Get a comprehensive briefing on a topic combining entities, relationships, timeline, and conflicts.

Parameters:

Parameter	Type	Required	Description
topic	string	Yes	Topic to get full context for
depth	string	No	brief (default) or full (comprehensive with all relationships and history)

Example:

Topic: "payments service"
Depth: "full"

Returns: Structured briefing with sections: Current State, Key Decisions, Relationships, Timeline, Open Issues.

---

teamloop_narrative

Generate a natural language narrative of how a topic evolved over time.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Topic to narrate
from_date	string	Yes	Start date (YYYY-MM-DD)
to_date	string	Yes	End date (YYYY-MM-DD)
focus	string	No	decisions, changes, or all (default)

Returns: AI-generated narrative explaining the evolution of a topic over time.

Best Practices

Workflow Pattern

With Agent Memory (recommended):

1. Recall - Use teamloop_recall to check what’s already known
2. Query - Use teamloop_query to fetch fresh data from integrations
3. Remember - Use teamloop_remember to store findings in natural language
4. Context - Use teamloop_get_context for comprehensive briefings

Manual workflow:

1. Query - Use teamloop_query to search integrations
2. Extract - Use teamloop_save_knowledge to save entities
3. Organize - Use teamloop_create_subgraph to group related knowledge
4. Expand - Use teamloop_expand_subgraph to find connections
5. Synthesize - Use teamloop_synthesize to generate documents

Temporal Queries

• Use mode: "as_of" to see what was known at a specific date
• Use teamloop_evolution to track changes over time
• Use teamloop_compare to diff knowledge between dates
• Use teamloop_timeline for entity-specific lineage

Entity Extraction

• Always include event_date from source documents
• Use source_url for traceability
• Create relationships to connect entities
• Use appropriate entity types for better queries

Atomic Facts

When you save entities with detailed descriptions via teamloop_save_knowledge, TeamLoop will instruct you to extract atomic facts using teamloop_save_facts. This improves retrieval granularity — instead of matching against an entire document’s embedding, specific facts like “Sarah approved the migration on Jan 15” become independently searchable.

Facts are automatically extracted server-side when using teamloop_remember or the REST API. The teamloop_save_facts tool is for the host LLM extraction path.