MCP tools

Resolve a name or alias to an entity_id. Your first call whenever the user names something. Case-insensitive substring match against every entity mantle has extracted across your connected sources.

When to call it: The user says “Who is Maren Vosh?” or “Tell me about Acme Corp.” You don't know an entity_id yet — this gets you one.

Returns: a ranked list of hits, each with entity_id, name, entity_type, and a preview of properties + source references.

One-call snapshot of an entity: identity, flat properties, aliases, and a bucketed summary of every relationship grouped by type. Pass verbosity="detailed" and each bucket gets three highest-confidence example edges inline — avoids a second round trip.

When to call it: “Tell me everything you know about X.” This is the workhorse after search_entities.

Doesn't return: raw document text. For that, use semantic_search or fetch_document.

Enumerate an entity's relationships. Two modes:

• mode="summary" — relationship types grouped by count with three example edges each
• mode="detailed" — a paginated list of edges, optionally filtered by rel_type

Use this — not semantic_search — for enumeration questions: “Which properties does Helix own?”, “What companies does Maren advise?” Semantic search returns a ranked sample; this returns the complete linked set.

Completeness signal: the response carries a completeness field ("exhaustive" / "truncated" / "severely_truncated") and an optional suggestion string when the entity is a hub and the answer is incomplete. Read these — your agent will know whether to page or narrow.

Shortest relationship path between two entities with per-hop evidence. One of the most valuable tools — agents want to say “X is connected to Y via Z” with confidence, not hallucinate a path.

When to call it: “How is A connected to B?”, “Is there any link between Acme and Globex?”

If no path exists within max_hops at the given min_confidence, the tool returns found=false — your agent can report that honestly and optionally retry with looser constraints.

Vector search across every indexed document chunk. Returns a ranked sample, not an exhaustive list — the response's completeness field is always "top_k" to keep this honest.

When to call it: topic-style questions where no specific entity is named. “What do we know about the Series B close?”

For enumeration questions anchored on a named entity (“which properties in Brickell”), prefer search_entities → get_relationships. If you do call semantic_search on an enumeration-style question and the query resolves to an indexed entity, the response will include an entity_suggestion field nudging you toward the graph path.

Pull source content. Two modes:

• chunk_id — returns the specified chunk plus window chunks on each side. Fast; use after semantic_search to expand context.
• (source_id, file_id) — returns the full document. Slower; use when the chunk window isn't enough.

Raw local-subgraph dump — every RELATES_TO edge reachable within depth hops. Annotated openWorldHint: true to signal breadth.

When to use: You want the whole neighborhood to render a visualization or reason over structure. For most narrative questions the primary retrieval tools are better.

Fuzzy-find relationship-type strings by meaning. Example: search_relationships("financing") might return financed_with_debt, has_lender, equity_investor. Use before get_relationships(rel_type=X) to discover which canonical rel-type the user's intent maps to.

Returns empty on no match — don't retry with variations. Report the gap to the user.

Read-only SELECT against a connected PostgreSQL source. sqlparse-validated; INSERT / UPDATE / DELETE / DDL are rejected client-side. readOnlyHint: true.

Best practice: always call semantic_search("schema columns <table>") first to discover real column names. Don't guess.

Every connected data source with status and document count. Your agent calls this to discover source_id values for semantic_search / query_database / fetch_document.

Aggregate corpus counts — sources, documents, entities, relationships, communities. “What's in my graph right now?”

Current credit balance for the tenant. Call this before expensive operations if your agent is cost-sensitive.

Enqueue an async sync of the named source. Idempotent, not destructive. Useful for “pull the latest from Gmail” style requests. Returns immediately with a task_id; the sync runs in the background.