Skip to main content
Glama
markmhendrickson

Neotoma

by markmhendrickson
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

list_relationships

List relationships for an entity, or discover the relationship type(s) between two specific entities. Filter by entity_id (with direction), or by source_entity_id and/or target_entity_id, and optionally relationship_type.

Instructions

List relationships for an entity, or discover the relationship type(s) between two specific entities. Filter by entity_id (with direction), or by source_entity_id and/or target_entity_id, and optionally relationship_type. To discover the type before delete_relationship, pass both source_entity_id and target_entity_id: each returned relationship carries its relationship_type. Soft-deleted relationships are excluded by default, so a deleted edge will not be re-offered for deletion; pass include_deleted: true to include them for audit. Paginated via limit/offset.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of relationships to return.
offsetNoNumber of relationships to skip before returning results.
user_idNoOptional user_id override (scoped to callers with privilege to query on behalf of another user). When omitted, the authenticated user is used.
directionNoDirection applied when `entity_id` is set. `incoming`/`inbound` matches relationships where the entity is the target; `outgoing`/`outbound` matches relationships where the entity is the source; `both` (default) matches either side. both
entity_idNoEntity ID to match against either the source or target of each relationship (filtered further by `direction`). Legacy filter pattern; prefer `source_entity_id` / `target_entity_id` for new code.
include_deletedNoWhen `false` (default), soft-deleted relationships are excluded from the result. When `true`, soft-deleted edges are included (audit/history use). A relationship is soft-deleted once its highest-priority deletion observation is recorded; the snapshot row itself persists.
source_entity_idNoMatch relationships whose `source_entity_id` equals this value.
target_entity_idNoMatch relationships whose `target_entity_id` equals this value.
relationship_typeNoRelationship type. The vocabulary is a runtime registry, not a closed enum: call list_relationship_types to read what this instance accepts, and register_relationship_type to add to it. Names are identifier-shaped and casing-agnostic (both SCREAMING_SNAKE and lower_snake are in use).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.25.0
    • changedInput schema / properties / relationship_type / description
      Previous value: -"Optional relationship_type filter. Closed enum matching the handler's\naccepted values; spec-driven clients passing any other value will be\nrejected at runtime with a Zod validation error.\n"New value: +"Relationship type. The vocabulary is a runtime registry, not a closed enum: call list_relationship_types to read what this instance accepts, and register_relationship_type to add to it. Names are identifier-shaped and casing-agnostic (both SCREAMING_SNAKE and lower_snake are in use)."
    • removedInput schema / properties / relationship_type / enum
      Removed value: -[
-  "PART_OF",
-  "CORRECTS",
-  "REFERS_TO",
-  "SETTLES",
-  "DUPLICATE_OF",
-  "DEPENDS_ON",
-  "SUPERSEDES",
-  "EMBEDS",
-  "works_at",
-  "owns",
-  "manages",
-  "part_of",
-  "related_to",
-  "depends_on",
-  "references",
-  "transacted_with",
-  "member_of",
-  "reports_to",
-  "located_at",
-  "created_by",
-  "funded_by",
-  "acquired_by",
-  "subsidiary_of",
-  "partner_of",
-  "competitor_of",
-  "supplies_to",
-  "contracted_with",
-  "invested_in"
-]
  2. Changed1 schema field changedv0.16.0
    • addedInput schema / properties / include_deleted
      Added value: +{
+  "default": false,
+  "description": "When `false` (default), soft-deleted relationships are excluded from\nthe result. When `true`, soft-deleted edges are included (audit/history\nuse). A relationship is soft-deleted once its highest-priority\ndeletion observation is recorded; the snapshot row itself persists.\n",
+  "type": "boolean"
+}
  3. Addedv0.15.0
  4. Removedv0.14.0
  5. Addedv0.12.1
  6. Removedv0.11.0
  7. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations, the description carries the burden and does so well: it discloses that soft-deleted relationships are excluded by default and why (so a deleted edge isn't re-offered for deletion), that include_deleted supports audit, and that pagination is via limit/offset. It omits permission/auth requirements for the user_id override, which stays only in the schema.

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?

Front-loaded with the primary purpose, then filter mechanics, a concrete workflow, soft-delete semantics, and pagination in a logical order. Dense but nearly every sentence adds information; only the filter enumeration lightly overlaps the schema.

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

Completeness4/5

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

For a 9-parameter, no-annotation, no-output-schema tool, the description covers the behaviors an agent needs (soft-delete handling, pagination, filter combination, type discovery). Return-value shape is only partially implied (each relationship carries its relationship_type), which is the main residual gap.

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 coverage is 100%, so baseline is 3, but the description adds combinatorial meaning the per-parameter schema lacks: it frames entity_id + direction as the legacy pattern versus source_entity_id/target_entity_id, and reinforces include_deleted's effect on results. It maps filters to intent rather than merely restating them.

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?

States a specific verb (list) and resource (relationships) and distinguishes two distinct modes: listing edges for one entity vs. discovering the relationship type between two specific entities. An agent can differentiate it from siblings like retrieve_related_entities and delete_relationship without opening the schema.

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?

Provides explicit workflow guidance ('To discover the type before delete_relationship, pass both source_entity_id and target_entity_id') and a clear default-vs-override case for soft-deleted edges. Strong context, though it doesn't explicitly contrast itself against a sibling tool by name in a use-this-not-that sense.

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

Deploy Server

Other Tools