Skip to main content
Glama
Sign In
Neotoma

Neotoma

by markmhendrickson
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

create_relationship

Create a typed relationship between two entities. The relationship_type vocabulary is a runtime registry, not a fixed list: call list_relationship_types to read what this instance accepts, and register_relationship_type to add to it.

Instructions

Create a typed relationship between two entities. The relationship_type vocabulary is a runtime registry, not a fixed list: call list_relationship_types to read what this instance accepts, and register_relationship_type to add to it. Use EMBEDS when a container entity (e.g. blog post, document) embeds an asset entity (e.g. image, attachment): source_entity_id = container, target_entity_id = asset. For images/files stored in Neotoma: store the file via store (get source_id), create an image/media entity with source_id, then create_relationship(EMBEDS, post_entity_id, image_entity_id). Optional metadata: caption, order. Both source_entity_id and target_entity_id must be entities you own; store the entity first (or in the same store call), then link it.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "relationship_type": "<relationship_type>",
      "source_entity_id": "<source_entity_id>",
      "target_entity_id": "<target_entity_id>"
    },
    "name": "create_relationship"
  }
}

Input Schema

NameRequiredDescriptionDefault
user_idNoOptional explicit user id; inferred from authentication when omitted.
metadataNoOptional metadata attached to the relationship (e.g. `caption`, `order` for `EMBEDS` edges).
source_idNoOptional `sources` row id stamped as provenance on the relationship observation.
source_entity_idYesExisting entity id at the source end of the edge.
target_entity_idYesExisting entity id at the target end of the edge.
relationship_typeYesRelationship 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: -"Typed relationship category. Canonical structural types are\n`PART_OF`, `CORRECTS`, `REFERS_TO`, `SETTLES`,\n`DUPLICATE_OF`, `DEPENDS_ON`, `SUPERSEDES`, `EMBEDS`. Domain\ntypes (e.g. `works_at`, `owns`, `manages`) are also accepted.\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. Addedv0.15.0
  3. Removedv0.14.0
  4. Changed7 schema fields changedv0.13.0
    • addedInput schema / properties / metadata
      Added value: +{
+  "additionalProperties": true,
+  "description": "Optional metadata attached to the relationship (e.g.\n`caption`, `order` for `EMBEDS` edges).\n",
+  "type": "object"
+}
    • addedInput schema / properties / relationship_type
      Added value: +{
+  "description": "Typed relationship category. Canonical structural types are\n`PART_OF`, `CORRECTS`, `REFERS_TO`, `SETTLES`,\n`DUPLICATE_OF`, `DEPENDS_ON`, `SUPERSEDES`, `EMBEDS`. Domain\ntypes (e.g. `works_at`, `owns`, `manages`) are also accepted.\n",
+  "enum": [
+    "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"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / source_entity_id
      Added value: +{
+  "description": "Existing entity id at the source end of the edge.",
+  "type": "string"
+}
    • addedInput schema / properties / source_id
      Added value: +{
+  "description": "Optional `sources` row id stamped as provenance on the\nrelationship observation.\n",
+  "type": "string"
+}
    • addedInput schema / properties / target_entity_id
      Added value: +{
+  "description": "Existing entity id at the target end of the edge.",
+  "type": "string"
+}
    • addedInput schema / properties / user_id
      Added value: +{
+  "description": "Optional explicit user id; inferred from authentication\nwhen omitted.\n",
+  "type": "string"
+}
    • changedInput schema / required
      Previous value: -[]New value: +[
+  "relationship_type",
+  "source_entity_id",
+  "target_entity_id"
+]
  5. Addedv0.12.1
  6. Removedv0.11.0
  7. First observedv0.1.0

TDQS

A4.2/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 well: it discloses that the type vocabulary is instance-specific and discoverable at runtime, that both endpoints must be entities the caller owns, and that entities must be stored before linking. It does not cover duplicate-edge behavior, whether creation is idempotent, or the permission/auth model beyond inferred user id, which are meaningful gaps for a mutation tool.

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 core action and the registry caveat are front-loaded in the first two sentences, and the EMBEDS direction rule is stated crisply. The step-by-step image/file workflow is the longest segment and is useful but slightly over-specified for a description, making it efficient rather than maximally tight.

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 6-parameter write tool with a nested metadata object, no annotations, and no output schema, the description covers purpose, prerequisites, vocabulary discovery, and direction semantics. Missing are the return value (whether a relationship id comes back) and failure/duplicate semantics, which an agent needs when a write fails or is retried.

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 the baseline is 3, but the description adds real semantic value beyond the schema: it explains the directional meaning of source_entity_id (container) vs target_entity_id (asset) for EMBEDS and names concrete metadata keys (caption, order). It does not explain the source_id provenance parameter or user_id, so it is above baseline without being exhaustive.

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

Purpose4/5

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

States a specific verb+resource ('Create a typed relationship between two entities') and immediately explains the nature of the relationship type space (runtime registry, not fixed enum). It clearly separates itself from list_relationship_types and register_relationship_type, but never distinguishes itself from the very similar sibling 'create_relationships' (plural), leaving ambiguity about the single-vs-batch choice.

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

Usage Guidelines5/5

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

Explicitly names alternatives and the conditions that select them: call list_relationship_types to read the vocabulary, register_relationship_type to extend it, and use EMBEDS specifically for container-embeds-asset edges with the source/target direction spelled out. It also gives an ordered prerequisite workflow (store file -> get source_id -> create media entity -> link) and the ownership precondition.

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