mazarbul

Overview Schema Source Related Servers Discussions Admin

createEntity

Mint a structured entity directly from a kind and display name, skipping LLM extraction. Deduplicates by identifier so later relations can reference a stable uid.

Instructions

Mint a structured entity of a registered kind directly, bypassing LLM extraction — the write-side complement to relate. Use it when you already hold an entity as (kind, displayName) and need its entities/{uid} to assert a relation, without a remember() round-trip. Inputs: kind (a core kind or a registered extension kind — register first with defineEntityKind, check with introspect), displayName, optional confidence (default 1.0), identifiers (anchor the entity so the resolver attaches future mentions instead of duplicating), alternateNames, and properties (typed attributes validated against the kind's propertySchema). Deduplicates before minting: a matching identifier returns the existing entity (status reused); an existing same-name or near-duplicate of the same kind is NOT created (status duplicate_candidates) — inspect candidates, then reuse a uid, merge with mergeEntities, or retry with force=true to record a genuinely distinct entity that happens to share a name. On a plain create (status created) any advisory near-matches are still listed in candidates. Returns E_VALIDATION on a malformed kind, empty displayName, out-of-range confidence, or non-object properties.

Input Schema

Name	Required	Description
`kind`	Yes	Entity kind. A core kind (person, organization, place, project, event, document) or a registered extension kind (e.g. user:vehicle). Register a new kind with defineEntityKind first; introspect lists what exists.
`force`	No	Skip the duplicate check and mint a new entity even when one with the same name already exists. Use to record a genuinely distinct entity that shares a name with an existing one (e.g. a second real person named the same). Defaults to false.
`scope`	No	Scope to write into — pick by who should see it. Defaults to personal (private to the user, syncs to their devices). Use "project" for records tied to the current repo/codebase (shared with anyone who has repo access). Use "team" for the shared team brain (requires admitted membership, else E_PERMISSION).
`confidence`	No	Writer confidence in the entity's identity. Defaults to 1.0 (user-confirmed).
`properties`	No	Typed attribute values matching the kind's propertySchema (P3), e.g. {"vin":"…","make":"…"}. Validated on write when strict_attributes is enabled. Optional.
`displayName`	Yes	Human-readable label, e.g. "Mithril Corp" or "Eowyn".
`identifiers`	No	Strong/weak external identifiers to anchor the entity so the resolver attaches future mentions instead of minting a duplicate. Optional.
`alternateNames`	No	Other surface forms for this entity. Optional.

Output Schema

Name	Required	Description
`uid`	No	Bare ULID of the entity (set on status created/reused).
`kind`	No	The entity's kind (set on status created/reused).
`name`	No	AIP resource name of the entity (set on status created/reused). Pass to relate or get(entities/{uid}).
`status`	Yes	created = a new entity was minted; reused = an existing entity matched by identifier and is returned in uid/name; duplicate_candidates = NOT created because same-name or near-duplicate entities exist (see candidates) — reuse one, merge with mergeEntities, or retry with force=true.
`candidates`	No	Existing entities that match by name or embedding. On duplicate_candidates the create was refused; on created these are advisory near-matches you may want to merge.

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 burden and does: it discloses deduplication semantics per status (reused, duplicate_candidates, created), that same-name or near-duplicates are NOT minted silently, that advisory candidates are still listed on a plain create, and that E_VALIDATION fires on malformed kind, empty displayName, out-of-range confidence or non-object properties. That is unusually rich behavior disclosure 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?

Purpose and usage are front-loaded in the first two sentences, followed by dedup behavior and error surface, which is the right ordering. It loses a mark for the middle "Inputs:" enumeration, which duplicates what the schema already says and bloats an otherwise tight paragraph.

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 an 8-parameter mutation tool with nested identifier objects, no annotations, but a full output schema, the description covers what it must: prerequisites, dedup/override workflow, per-status outcomes and validation errors. Return shape is correctly left to the output schema, so nothing material is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents kind, force, confidence, identifiers, alternateNames and properties in detail; the description's "Inputs:" clause mostly restates it. It adds modest relational meaning — that identifiers anchor the resolver into a distinct lookup lane and that force overrides the duplicate gate — but not enough to exceed the baseline.

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 opens with a specific verb+resource: "Mint a structured entity of a registered kind directly, bypassing LLM extraction." It immediately positions itself against siblings — the write-side complement to relate, explicitly not a remember() round-trip — so an agent can distinguish createEntity from remember, relate, updateEntity and defineEntityKind without opening any schema.

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?

It gives an explicit use condition ("when you already hold an entity as (kind, displayName) and need its entities/{uid} to assert a relation") and then names the alternatives in the duplicate case: reuse a uid, merge with mergeEntities, or retry with force=true. The defineEntityKind/introspect prerequisite for extension kinds is stated outright, so there is nothing left to infer.

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