NEXUS AGI

Create entity

create_entity

Create a new entity in the world model.

Always inserts a new node; it does not check for an existing entity with
the same name. To reuse-or-create by name, use ``relate_entities`` (which
also records a relation) or check with ``search_entities`` first.

Side effects: with the default ``hybrid`` strategy the entity is linked to
the NEXUS root entity (``belongs_to``); a creation episode, memory links
and an event are recorded; and entities with a very similar name may be
queued as merge proposals. For explicit links to specific entities use
``create_entity_cognitive``.

Returns the entity plus ``relations_created``, ``episode_id``,
``event_id`` and ``memory_links_created``.

Args:
    name: Human-readable name of the entity.
    entity_type: Type from the closed ontology (schema enum). Use
        'unclassified' if none fits.
    attributes: Optional key-value attributes.
    strategy: Auto-linking strategy:
        'hybrid' (default) or 'root' — link to the NEXUS root entity.
        'similar' — link (related_to) to the most recently created
        entity of the same type.
        'none' — no automatic links.

Input Schema

Name	Required	Default
`name`	Yes
`strategy`	No	hybrid
`attributes`	No
`entity_type`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 8, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations only declare the safety profile (readOnly false, idempotent false, destructive false); the description goes far beyond by enumerating concrete side effects — NEXUS root linking under hybrid, a creation episode, memory links, an event, and queued merge proposals — plus the exact return payload. This is behaviorally richer than the annotations permit alone.

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 purpose, then disambiguation, side effects, returns, and args — every section earns its place. It is somewhat long and the Args block partially restates field names, but each entry adds semantics (especially the strategy enum values), so the size is defensible.

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 mutation tool with no output schema and 0% param description coverage, the description closes both gaps: it describes the return fields (relations_created, episode_id, event_id, memory_links_created) and all four parameters. Nothing needed to invoke it correctly is missing.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must carry the burden, and it does: name, entity_type (closed ontology, with 'unclassified' fallback), attributes, and strategy with every value ('hybrid', 'root', 'similar', 'none') individually explained. This adds meaning well beyond the bare schema names.

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+resource ("Create a new entity in the world model") and immediately distinguishes itself from siblings by naming the alternative reuse-or-create path via relate_entities and search_entities. An agent knows exactly what this tool does versus create_entity_cognitive or update_entity.

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?

Explicit when/when-not guidance: "Always inserts a new node; it does not check for an existing entity with the same name." It then routes the agent to alternatives (relate_entities for reuse-or-create, search_entities to check first, create_entity_cognitive for explicit links), covering both the tool and its exclusion cases.

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

All NEXUS AGI tools Inspect

Try in Browser

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?