Stores a new factual claim or memory by inserting text into a named collection under a numeric ID, with automatic vectorization for later retrieval.
Store a new factual claim or memory: insert text into collection under numeric id (auto-vectorized). Returns a JSON object {ok: true, id} on success or {ok: false, error} on failure.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| text | Yes | ||
| metadata | No | ||
| collection | Yes |
Changes observed during successful MCP inspections.
v4.2.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does well to disclose the auto-vectorization side effect and the exact return contract ({ok: true, id} / {ok: false, error}), which is valuable given there is no output schema. It omits overwrite/upsert behavior on duplicate id, whether errors are raised or returned, and any cost implications of embedding each insert.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, with the core action front-loaded and the return contract appended where it is useful. Nothing is repeated from the schema or title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, no output schema, 0% parameter description coverage, and a nested object parameter, the description should explain at minimum the metadata object and duplicate-id behavior. The return-shape disclosure is a real strength, but the parameter and error-path gaps leave the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it only partly does: it clarifies that `id` is numeric and that `text` is what gets vectorized. The `metadata` parameter — a nested object, the highest-ambiguity field — is never mentioned, so an agent has no guidance on its shape or purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb (insert/store), a concrete resource (text into a collection under a numeric id), and adds the non-obvious behavioral detail that the text is auto-vectorized. The phrasing 'new factual claim or memory' distinguishes this write path from the search/graph siblings without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this versus alternatives, and no mention of prerequisites — notably that the target `collection` presumably must already exist (cf. hyperspace_create_collection). The word 'new' hints at insert-vs-update semantics but nothing tells the agent how to handle an id that already exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.