mazarbul

Overview Schema Source Related Servers Discussions Admin

relations

List an entity's typed connections (incoming and outgoing) with direction tags, defaulting to current graph state and optionally including expired history or a time-travel view.

Instructions

List an entity's typed relations (incoming + outgoing), each row tagged direction=outgoing|incoming relative to the queried entity so directional predicates (reports_to, manages) read unambiguously. Endpoint names are hydrated. LLM-free. The DEFAULT view is point-in-time NOW: only edges valid now and not superseded; pass includeInactive=true for expired/superseded history, or time-travel with at/asOf. Filter by predicate. Role/title is often carried as an attributes.role string on a works_at/founded edge rather than a separate has_role edge; each row's sourceEventUid links back to the originating episode. Pair with neighbors to walk further.

Input Schema

Name	Required	Description
`at`	No	Valid-time anchor (RFC 3339 UTC). Returns relations live at this instant. Defaults to now.
`asOf`	No	Transaction-time anchor (RFC 3339 UTC). Hides relations recorded after this instant.
`limit`	No	Maximum relations to return. Defaults to 50.
`entity`	Yes	Entity whose relations to list: an entities/{uid} ref (as returned in a recall hit's entities[]), a bare uid, or a display name (resolved case-insensitively; an unknown or ambiguous name returns an error naming the candidate uids so you can retry).
`scopes`	No	Scopes to read from: project, personal, team. Defaults to project+personal. Unknown values are rejected.
`predicates`	No	Restrict to these predicates, e.g. ["works_at","reports_to"]. Omit to return all.
`includeInactive`	No	Return superseded / expired relations too (full history). Off by default.

Output Schema

Name	Required	Description	Default
`relations`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 31, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so well: it discloses direction tagging, endpoint hydration, default point-in-time semantics, superseded-edge exclusion, history and time-travel options, predicate filtering, attributes.role conventions, and sourceEventUid provenance. These are meaningful behavioral details beyond what the schema alone conveys.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and direction semantics, and most sentences add useful information. It is information-dense and somewhat run-on, but not padded with irrelevant material.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a seven-parameter temporal graph-query tool with no annotations but an output schema, the description is complete enough to call correctly. It explains the default temporal view, history and time-travel behavior, direction semantics, role/title modeling, and provenance links without needing to restate the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is a 3. The description adds useful semantics for includeInactive, at/asOf temporal anchoring, predicate filtering, and entity context, though it does not add meaning for limit or scopes beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: list an entity's typed relations, including both incoming and outgoing edges. It also explains the direction tagging so directional predicates are unambiguous, and it distinguishes the tool's role from walking further via neighbors.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear operational guidance for the default now view, includeInactive for historical/superseded edges, and at/asOf for time travel. It also points to neighbors for walking further, but it does not explicitly say when to prefer other relation-oriented siblings such as relate, unrelate, fact, or query.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.