Neotoma

Overview Schema Source Related Servers Discussions Admin

create_interpretation

Create an interpretation row for an existing source from agent-extracted flat entities. Observations produced by this tool are linked to both source_id and interpretation_id.

Instructions

Create an interpretation row for an existing source from agent-extracted flat entities. Observations produced by this tool are linked to both source_id and interpretation_id. Use store with an interpretation block when the source-derived extraction can be batched in one store call.

Input Schema

TableJSON Schema

Name	Required	Description
`user_id`	No
`entities`	Yes
`source_id`	Yes
`relationships`	No
`idempotency_key`	No
`interpretation_config`	No	Audit configuration for a parser or agent-authored interpretation run. Callers may include extractor_type, extractor_version, model, prompt_hash, schema_version, agent_notes, and other provenance fields needed to explain how extracted observations were produced.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.25.0Oct 12, 2026

changedInput schema / properties / relationships / items / oneOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "metadata": {
-        "additionalProperties": true,
-        "type": "object"
-      },
-      "relationship_type": {
-        "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"
-      },
-      "source_index": {
-        "description": "Index into the entities array for the source entity.",
-        "minimum": 0,
-        "type": "integer"
-      },
-      "target_index": {
-        "description": "Index into the entities array for the target entity.",
-        "minimum": 0,
-        "type": "integer"
-      }
-    },
-    "required": [
-      "relationship_type",
-      "source_index",
-      "target_index"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "metadata": {
-        "additionalProperties": true,
-        "type": "object"
-      },
-      "relationship_type": {
-        "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"
-      },
-      "source_index": {
-        "description": "Index into the entities array for the source entity.",
-        "minimum": 0,
-        "type": "integer"
-      },
-      "target_entity_id": {
-        "description": "Existing target entity ID.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "relationship_type",
-      "source_index",
-      "target_entity_id"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "metadata": {
-        "additionalProperties": true,
-        "type": "object"
-      },
-      "relationship_type": {
-        "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"
-      },
-      "source_entity_id": {
-        "description": "Existing source entity ID.",
-        "type": "string"
-      },
-      "target_index": {
-        "description": "Index into the entities array for the target entity.",
-        "minimum": 0,
-        "type": "integer"
-      }
-    },
-    "required": [
-      "relationship_type",
-      "source_entity_id",
-      "target_index"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "metadata": {
-        "additionalProperties": true,
-        "type": "object"
-      },
-      "relationship_type": {
-        "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"
-      },
-      "source_entity_id": {
-        "description": "Existing source entity ID.",
-        "type": "string"
-      },
-      "target_entity_id": {
-        "description": "Existing target entity ID.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "relationship_type",
-      "source_entity_id",
-      "target_entity_id"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "metadata": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "relationship_type": {
+        "description": "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).",
+        "type": "string"
+      },
+      "source_index": {
+        "description": "Index into the entities array for the source entity.",
+        "minimum": 0,
+        "type": "integer"
+      },
+      "target_index": {
+        "description": "Index into the entities array for the target entity.",
+        "minimum": 0,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "relationship_type",
+      "source_index",
+      "target_index"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "metadata": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "relationship_type": {
+        "description": "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).",
+        "type": "string"
+      },
+      "source_index": {
+        "description": "Index into the entities array for the source entity.",
+        "minimum": 0,
+        "type": "integer"
+      },
+      "target_entity_id": {
+        "description": "Existing target entity ID.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "relationship_type",
+      "source_index",
+      "target_entity_id"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "metadata": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "relationship_type": {
+        "description": "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).",
+        "type": "string"
+      },
+      "source_entity_id": {
+        "description": "Existing source entity ID.",
+        "type": "string"
+      },
+      "target_index": {
+        "description": "Index into the entities array for the target entity.",
+        "minimum": 0,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "relationship_type",
+      "source_entity_id",
+      "target_index"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "metadata": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "relationship_type": {
+        "description": "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).",
+        "type": "string"
+      },
+      "source_entity_id": {
+        "description": "Existing source entity ID.",
+        "type": "string"
+      },
+      "target_entity_id": {
+        "description": "Existing target entity ID.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "relationship_type",
+      "source_entity_id",
+      "target_entity_id"
+    ],
+    "type": "object"
+  }
+]

Addedv0.15.0May 31, 2026
Removedv0.14.0May 22, 2026
Addedv0.12.1May 13, 2026

TDQS

B3.1/5.0

Behavior2/5

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

No annotations provided, so the description carries full burden. It states observations are linked to source_id and interpretation_id, but doesn't disclose permissions needed, side effects (mutation), idempotency behavior (despite idempotency_key param existing), or what happens if entities are malformed. For a mutation tool with zero annotations, this is a significant gap.

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?

Two efficient sentences, front-loaded with the core action and followed by the routing alternative. No wasted words, though the bolding of 'store' is slightly noisy.

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

Completeness2/5

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

Highly complex tool: 6 params, nested objects, complex relationships oneOf, no output schema, no annotations, low schema coverage (17%). The description only covers the basic purpose and a routing hint, omitting critical details about the relationships parameter's runtime-registry semantics, idempotency behavior, and the meaning of interpretation_config fields.

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

Parameters2/5

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

Schema coverage is 17%, so the description must compensate. It explains observations are linked to source_id and interpretation_id, but doesn't clarify the entities array structure, relationships parameter (which has complex oneOf schemas with runtime registry vocabulary), interpretation_config audit fields, or idempotency_key usage. The relationships parameter alone has four variants with runtime-registry semantics that the description ignores entirely.

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?

Clear specific verb+resource: 'Create an interpretation row for an existing source from agent-extracted flat entities.' This distinguishes it from siblings like list_interpretations or store. It implies a specific workflow (agent extraction to interpretation), which is more informative than generic create tools.

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?

Explicit routing: 'Use **store** with an interpretation block when the source-derived extraction can be batched in one store call.' This tells the agent when to use store instead. However, it doesn't fully clarify when to use this tool vs store (the inverse condition), leaving some ambiguity about the exact boundary.

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

Deploy Server

create_interpretation

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools