Shared long-term memory for AI agents: save and recall context as a searchable knowledge graph.
Scored across 21 tools
Several retrieval tools overlap in surface purpose (search_memory, find_memories_by_entity, find_related_memories, find_memory_connections, query_memory_graph, plus partner variants), but descriptions consistently and explicitly state when to use each and which tool to prefer instead. Some boundaries remain nuanced, yet an agent can generally select correctly.
All tools follow a predictable snake_case verb_noun/verb_resource pattern such as describe_memory_schema, find_memories_by_entity, get_memory_content, list_memory_timeline, query_memories_with_sql, save_memory, search_memory, and update_memory. Partner tools consistently insert a partner qualifier into the same naming scheme.
Twenty-one tools is heavy, but the server covers a broad memory platform: own and partner search, graph traversal, SQL, content retrieval, lifecycle writes, schema, app actions, target/project management, and guides. The paired partner tools justify much of the count, though it sits near the upper bound for easy tool selection.
Core memory lifecycle coverage is strong: save, search, retrieve content, update, soft-hide, schema/SQL/graph access, partner reading, and project/target inspection. The main gaps are intentional but still real: no hard-delete or un-hide tool, and target switching is only user-mediated rather than directly performable through a tool.
Publish a one-page AiAkiv card that summarizes memory the user already has.
Use this when the user asks to turn something from their memory into a
card, a shareable summary page, or a link they can share. Do not use it to
save a memory; use `save_memory` for that.
Creating is publishing: the card page and two share images are live on the
open web the moment this returns. The card is unlisted, so nobody finds it
without the address, but anyone holding the address can open it with no
login. It cannot be edited or taken down from here. Write it only from
memory the user can already read; the server never calls a model. Listing,
deleting, search visibility and filing tags for cards the user made are
handled by the user in the AiAkiv web console.
Limits, checked by the card service after it trims whitespace and drops
empty items: title up to 80 characters; 3 to 5 bullets of up to
120 characters each; conclusion up to 200 characters; source_count
an integer of 0 or more; up to 3 tags of up to 20 characters each; body
up to 30,000 characters. Title, bullets, conclusion and tags are single
lines; line breaks in them collapse to spaces.
Fitting the images: bullets share one fixed block of vertical space, so
their count and length trade against each other. A line holds about 31
Korean characters (Latin letters and spaces fit more) and each bullet gets
up to 3 lines, but when the total does not fit, every bullet is cut to
fewer lines and shortened with an ellipsis, so staying under 120 characters
is not enough. With a title of up to about 20 Korean characters and a
conclusion of up to about 30, three or four bullets of up to about 40
Korean characters each fit both images; with 5 bullets the last one
is left out of the wide image. The page always shows the full text. Aim to
fit on the first try: creating again makes a new card and leaves this one
published until the user deletes it.
Args:
title: The card title, one line, up to 80 characters.
bullets: 3 to 5 key points, one line each, up to 120 characters each.
conclusion: A one-line conclusion, up to 200 characters.
source_count: How many memories the card was written from. Defaults to 0.
tags: Up to 3 search terms for the card, up to 20 characters each. They are drawn into the images and cannot be changed later. Defaults to none.
body: Optional longer text shown on the page but not in the images, up to 30,000 characters of restricted markdown: paragraphs, `##` headings, `-` and `1.` lists, `>` quotes, inline and fenced code, bold, italic, http(s) links and `---`. Anything else shows as plain text.
Returns:
On success `{notice, ok, app, key, url, og_url, square_url, fit?, ...}`.
`notice` comes first and states what just became public and how to take
it down; it is information the user needs to see. `url` is the card
page; `og_url` and `square_url` are the share images. `fit`, present
only when an image cut something, names the bullets that were shortened
or left out and how much to shorten them. On failure
`{error, message or hint, field?}` and no card was made: `invalid_card`
names the field to fix, `quota_exceeded` carries the window, limit and
used counts.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Optional longer text shown on the page but not in the images, up to 30,000 characters of restricted markdown: paragraphs, `##` headings, `-` and `1.` lists, `>` quotes, inline and fenced code, bold, italic, http(s) links and `---`. Anything else shows as plain text. | |
| tags | No | Up to 3 search terms for the card, up to 20 characters each. They are drawn into the images and cannot be changed later. Defaults to none. | |
| title | Yes | The card title, one line, up to 80 characters. | |
| bullets | Yes | 3 to 5 key points, one line each, up to 120 characters each. | |
| conclusion | Yes | A one-line conclusion, up to 200 characters. | |
| source_count | No | How many memories the card was written from. Defaults to 0. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Return the memory database's tables, columns, and types.
Use this when a SQL query needs the schema first. Do not use it to read
stored content; it describes structure alone.
Read-only and cheap. The schema itself is public information; the data in
those tables stays protected by RLS.
Returns:
Every table with its columns and their types.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and not destructive. The description adds useful context: it is 'cheap' and mentions RLS protection, which adds behavioral nuance beyond annotations. No contradiction.
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?
The description is compact, with key purpose and usage in the first two sentences, and additional behavioral context in the third. Every sentence adds value; no fluff.
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?
Given no parameters and an output schema (implicitly mentioned by the 'Returns' section), the description fully covers what an agent needs: purpose, usage guidance, behavioral traits, and return value summary. Nothing is missing.
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?
There are no parameters, so the schema is trivial. The description doesn't need to explain parameters; it correctly focuses on the tool's output and usage, which is sufficient. Baseline for 0 params is 4.
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?
The description clearly states the tool returns schema (tables, columns, types), which is specific and distinguishes it from sibling tools focused on content retrieval or manipulation. It uses a specific verb 'Return' and resource 'memory database's tables, columns, and types', making it unambiguous.
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?
It explicitly states when to use ('when a SQL query needs the schema first') and when not to use ('Do not use it to read stored content'), and distinguishes from alternatives by stating it 'describes structure alone'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up entities by name and return the events they appear in.
Use this when the user names a person, project, system, or term and wants
what is recorded about it. Do not use it for an open question about a topic;
use `search_memory` for that.
Read-only. Scope is decided by the server and reported in `searched_scope`.
Args:
entity_name: Substring to match, case-insensitive. May be empty when
`entity_id` is given.
entity_id: Exact entity id (`ent_...`), for following an entity a
previous response named. Same scope as a name lookup; it takes
precedence over `entity_name`.
limit: Max events per entity (1-50, clamped).
Returns:
`{query_name, hint, suggestion, matches, tag_matches, searched_scope}`.
The same substring also matches tags, which arrive in `tag_matches`.
Each match's `top_partners` is the co-occurrence ranking across the whole
scope, which is what "which entity co-occurs most with X?" asks for;
`hint.entities[].hit_count` counts only within this response's sample.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max events per entity (1-50, clamped). | |
| entity_id | No | Exact entity id (`ent_...`), for following an entity a previous response named. Same scope as a name lookup; it takes precedence over `entity_name`. | |
| entity_name | No | Substring to match, case-insensitive. May be empty when `entity_id` is given. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive safety, so the description adds value by disclosing that scope is server-decided and reported in `searched_scope`, that the substring also matches tags, and that `top_partners` is a whole-scope ranking while `hit_count` is sample-limited. No contradiction with annotations.
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?
The description is well-structured with purpose, usage, Args, and Returns sections, and front-loads the most important guidance. The Args section is redundant with the schema, but the Returns clarification earns its place.
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 read-only lookup with three fully documented parameters and an output schema, the description covers when to use it, scope behavior, tag matching, and the meaning of ranking fields. Nothing needed for correct invocation is missing.
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 coverage is 100%, so the schema already documents all three parameters. The description's Args section largely repeats those descriptions and adds no new parameter-level meaning, though it does reinforce precedence and case-insensitivity.
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?
The description opens with a specific verb and resource ('Look up entities by name and return the events they appear in') and immediately distinguishes itself from search_memory. This makes the tool's role clear among a large sibling set.
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?
It gives an explicit trigger condition ('when the user names a person, project, system, or term'), an explicit exclusion ('Do not use it for an open question about a topic'), and names the alternative (`search_memory`). It also explains when `entity_id` should be used, which is strong routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Walk the entity-event graph outward from what a sentence finds, one or two hops.
Search returns the closest events; this returns events connected to them
through shared entities the vector ranking left outside the top hits, each
candidate carrying its bridge entity, path, and evidence.
Use this when the user asks what is linked to something that a ranked search
did not surface. Do not use it for a direct answer to a question; use
`search_memory` for that. Do not use it when the request states a pattern to
match; use `query_memory_graph` for that.
Read-only. Candidates are unverified pointers, not established facts.
Args:
sentence: One complete sentence, not keywords. Required for every
relation except `explore`, which forbids it.
anchor_entity_id: An entity id to walk from instead of a vector entry;
this path does not depend on the ranking. Required for
`relation="explore"`.
relation: `similar` (default, time-stratified), `before`, `after`,
`evolution`, `contrast`, or `explore`. `before` and `after` require
exactly one of `reference_time` or `anchor_event_id`; there is no
implicit "now". `contrast` returns candidates narrowed by cosine
without judging opposition, which the reader does. `explore` needs
`anchor_entity_id`, forbids `sentence`, and returns
`grounding="exploration"`.
reference_time: ISO 8601 basis for `before` and `after`.
anchor_event_id: Event basis for `before` and `after`.
top_n: Max candidates per round (server-capped).
expansion_rounds: 1 (default) or 2. Round 2 re-expands from the round-1
picks through bridges not used in round 1, reaching things two
structural steps away, so a 2-round call can return up to twice
`top_n` in total. Each candidate carries its `round`.
Returns:
`{candidates: [{event_id, summary, path, bridge_entity_id, cosine,
cosine_percentile, timestamp}], grounding, grounding_basis, bridges,
entry, searched_scope, truncations}`. `grounding` is `grounded`, `weak`,
`absent`, or `exploration`; `absent` means no neighbourhood exists for
this sentence in scope, an honest empty rather than a failure.
`event_id` feeds `get_memory_content`.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | Max candidates per round (server-capped). | |
| relation | No | `similar` (default, time-stratified), `before`, `after`, `evolution`, `contrast`, or `explore`. `before` and `after` require exactly one of `reference_time` or `anchor_event_id`; there is no implicit "now". `contrast` returns candidates narrowed by cosine without judging opposition, which the reader does. `explore` needs `anchor_entity_id`, forbids `sentence`, and returns `grounding="exploration"`. | similar |
| sentence | No | One complete sentence, not keywords. Required for every relation except `explore`, which forbids it. | |
| reference_time | No | ISO 8601 basis for `before` and `after`. | |
| anchor_event_id | No | Event basis for `before` and `after`. | |
| anchor_entity_id | No | An entity id to walk from instead of a vector entry; this path does not depend on the ranking. Required for `relation="explore"`. | |
| expansion_rounds | No | 1 (default) or 2. Round 2 re-expands from the round-1 picks through bridges not used in round 1, reaching things two structural steps away, so a 2-round call can return up to twice `top_n` in total. Each candidate carries its `round`. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond those: results are 'unverified pointers, not established facts', the semantics of `grounding` values (including 'absent' as an honest empty), and the expansion_rounds behavior (re-expansion through unused bridges). This is valuable transparency beyond what annotations state.
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?
The description is long but structured: it leads with the core behavior, then usage guidance, then parameter details. The parameter section duplicates the schema text nearly exactly, which is redundant and could be trimmed. However, the redundancy is not fluff; it is informative for agents that may not parse the schema deeply. It is appropriately sized for the tool's complexity, but not maximally concise.
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?
The description is exceptionally complete for a tool with 7 parameters and an output schema. It covers all relation-specific constraints (e.g., `before`/`after` require exactly one time reference, `explore` forbids `sentence`), explains the return object shape, defines `grounding` values, and clarifies edge cases like 'absent'. The output schema also documents return fields, but the description goes beyond that to explain semantics, leaving no gaps for correct invocation.
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 100% – the input schema already contains nearly identical, detailed descriptions for every parameter. The description repeats most of that verbatim (e.g., relation requirements, top_n cap). It adds no new meaning beyond the schema, so the baseline of 3 applies. Minor additions like the round behavior for expansion_rounds are also in the schema, so no extra credit.
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?
The description opens with a specific verb ('walk') and resource ('entity-event graph'), and clearly distinguishes itself from siblings: 'Search returns the closest events; this returns events connected to them through shared entities...' It explicitly names alternatives (`search_memory`, `query_memory_graph`) and the conditions that route to them, making the tool's unique role unmistakable.
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?
The description gives an explicit use case ('when the user asks what is linked to something that a ranked search did not surface') and explicit negative cases ('Do not use it for a direct answer to a question; use `search_memory` for that. Do not use it when the request states a pattern to match; use `query_memory_graph` for that.'). This is textbook guidance, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Walk the entity-event graph across the caller's org and a partner org.
Use this when the user asks what a linked partner team's memory connects to
something of their own. Do not use it for a plain partner lookup; use
`search_partner_memory` for that. Do not use it when the request states a
pattern to match; use `query_partner_memory_graph` for that.
Reads the partner org and writes nothing to either side. Candidates are
unverified pointers, not established facts. Calls are handled
one at a time per org: a second link call issued while one is in flight
comes back with `reason: busy` without running. A revoke during the call
aborts it with an explicit error rather than a shortened answer.
Args:
link_id: Which link to read through, from `list_partner_links`.
sentence: A complete sentence; required unless `relation="explore"`.
anchor_entity_id: An entity of the caller's own to start from; required
for `explore`. Entry happens in the caller's org either way.
relation: `similar`, `before`, `after`, `evolution`, `contrast`, or
`explore` — same meanings and argument requirements as
`find_memory_connections`.
reference_time: ISO 8601 basis for `before` and `after`.
anchor_event_id: Event basis for `before` and `after`. Passing only
`link_id` and `anchor_event_id` is read as the earlier call form, a
walk from that event, and the response carries
`compat="v1_anchor_walk"`.
top_n: Max candidates per round (server-capped).
expansion_rounds: 1 (default) or 2, as in `find_memory_connections`.
Returns:
`{status, link_id, remote_org, candidates, bridges, grounding,
grounding_basis, entry, truncations, budget}`. Each candidate carries
`side`, and a partner candidate's `content_pointer` names
`get_partner_memory_content` and this link. Aliased bridges carry
`df_home` and `df_remote`, how common the entity is on each side. The
partner side is not searched at entry and is reached only through
bridges, so this never reports `absent`; see
`grounding_basis.remote_entry_not_searched`.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | Max candidates per round (server-capped). | |
| link_id | Yes | Which link to read through, from `list_partner_links`. | |
| relation | No | `similar`, `before`, `after`, `evolution`, `contrast`, or `explore` — same meanings and argument requirements as `find_memory_connections`. | similar |
| sentence | No | A complete sentence; required unless `relation="explore"`. | |
| reference_time | No | ISO 8601 basis for `before` and `after`. | |
| anchor_event_id | No | Event basis for `before` and `after`. Passing only `link_id` and `anchor_event_id` is read as the earlier call form, a walk from that event, and the response carries `compat="v1_anchor_walk"`. | |
| anchor_entity_id | No | An entity of the caller's own to start from; required for `explore`. Entry happens in the caller's org either way. | |
| expansion_rounds | No | 1 (default) or 2, as in `find_memory_connections`. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this read-only and non-destructive, and the description adds meaningful behavior beyond that: it writes nothing to either side, candidates are unverified pointers, concurrent calls return reason 'busy', a revoke aborts with an explicit error, and the partner side is never searched at entry. This is rich, actionable transparency.
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?
The description is long but structured and front-loaded: usage guidance first, then behavior, then parameters, then return semantics. Every section earns its place, and the parameter notes are tightly scoped to non-obvious cases rather than re-explaining the schema.
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 an 8-parameter tool with output schema present, the description is complete. It covers concurrency limits, abort behavior, entry semantics, relation requirements, compatibility call form, and return-field nuances such as side, content_pointer, bridge aliases, and why absent is never reported.
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 coverage is 100%, so the baseline is 3. The description adds real value beyond the schema: it clarifies when sentence is required, that anchor_entity_id is required only for explore, that entry happens in the caller's org either way, and that passing only link_id plus anchor_event_id is read as the v1 anchor-walk call form.
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?
The description opens with a specific verb and resource: 'Walk the entity-event graph across the caller's org and a partner org.' It also distinguishes itself from sibling tools by explicitly naming search_partner_memory and query_partner_memory_graph and stating what they are for.
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?
Guidance is explicit: use when the user asks how a linked partner team's memory connects to something of the caller's own, and do not use it for plain partner lookup (search_partner_memory) or pattern matching (query_partner_memory_graph). This leaves no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return an AiAkiv guide document for a topic, as text.
Use this when the user asks how to use AiAkiv or MWeft, wants the tutorial,
or pastes an `aiakiv.com/llms-*.txt` link that cannot be opened here. The
result is a reference document to read and draw on, not a set of commands.
Read-only.
Args:
topic: One of `"tour"` (first-run tutorial, llms-tour.txt),
`"playbook"` (projects and personas, llms-playbook.txt), `"setup"`
(install and connect, llms.txt), `"demo"` (public demo-memory
walkthrough, llms-tour-demo.txt), or `"console"` (the console app
actions for teams, links, audit and cards, llms-console.txt). It
defaults to `"tour"`, so a request for one of the other four
carries the topic. Any other value returns an error listing these
five.
Returns:
`{topic, source_url, content, cached, available_topics}` — or
`{error, hint}` when the topic is unknown or the fetch fails.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | One of `"tour"` (first-run tutorial, llms-tour.txt), `"playbook"` (projects and personas, llms-playbook.txt), `"setup"` (install and connect, llms.txt), `"demo"` (public demo-memory walkthrough, llms-tour-demo.txt), or `"console"` (the console app actions for teams, links, audit and cards, llms-console.txt). It defaults to `"tour"`, so a request for one of the other four carries the topic. Any other value returns an error listing these five. | tour |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description explains the return format and error handling. It specifies that unknown topics return an error listing valid topics, and it mentions caching ('cached' field). The annotations already indicate it is safe and idempotent, and the description adds useful details on behavior.
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?
The description is well-structured with clear sections (purpose, usage, read-only, args, returns). It is front-loaded with the most important information, uses bullet points for enumeration, and every sentence adds value without redundancy.
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?
The description fully explains what the tool returns, including a schema of the return object, and the parameter is thoroughly documented. It covers error conditions and reference to source files. Given the tool's simplicity (only one param) and existing annotations, the description is complete for an agent to invoke correctly.
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?
The schema description covers 100% of the parameter, and the description repeats the parameter details. However, it also adds context about default value and error behavior, but since high schema coverage, baseline of 3 is appropriate.
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?
The description clearly states the tool's purpose: returning an AiAkiv guide document for a topic. It specifies the resource (guide document) and the verb ('Return'), and distinguishes it from other memory-related sibling tools by focusing on documentation rather than data operations. It also lists the exact topics and their meanings.
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?
It explicitly states when to use this tool (when user asks for AiAkiv usage, tutorial, or pastes a link) and when not (since it is a reference document, not commands). It also differentiates from siblings by focusing on guides, while siblings handle memory data directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the stored text of one event.
Use this when a summary from a search or lookup result lacks the detail
needed to answer. Do not use it to browse a topic; it takes one event id.
Read-only. Long bodies arrive in pieces: `content` is a slice and
`char_count` is the body's total length, so while `next_offset` is not null
the body is incomplete — call again with `offset=next_offset` and join the
pieces until `next_offset` is null. A partial body is not the whole text.
Args:
event_id: `events.id` (`ev_...`) or `vector_id` (`vec_...`).
include_raw: True fetches the full body from `storage_uri`; False
returns metadata alone, which suits large files and test queries.
offset: Start character of the slice (default 0). Pass the previous
response's `next_offset` to continue.
limit: Characters to return in this call (default 15000, max 30000).
Larger values are clamped, because the transport drops oversized
responses silently and paging is what avoids that.
Returns:
`{event_id, found, summary, content, char_count, offset, returned_chars,
next_offset, storage_uri, section_heading, domain, inline_meta}`.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Characters to return in this call (default 15000, max 30000). Larger values are clamped, because the transport drops oversized responses silently and paging is what avoids that. | |
| offset | No | Start character of the slice (default 0). Pass the previous response's `next_offset` to continue. | |
| event_id | Yes | `events.id` (`ev_...`) or `vector_id` (`vec_...`). | |
| include_raw | No | True fetches the full body from `storage_uri`; False returns metadata alone, which suits large files and test queries. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral detail beyond that: paging semantics, partial-body incompleteness, silent transport drops for oversized responses, and the meaning of include_raw. This is exactly the kind of context an agent needs to invoke the tool correctly.
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?
The description is detailed but every sentence earns its place: purpose, usage boundary, paging behavior, parameter explanations, and return shape. It is front-loaded with the most important information and uses clear structure.
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?
Given the output schema, annotations, and a description covering usage, paging, parameter behavior, and return fields, nothing an agent needs to call this tool correctly is missing. It is fully self-sufficient.
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 100%, so the schema fully documents all four parameters. The description repeats the same parameter meanings without adding significant new semantics beyond what the schema already provides. Baseline 3 is appropriate.
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?
The description opens with a specific verb and resource: 'Fetch the stored text of one event.' It also clarifies the scope ('takes one event id') and distinguishes itself from browsing/search tools, making its purpose unmistakable even among many sibling tools.
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?
Explicitly states when to use it ('when a summary from a search or lookup result lacks the detail needed to answer') and when not to ('Do not use it to browse a topic; it takes one event id'). This gives an agent clear selection criteria without needing to inspect other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one linked partner event's body, paged.
Use this when a partner search result's summary lacks the detail needed to
answer. Do not use it for the caller's own events; use
`get_memory_content` for that.
Reads the partner org and writes nothing. It takes an `event_id` and no raw
storage pointer, because the link surfacing that event is what grants its
body. Calls are handled one at a time per org: a second link call issued while
one is in flight comes back with `reason: busy` without running.
Args:
link_id: The link the event came from.
event_id: From `search_partner_memory` results.
offset: Start character (default 0).
limit: Characters to return (server-capped).
Returns:
`{status, link_id, remote_org, found, event_id, summary, content,
char_count, offset, returned_chars, next_offset}`. While `next_offset` is
not null the body is incomplete — call again with `offset=next_offset`.
`found: false` is the same answer whether the event is absent or outside
the link's scope.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Characters to return (server-capped). | |
| offset | No | Start character (default 0). | |
| link_id | Yes | The link the event came from. | |
| event_id | Yes | From `search_partner_memory` results. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses a per-org concurrency limit ('a second link call issued while one is in flight comes back with `reason: busy` without running'), the pagination contract (`next_offset` loop), and the semantic ambiguity of `found: false` (absent vs. out-of-scope are indistinguishable). It also explains the authorization model: the link is what grants the body, hence no storage pointer.
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?
The one-line summary is front-loaded, followed by tightly grouped usage, behavior, Args, and Returns sections. Every sentence earns its place — the busy/concurrency note and the found:false ambiguity are actionable, not padding. Length is justified by the tool's pagination and concurrency complexity.
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?
Given the tool's complexity (pagination, partner-org scoping, concurrency limits), the description covers everything an agent needs: when to call it, when to use the sibling instead, how to page through results, what busy means, and how to interpret found:false. The explicit Returns contract complements the output schema rather than duplicating it.
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 coverage is 100%, so the baseline is 3. The Args section largely repeats the schema verbatim, but the narrative adds meaning beyond it: it explains the link_id/event_id relationship ('the link surfacing that event is what grants its body') and how offset/limit participate in the pagination loop via `next_offset`. That pushes it a step above baseline, though the Args block itself adds no new parameter detail.
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?
Opens with a specific verb+resource+mode: 'Read one linked partner event's body, paged.' It then explicitly distinguishes itself from the sibling `get_memory_content` ('Do not use it for the caller's own events'), so an agent can tell them apart without inspecting schemas.
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?
States exactly when to use it ('when a partner search result's summary lacks the detail needed to answer') and when not to ('Do not use it for the caller's own events; use `get_memory_content` for that'), naming the alternative explicitly. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report where saves currently go, and how to change it.
The target is the signed-in account plus the project coordinates: a team
name, a save domain, and a save group.
Use this when the user asks where their memory is being saved, asks to switch
project, or when expected memory seems missing and the account or project may
have changed. It does not change the target. On a Main-following connection
the switch happens when the user opens `switch_url` and clicks; the `note`
field says how switching works on this connection. On a pinned connection
(`binding` = `folder` or `api-key`) `switch_url` is null: the console
cannot move it, and `switchable_via` says what the user changes instead.
Read-only.
Returns:
`{team, account, account_email, project, binding, read_only, link_id,
save_domain, save_group, switch_url, switchable_via,
multi_connection_note?, persona?, emergency_notice?, note}`. `binding`
says what the target is pinned to:
`folder` and `api-key` mean this connection is pinned to that project and
a console switch elsewhere does not move it (so `switch_url` is null);
`main` means it follows the account-wide preset and can change
mid-session; `public-read` and `link-read` are read-only binds where
saving is disabled. `multi_connection_note` appears only when `binding`
is `main`: saves belong on a `folder` or `api-key` AiAkiv connection if
the conversation has one. `persona`, when present, is a project-level
note set by the project owner in the web console.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Hide a saved event from all recall — search, neighbors, and derived layers.
Use this when the user says a memory was saved by mistake, landed in the
wrong project, or has been superseded. Do not use it to remove data
permanently: this is a reversible hide rather than a delete, and un-hiding is
an operator action, not a tool.
Writes to an existing record. Events belonging to another team are refused.
A memory that an app manages (for example a work published by an app) cannot
be hidden while that work is archived, or while the account's "Write
directly into app memory" permission is off; only a human can turn that on.
Args:
event_id: The event to hide.
Returns:
`{event_id, deprecated, hidden, changed}` — or `{error}` when the id is
empty, not found, belongs to another org, or is app-managed memory
(`app_managed_read_only`, `app_memory_write_disabled`).
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes | The event to hide. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses that this is a reversible hide, that it writes to an existing record, that cross-team events are refused, and that app-managed memory is blocked unless a human enables the write permission. It also enumerates the error conditions, which is unusually rich behavioral context.
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?
Front-loaded with purpose and routing in the first two sentences, and the behavioral caveats follow logically. The structured Args/Returns blocks are somewhat redundant given the schema and existing output schema, but the prose itself is tight.
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 single-parameter mutation tool with annotations and an output schema, the description covers purpose, alternatives, reversibility, auth/permission constraints, and error cases. Nothing an agent needs 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter and schema coverage is 100%, so the schema already carries the semantics; the description merely restates 'event_id: The event to hide.' Per the baseline for high schema coverage, a 3 is appropriate, and it adds no format or syntax detail beyond the schema.
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 specific verb (hide) and resource (a saved event/memory) and pins the scope precisely: 'from all recall — search, neighbors, and derived layers.' This clearly distinguishes it from siblings like update_memory, save_memory, and the search/query tools.
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?
Explicitly names when to use it (memory saved by mistake, landed in wrong project, superseded) and when not to (permanent removal), and clarifies that un-hiding is an operator action rather than a sibling tool. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the projects the signed-in account can save to or read.
Use this when the user asks which projects they have, which one they are
saving to, or wants to move their saves elsewhere. It does not perform the
switch: the user's click on a project's `switch_link` is the switch.
Read-only.
Returns:
`{projects: [{project, team, save_domain, save_group, is_main,
is_this_connection, read_only?, switch_url, switch_link}], main_project,
main_paused?, display, note}`. Each `switch_link` is a clickable link;
the user's click on it performs the switch. `is_main` marks the
account-wide target; `is_this_connection` marks the project this
connection is folder-bound to. Entries with `read_only` are public
targets the account can read without owning a preset, such as a shared
demo. `main_paused`, when present, means the user switched Main off in
the console. A wanted memory is located by its `team`, not by an exact
project name.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Return events in chronological order for an entity, tag group, or domain.
Use this when the user asks how something developed over time, or what
happened in a period. Do not use it to rank by relevance to a question; use
`search_memory` for that.
Read-only. The domain is decided by the server and reported in
`searched_scope`.
Args:
entity_id: Return events involving this entity, from
`find_memories_by_entity`.
cg_id: Return events carrying this tag group, named by the group ids in
a search response's `hint.categories`.
days: Restrict to the last N days.
limit: 1-200 (default 20).
Returns:
`{mode, anchor, events, total, truncated, searched_scope}`. With neither
`entity_id` nor `cg_id`, the flow covers the whole domain.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Restrict to the last N days. | |
| cg_id | No | Return events carrying this tag group, named by the group ids in a search response's `hint.categories`. | |
| limit | No | 1-200 (default 20). | |
| entity_id | No | Return events involving this entity, from `find_memories_by_entity`. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces 'Read-only.' More importantly, it adds context not in annotations: the domain is server-decided and reported in `searched_scope`, and with neither entity_id nor cg_id the flow covers the whole domain. This goes beyond the structured annotations.
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?
The description is well structured and front-loaded with purpose and usage. However, the Args block largely duplicates the schema descriptions verbatim, which is redundant given 100% schema coverage. Still, the extra context sentences (whole-domain behavior, output shape) justify the overall length, so it is acceptable.
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?
The description covers why, when, how to use (parameters), and what to expect in return (the `{mode, anchor, events, total, truncated, searched_scope}` object). It also notes the whole-domain behavior when filters are omitted. Since an output schema exists, this is complete enough for reliable tool selection and invocation.
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 100%, so the baseline is 3. The description adds value by clarifying parameter combinations: 'With neither `entity_id` nor `cg_id`, the flow covers the whole domain.' This is a meaningful behavioral note not expressed in the schema and helps the agent understand the effect of omitting both optional filters.
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?
The description states a specific action and resource: 'Return events in chronological order for an entity, tag group, or domain.' It also distinguishes itself from `search_memory` by explicitly saying it is not for relevance ranking, which makes the tool's purpose unmistakable.
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?
It gives explicit when-to-use guidance ('when the user asks how something developed over time, or what happened in a period') and when-not-to-use guidance with a named alternative ('use `search_memory` for that'). This is exactly what the dimension asks for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the org links the caller can read through, and whether each works now.
Use this when the user asks which partner teams they can read, or when a link
tool returned an error and the reason needs checking. Do not use it to read
partner content; the partner tools (`search_partner_memory`,
`find_partner_memory_connections`, `query_partner_memory_graph`,
`get_partner_memory_content`) do that.
Read-only and local: it keeps answering while the partner org is down, which
is when its answer matters most.
Returns:
`{status, count, provided_link_count, links: [{link_id, partner_org_id,
status, usable, blocked_reason, contract_version, reconsent: {mine,
partner}, expires_at, created_at}]}`. `link_id` is what every partner
tool takes, and `usable` says which links will answer.
`blocked_reason` names what to fix: `link_not_active` (suspended,
pending, or revoked), `contract_version_too_old` (both owners
re-consent — `reconsent` says who is missing), `link_expired`,
`remote_org_unavailable`, or `principal_not_active` (this direction is
closed).
Links run one way, and the ones **this** org provides are not listed:
they open our memory to the other team, so there is nothing here to read
and nothing to fix. `provided_link_count` (sent with the list) says how
many exist — they are managed in the console, not through these tools.
Passing one of their ids to a remote tool is refused with
`principal_not_active`. An empty list is an honest empty, not an error.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/openWorldHint annotations, it discloses the key operational trait that this call is local and keeps answering while the partner org is down, explains that an empty list is a valid result, and enumerates blocked_reason values with their remediation meaning. This is real behavioral context the annotations do not carry.
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?
Front-loaded with purpose, then usage/exclusions, then behavioral note, then returns — a logical progression. Despite its length, every section carries distinct information (routing, resilience, blocked_reason decoding, one-way link semantics) with no filler.
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?
Even though an output schema exists, the description supplies the semantic layer it lacks: what each status value means, that provided links are deliberately excluded and managed in the console, and that passing a provided id to a remote tool yields principal_not_active. Nothing an agent needs to interpret or act on the result is missing.
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?
The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate; the description instead invests in return-field semantics (link_id, usable, provided_link_count). That is a 4 baseline rather than a 5 because no parameter-level meaning exists to add.
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 specific verb+resource ('List the org links the caller can read through') plus the added scope of whether each is currently usable. It cleanly distinguishes itself from the four named partner-content siblings, so an agent can route 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit positive triggers ('when the user asks which partner teams they can read, or when a link tool returned an error and the reason needs checking') and an explicit exclusion naming the alternative tools that should be used to read partner content instead. Both when-to-use and when-not-to-use are present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a read-only SQL query against the memory database.
Use this when the user wants exact counts, aggregates, or table-level facts
that a semantic search cannot give. Do not use it to change data: SELECT and
WITH statements only.
Read-only. Access control is applied by the server, so rows outside the
caller's permissions never appear. A LIMIT and a statement timeout are
applied automatically.
Args:
sql: A SELECT or WITH statement. `describe_memory_schema` returns the
table and column names to write it against.
max_rows: Automatic LIMIT cap, preserved when the query already sets
one. Default 10000.
timeout_ms: Postgres statement timeout in milliseconds. Default 5000.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | A SELECT or WITH statement. `describe_memory_schema` returns the table and column names to write it against. | |
| max_rows | No | Automatic LIMIT cap, preserved when the query already sets one. Default 10000. | |
| timeout_ms | No | Postgres statement timeout in milliseconds. Default 5000. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: access control is applied server-side so restricted rows never appear, and a LIMIT plus statement timeout are automatically applied. This gives the agent important expectations about execution behavior.
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?
The description is well-structured and front-loaded: the core purpose is in the first sentence, usage guidance follows, and parameter details are cleanly listed. Every sentence earns its place, and the format is scannable for an agent.
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?
The description is complete for a read-only query tool. It covers when to use it, what it cannot do, safety behavior, access control, automatic limits, and how to discover the schema. The output schema exists, so return values need no explanation. Nothing an agent needs to call it correctly is missing.
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 100%, so the schema already documents all three parameters. The description repeats the parameter details but adds the context that describe_memory_schema provides the table/column names to write the query against. This is useful but not a major addition beyond the schema, so baseline 3 is appropriate.
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?
The description states a specific verb ('Run a read-only SQL query') and resource ('the memory database'), and explicitly distinguishes itself from semantic search by noting it is for exact counts, aggregates, or table-level facts. This clearly differentiates it from siblings like search_memory and find_memories_by_entity.
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?
The description explicitly says when to use it ('when the user wants exact counts, aggregates, or table-level facts that a semantic search cannot give') and when not to use it ('Do not use it to change data'). It also references describe_memory_schema as the way to get table/column names, providing clear guidance for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a graph query, in a Cypher subset, over the caller's own memory graph.
Use this when the user wants a structured traversal — shared-entity counts,
paths between events, tag membership — that a text query cannot express. Do
not use it for relational table facts; use `query_memories_with_sql` for that.
Do not use it when the starting point is a sentence and no pattern is stated;
use `find_memory_connections` for that.
Read-only.
The subset: a query opens with `START a = events(text: "..." | entity: "name
or id" | ids: [...], k: n)`, so the anchor set is always events. `k` defaults
to 5 and by default goes up to 20, or 200 with `entity:` alone. Events reach
events through `SHARES` (shared entities), `SIMILAR` and `FAR` (vector),
`NEXT`, and `RESOLVED_BY`, which runs `(plan)-[:RESOLVED_BY]->(evidence)`
from a plan or expectation to the memory that realized it and carries
`r.relation` and `r.asserted_at`; revoked links never appear. Events reach
entities through `PARTICIPATED_IN` and tags through `MEMBER_OF`; entities
reach entities through `CONNECTED` (stored co-occurrence) and `SAME_AS`
(stored alias). There is no `WITH` — conditions go in relation parameters
such as `{min: 3}`. The rest is ordinary Cypher: `MATCH`, `WHERE`,
`RETURN [DISTINCT]`, `ORDER BY`, `LIMIT`, aggregates in `RETURN`, `$name`
parameters, and `cos(a, b)`. Without `LIMIT`, rows stop at 20; `LIMIT` goes
up to 200.
Name match: `WHERE e.name CONTAINS $part` keeps the rows whose `Entity.name`
or `Tag.name` holds that piece, ignoring letter case and full-width forms. A
piece that is all ASCII needs two characters; one Hangul or Han character is
enough. It runs on the rows the walk already returned, so when
`truncated` is non-empty an empty result means the piece was not seen in what
was reached, not that no such name exists.
Scoped start: `events(entity: $name, text: $q, k: n)` ranks, by closeness to
`$q`, just the events that entity takes part in; `tag: $t, text: $q` does the
same inside a tag, and `tag:` alone gives its newest events. A list,
`entity: ["A", "B"]`, keeps events with any of the names; `entity_all:` or
`tag_all:` keeps events with all of them; `entity:` with `tag:` keeps events
matching both. Every part must hold and any name holds a part; there are no
brackets, no negation and no entity-or-tag choice. Up to 10 names in all;
`start.unresolved` lists the `{kind, name}` not found, and a part with no
name found gives no rows. The combined starts take `k` up to 20 and `tag:`
alone up to 200 by default; a server can set other caps, and `budget.caps`
in the response shows the ones in force. Names match exactly, up to 20
entities or tags; `start.entities_truncated` or `tags_truncated` says more
matched. `a.score` is the start event's cosine to
the start text, null when there is no text and on events reached by a hop;
nulls sort last, so use `ORDER BY a.score DESC, a.id` for a stable order.
`start.scoped_mode` is `exact` or `filtered_ann` (a large scope searched
through the vector index). `exact` measures every candidate's distance but
returns only the top `k`; `start.has_more: true` says the scope holds more
candidates than came back. A scope not fully covered (`filled: false` or a
names cap) adds a `stage: start` entry to `truncated` and sets `partial`
whatever the row count; 0 rows then means not confirmed, not absent.
`MATCH` can be left out when the start itself is the answer: `START a =
events(entity: $name, text: $q, k: 20) RETURN a, a.score ORDER BY a.score
DESC, a.id`. An arrow left off a directed relation is filled in, with a
line in `notes`, when the end labels allow one way only, as
`(a)-[:MEMBER_OF]-(t)` from an event reads `->`; `NEXT` and `RESOLVED_BY`
join two events and still need their arrow.
Example: `START a = events(text: $q, k: 3) MATCH (a)-[:PARTICIPATED_IN]-(e)
-[:PARTICIPATED_IN]-(b) RETURN b, count(DISTINCT e) AS shared ORDER BY shared
DESC LIMIT 20`
Args:
query: The graph query text.
params: Values for `$name` references (strings, numbers, lists).
Returns:
`{columns, rows, row_count, start, partial, truncated, plan, budget,
notes}`. Rows are projected: an Event to `{id, summary, timestamp,
order_index}`, an Entity to `{id, name, type}`, a Tag to `{id, name}`.
Budget caps, including a START cut short (`stage: start`), are
reported in `truncated`, never applied silently.
Rejections come back as `{error, blocked_by: syntax|grammar|params,
hint?, allowed_*}`.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The graph query text. | |
| params | No | Values for `$name` references (strings, numbers, lists). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description's 'Read-only.' merely restates that. It does add real behavioral context elsewhere — budget caps surfaced in `truncated` and never applied silently, revoked RESOLVED_BY links never appearing, arrow inference logged in `notes`, null-sorting order, and the `{error, blocked_by, hint?, allowed_*}` rejection shape. That is meaningful, but it is largely specification of the query language rather than disclosure of operational traits (auth, latency, side effects), so a 3 is the honest ceiling against rich annotations.
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?
Purpose, exclusions, and example are front-loaded, and there is light sectioning ('The subset:', 'Name match:', 'Scoped start:', 'Returns:'). But the body is a dense multi-paragraph reference manual covering edge cases (full-width matching, Hangul/Han thresholds, arrow inference) that would be better placed in external docs, and it runs well past what a selection-time description needs.
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 high-complexity query tool the description is complete: it documents the grammar subset, defaults and caps, partial-result semantics (`partial`, `truncated`, `stage: start`), scoping modes, an inline example, and the error envelope. An output schema exists, so return values need not be re-explained, and it still summarizes row projection and budget reporting adequately.
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 coverage is 100%, but the schema only says 'The graph query text.' and 'Values for `$name` references.' The description supplies the entire semantics of `query` — the START grammar, relation set, defaults for `k`, limits, scoping modes — and clarifies `params` as `$name` bindings accepting strings, numbers, and lists. It adds far more meaning than the structured fields carry.
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?
The opening sentence gives a precise verb, resource, and scope: 'Run a graph query, in a Cypher subset, over the caller's own memory graph.' It immediately distinguishes itself from siblings by naming query_memories_with_sql and find_memory_connections and stating the conditions that route to each.
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?
Explicit when-to-use ('structured traversal — shared-entity counts, paths between events, tag membership — that a text query cannot express') plus two explicit when-not-to-use clauses naming the correct alternative tools. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the same graph query language across the caller's org and a partner org.
Use this when the user asks how their own memory relates to a linked partner
team's. Do not use it to read the partner alone; use `search_partner_memory` for
that. Do not use it when the starting point is a sentence and no pattern is
stated; use `find_partner_memory_connections` for that.
Reads the partner org and writes nothing to either side. Calls are handled
one at a time per org: a second link call issued while one is in flight comes
back with `reason: busy` without running.
Name match: `WHERE e.name CONTAINS $part` works here too, on `Entity.name`
and `Tag.name`, ignoring letter case and full-width forms, two characters for
a piece that is all ASCII and one for Hangul or Han. It runs on the rows the
walk already returned, so an empty result over a `truncated` walk means the
piece was not seen, not that it is absent. Entities the link has aliased fold
into one node under the home spelling, so the partner's own spelling of a
name is not what this compares against.
Scoped start: `entity:` or `tag:` together with `text:`, and `tag:` alone,
work here too and resolve in the caller's org only, as do name lists (any),
`entity_all:` or `tag_all:` (all) and `entity:` with `tag:` (both), with
nothing beyond that shape. `a.score`, `scoped_mode`, `filled`, `has_more`,
`unresolved`, `entities_truncated` and `budget.caps` mean what they mean on
`query_memory_graph`. `exact` measures every candidate but returns
only the top `k`, and `has_more: true` says more candidates remain in
scope. An uncovered scope adds `stage: start` to `truncated`,
and `a.score` is null on hop-reached events and sorts last, so use
`ORDER BY a.score DESC, a.id` for a stable order. 0 rows with
`filled: false` means not confirmed, not absent. `MATCH` can be left out
when the start itself is the answer, as in `START a = events(entity: $name,
text: $q, k: 20) RETURN a, a.score ORDER BY a.score DESC, a.id`; with no
walk it returns only the caller's own events. A missing arrow on a
directed relation is filled in as on `query_memory_graph`, with a line in
`notes`.
Args:
link_id: Which link to read through, from `list_partner_links`.
query: The graph query text, same grammar and vocabulary as
`query_memory_graph`. `START` resolves in the caller's org only; the
walk crosses into the partner's events through entities the link has
aliased, which count as one entity for `PARTICIPATED_IN` and
`SHARES`. `NEXT`, `MEMBER_OF`, `CONNECTED`, and `RESOLVED_BY` stay
within a side.
params: Values for `$name` references.
Returns:
`{status, link_id, remote_org, columns, rows, row_count, start, partial,
truncated, plan, budget, notes}`, or `{status: error, error, reason,
detail}` where `error` repeats the reason code. A query the grammar
rejects also carries `{blocked_by: syntax|grammar|params, hint?,
allowed_*}`, as on the home path. Returned events carry `side`
(`remote` = partner), and partner content opens with
`get_partner_memory_content`. A `reason` names
the state of the link, not a failure of the caller's own memory.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The graph query text, same grammar and vocabulary as `query_memory_graph`. `START` resolves in the caller's org only; the walk crosses into the partner's events through entities the link has aliased, which count as one entity for `PARTICIPATED_IN` and `SHARES`. `NEXT`, `MEMBER_OF`, `CONNECTED`, and `RESOLVED_BY` stay within a side. | |
| params | No | Values for `$name` references. | |
| link_id | Yes | Which link to read through, from `list_partner_links`. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly/idempotent/non-destructive), and the description goes well beyond them: it discloses that reads touch the partner org and write nothing, that concurrent link calls return `reason: busy` without executing, and that name matching is case- and full-width-insensitive with an empty result over a `truncated` walk meaning 'not seen' rather than 'absent'. That is substantive behavioral context an agent cannot get from the annotations.
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?
It is front-loaded with purpose and usage, and the behavior/Args/Returns structure is disciplined, but the body is very long and includes material that duplicates the input schema's parameter descriptions and the existing output schema's field list (the whole Returns block). Several edge cases (Hangul/Han character counting, full-width forms) are dense without clear payoff for tool selection.
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 high-complexity multi-org graph query tool, the description covers scoping rules, cross-org entity aliasing, truncation semantics, ordering guidance, and error shapes (`blocked_by`, `reason`). Combined with a 100% schema and a present output schema, an agent has everything needed to invoke it correctly.
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 100%, so the baseline is 3. The Args block for `link_id`, `query`, and `params` largely restates the schema text verbatim ('from `list_partner_links`', 'Values for `$name` references'), so it adds little beyond what the structured fields already provide.
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?
The opening sentence states a specific verb and resource with scope: 'Run the same graph query language across the caller's org and a partner org.' It immediately distinguishes itself from `search_partner_memory` (partner-only) and `find_partner_memory_connections` (sentence/starts), so an agent can route correctly without opening the schema.
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?
Explicit when-to-use ('when the user asks how their own memory relates to a linked partner team's') plus two explicit when-not-to-use clauses that name the correct alternative for each case. Nothing about selection is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or query data in an AiAkiv app.
Use this when the user asks to make or look up something in an AiAkiv app,
or to manage their AiAkiv account through the `console` app: teams and
invitations, org links, audit logs, save-target history, switching Main or
turning it off and on, project presets, and the cards they created. Do not
use it to save a memory; use `save_memory` for that. Cards are made with
`create_aiakiv_card`.
Writes when `action="create"`. Some apps publish the result to the open web:
the returned link is live the moment it comes back — unlisted, but reachable
by anyone holding the address — and that publication cannot be undone from
here. The content is written by the caller from memory the user can already
read; the server never calls a model.
Args:
app: The app name. An unknown one returns `available_apps`.
action: `"describe"` returns the app's field list and limits, which is
how the exact input shape for an app is established; `"create"`
writes. Apps may define further read actions, which `describe`
lists.
data: The app's payload — a JSON object, or a JSON string holding one.
The string form survives transports that mangle long multi-line
fields.
Returns:
`{ok, app, key, url, notice?}` on create, or `{error, hint}`. The returned
`url` is the link to the created item. A `notice` is the app stating what just
became public and how to undo it, which is information the user needs to
see rather than a detail to compress away. On a shape error the app names
the offending field.
| Name | Required | Description | Default |
|---|---|---|---|
| app | Yes | The app name. An unknown one returns `available_apps`. | |
| data | No | The app's payload — a JSON object, or a JSON string holding one. The string form survives transports that mangle long multi-line fields. | |
| action | No | `"describe"` returns the app's field list and limits, which is how the exact input shape for an app is established; `"create"` writes. Apps may define further read actions, which `describe` lists. | create |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Save a piece of conversation content to memory.
Use this when the user explicitly asks to save or record something. Do not
use it on a bare "remember this" or a request to summarize; those are not
save requests.
Writes a new record. The destination project and folder come from the active
target and cannot be set from here.
Args:
payload: Alternative call form bundling {summary, entities, content,
tags} into this one argument, as a JSON object or a JSON string.
The other arguments are ignored when it is given.
summary: The retrieval surface, required unless `payload`, up to 500
characters. Searches rank against this rather than the content, so
exact identifiers kept verbatim and the acting party named in the
first sentence are what make the record findable later.
entities: NER results [{name, type}, ...], required unless `payload`.
One canonical spelling per entity; records connect on shared names.
tags: List of short slash-paths. Reusing the closest paths from a prior
response's `suggested_tags` or `tag_tree` keeps them consistent.
Ids, hashes, and dates are soft-rejected.
content: The original text, required unless `payload`, up to 50000
characters. Longer text is split across calls, each passing the
previous `event_id` as `prev_event_id`, with its own summary.
prev_event_id: The prior call's `event_id` when this save continues it.
allow_truncation_marker: Content carrying a truncation marker left by
upstream tooling is refused with `truncation_marker_detected`, since
nothing downstream can distinguish a cut body from a whole one. Set
it True when the marker is part of what is being recorded.
assert_project: The server refuses the save if the resolved target
differs from this project name. It blocks, never redirects.
timestamp: ISO 8601; defaults to the current time.
source: Upstream origin `{provider, address, version?}` when the content
came from outside this conversation.
Returns:
`{event_id, tags, tag_tree, suggested_tags?, saved_entities,
rejected_tags?, continuation_hint, edit_command, active_target}`.
`saved_entities` and `rejected_tags` let the user correct a wrong entity
or a dropped tag through `update_memory`. `suggested_entities` is
advisory — a literal name match does not establish that it denotes the
same thing here.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | List of short slash-paths. Reusing the closest paths from a prior response's `suggested_tags` or `tag_tree` keeps them consistent. Ids, hashes, and dates are soft-rejected. | |
| source | No | Upstream origin `{provider, address, version?}` when the content came from outside this conversation. | |
| content | No | The original text, required unless `payload`, up to 50000 characters. Longer text is split across calls, each passing the previous `event_id` as `prev_event_id`, with its own summary. | |
| payload | No | Alternative call form bundling {summary, entities, content, tags} into this one argument, as a JSON object or a JSON string. The other arguments are ignored when it is given. | |
| summary | No | The retrieval surface, required unless `payload`, up to 500 characters. Searches rank against this rather than the content, so exact identifiers kept verbatim and the acting party named in the first sentence are what make the record findable later. | |
| entities | No | NER results [{name, type}, ...], required unless `payload`. One canonical spelling per entity; records connect on shared names. | |
| timestamp | No | ISO 8601; defaults to the current time. | |
| prev_event_id | No | The prior call's `event_id` when this save continues it. | |
| assert_project | No | The server refuses the save if the resolved target differs from this project name. It blocks, never redirects. | |
| allow_truncation_marker | No | Content carrying a truncation marker left by upstream tooling is refused with `truncation_marker_detected`, since nothing downstream can distinguish a cut body from a whole one. Set it True when the marker is part of what is being recorded. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses key write behavior: it creates a new record, the target project/folder is fixed by the active target, truncated content is refused unless explicitly allowed, and long content must be split with prev_event_id. It also clarifies that assert_project blocks rather than redirects. This gives the agent strong behavioral expectations.
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?
The description is long but every section earns its place: purpose, usage boundary, parameter semantics, and return-value interpretation. It is logically ordered and front-loaded with the core use case. The length is justified by 10 parameters and nuanced policies.
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 complex 10-parameter write tool with an output schema, the description is essentially complete: required-alternation rules, error/refusal cases, destination control, continuation handling, and return interpretation via update_memory are all covered. There is a minor naming inconsistency between suggested_tags and suggested_entities, but it does not leave a material gap for invoking the tool correctly.
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?
Though schema coverage is 100%, the description adds substantial semantic value: summary is the retrieval surface with ranking implications, entities require one canonical spelling, tags soft-reject ids/hashes/dates, payload overrides other arguments, and continuation semantics are explained. This exceeds the baseline for already-covered schemas.
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?
The description clearly states the verb ('save') and resource ('conversation content to memory'), and explicitly contrasts with excluded cases like a bare 'remember this' or a summarization request. This distinguishes it well from sibling tools such as update_memory, search_memory, and describe_memory_schema.
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?
It explicitly specifies when to use the tool ('when the user explicitly asks to save or record something') and when not to ('bare remember this' or 'request to summarize'). It does not name alternative sibling tools for those exclusions, but the guidance is unambiguous and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find stored memories that answer a question.
Use this when the user asks about something that may already be recorded, or
refers back to an earlier conversation, decision, or document. Do not use it
to follow connections out from the memories it returns; use
`query_memory_graph` for that.
Read-only. Scope is decided by the server from the signed-in account and
reported in `searched_scope`.
Args:
query: One self-contained sentence. Resolving referents from the
conversation and keeping exact identifiers intact both help it rank.
top_k: Max hits (1-50, clamped).
mode: `"hybrid"` (default) or `"events"` — both return event hits.
`"entities"` is no longer supported and returns an error; to look
an entity up by name call `find_memories_by_entity`.
principal: Restrict to content attributed to one user or team — a handle
(email or team name) or a principal id, not a name to match. More
than one match returns `principal_candidates` to re-call with.
offset: How many top-ranked results to skip, for reading further down
the same ranking. Defaults to 0, and is clamped to 200. A response
that has more behind it names the continuing offset in
`continuation`.
Returns:
`{query, mode, hits, total, hint, searched_scope}`. `hint` is a
connection map over all results (threads, entities, categories,
clusters, available_channels). Event hits may carry
`connections.sequential {prev, next}`.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | `"hybrid"` (default) or `"events"` — both return event hits. `"entities"` is no longer supported and returns an error; to look an entity up by name call `find_memories_by_entity`. | hybrid |
| query | Yes | One self-contained sentence. Resolving referents from the conversation and keeping exact identifiers intact both help it rank. | |
| top_k | No | Max hits (1-50, clamped). | |
| offset | No | How many top-ranked results to skip, for reading further down the same ranking. Defaults to 0, and is clamped to 200. A response that has more behind it names the continuing offset in `continuation`. | |
| principal | No | Restrict to content attributed to one user or team — a handle (email or team name) or a principal id, not a name to match. More than one match returns `principal_candidates` to re-call with. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Search a linked partner org's memory.
Use this when the user asks what a partner team has recorded about something.
Do not use it to search the caller's own memory; use `search_memory` for that.
Reads the partner org and writes nothing; a link is a read capability both
orgs agreed to rather than a project to switch into, so the caller's own scope
is untouched and `link_id` is passed per call. Results are the partner's
events and stay theirs. Calls are handled one at a time per org: a second link
call issued while one is in flight comes back with `reason: busy` without
running.
Args:
sentence: One complete sentence, not keywords.
link_id: Which link to read through, from `list_partner_links`.
top_n: Max hits (server-capped at 50).
domain: An optional single remote domain to narrow to.
Returns:
`{status, link_id, remote_org, hits: [{event_id, domain, summary,
timestamp, distance, link_id}], count}`. With `status="error"` the
`reason` (`no_links`, `contract_version_too_old`, `busy`, ...) describes
the state of the link, not a failure of the caller's own memory.
`event_id` feeds `get_partner_memory_content`.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | Max hits (server-capped at 50). | |
| domain | No | An optional single remote domain to narrow to. | |
| link_id | Yes | Which link to read through, from `list_partner_links`. | |
| sentence | Yes | One complete sentence, not keywords. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context: the caller's scope is untouched, results remain the partner's, call concurrency is limited per org with a 'busy' reason, and error reasons describe link state rather than caller memory failures. This goes well beyond what the annotations alone convey.
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?
The description is dense and front-loaded with the core purpose and usage guidance, followed by important behavioral details. The Args and Returns sections partially duplicate the input and output schemas, which costs a little efficiency, but the extra behavioral prose justifies the length overall.
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 partner-memory search tool with concurrency constraints, error semantics, and ownership nuances, the description is remarkably complete. It covers when to use it, how it differs from the local-memory tool, what link_id means, how results are shaped, and how errors are interpreted. No critical operational detail is missing.
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 coverage is 100%, so the baseline is 3. The description's Args section largely restates the schema descriptions rather than adding new meaning. It does reinforce that sentence must be one complete sentence and that link_id is obtained from list_partner_links, but these appear in the schema as well, so no significant extra semantics are added.
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?
The description opens with a specific verb and resource: 'Search a linked partner org's memory.' It distinguishes itself from search_memory by explicitly stating that search_memory is for the caller's own memory, making its scope unambiguous.
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?
It states exactly when to use the tool ('when the user asks what a partner team has recorded'), and explicitly says not to use it for the caller's own memory, pointing to search_memory as the alternative. It also mentions that link_id comes from list_partner_links, giving clear invocation context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Correct the entities, tags, and order links on a saved event.
Use this when the user says a saved memory has a wrong or missing entity or
tag, or that two saves belong in sequence. Do not use it to change the saved
text; the stored content is never modified.
Writes to an existing record.
Args:
event_id: The event to correct.
remove_entities: Entity names or ids to unlink; orphans are deprecated.
add_entities: New entities [{name, type}, ...]; creates one when the
exact spelling does not exist.
add_entity_ids: Existing entity ids to link, never creating. Each is
re-validated; failures come back in `rejected_entity_ids`.
Idempotent.
add_tags: Tag paths to attach (same rules as `save_memory`).
remove_tags: Tag leaf names or group ids to detach.
add_prev_events: Event ids that come before this one, linking
`other -> event_id`, for saves that belong together but were not
chained at save time.
remove_prev_events: Event ids to unlink from the front of this event.
Links carrying document structure from ingestion are refused as
`protected_source` and cannot be rebuilt. The direction is always
"prev", so cutting a link on the other side means running this on
the later event. An id in both lists is refused as
`conflicting_request` and neither operation runs.
add_resolved_by: Evidence events that resolved this one — items are
`{"event_id": "...", "relation": "realization"}`, where `relation`
defaults to `realization`. The direction is the opposite of
`add_prev_events`: this event is the plan or intent, and each
listed event is the evidence. Write access is needed on this event
and read access on the peer. For `realization` this event must come from a
registered app (`#plan`, `#novel`, ...) and both ends must sit in
the same team part.
revoke_resolved_by: Same item shape, taking the edge down. The revoke is
soft: the assertion is preserved, and re-adding the same pair later
revives it rather than creating a second edge. The same pair in
both lists is refused as `conflicting_request`.
Returns:
`{event_id, removed_count, added_count, now_linked_entities,
orphaned_entities, added_tags?, removed_tags?, rejected_tags?,
rejected_entity_ids?, added_prev_events?, removed_prev_events?,
rejected_prev_events?, added_resolved_by?, already_linked_resolved_by?,
revoked_resolved_by?, rejected_resolved_by?, graph_delta?}`.
`graph_delta` reports the derived-layer re-sync when participation or
tags actually changed; a link-only edit feeds no derived layer and
carries none.
| Name | Required | Description | Default |
|---|---|---|---|
| add_tags | No | Tag paths to attach (same rules as `save_memory`). | |
| event_id | Yes | The event to correct. | |
| remove_tags | No | Tag leaf names or group ids to detach. | |
| add_entities | No | New entities [{name, type}, ...]; creates one when the exact spelling does not exist. | |
| add_entity_ids | No | Existing entity ids to link, never creating. Each is re-validated; failures come back in `rejected_entity_ids`. Idempotent. | |
| add_prev_events | No | Event ids that come before this one, linking `other -> event_id`, for saves that belong together but were not chained at save time. | |
| add_resolved_by | No | Evidence events that resolved this one — items are `{"event_id": "...", "relation": "realization"}`, where `relation` defaults to `realization`. The direction is the opposite of `add_prev_events`: this event is the plan or intent, and each listed event is the evidence. Write access is needed on this event and read access on the peer. For `realization` this event must come from a registered app (`#plan`, `#novel`, ...) and both ends must sit in the same team part. | |
| remove_entities | No | Entity names or ids to unlink; orphans are deprecated. | |
| remove_prev_events | No | Event ids to unlink from the front of this event. Links carrying document structure from ingestion are refused as `protected_source` and cannot be rebuilt. The direction is always "prev", so cutting a link on the other side means running this on the later event. An id in both lists is refused as `conflicting_request` and neither operation runs. | |
| revoke_resolved_by | No | Same item shape, taking the edge down. The revoke is soft: the assertion is preserved, and re-adding the same pair later revives it rather than creating a second edge. The same pair in both lists is refused as `conflicting_request`. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_aiakiv_memory_guide1 field changedInput schema / properties / topic / descriptionPrevious value: -"One of `\"tour\"` (first-run tutorial, llms-tour.txt), `\"playbook\"` (projects and personas, llms-playbook.txt), `\"setup\"` (install and connect, llms.txt), or `\"demo\"` (public demo-memory walkthrough, llms-tour-demo.txt). It defaults to `\"tour\"`, so a request for one of the other three carries the topic. Any other value returns an error listing these four."New value: +"One of `\"tour\"` (first-run tutorial, llms-tour.txt), `\"playbook\"` (projects and personas, llms-playbook.txt), `\"setup\"` (install and connect, llms.txt), `\"demo\"` (public demo-memory walkthrough, llms-tour-demo.txt), or `\"console\"` (the console app actions for teams, links, audit and cards, llms-console.txt). It defaults to `\"tour\"`, so a request for one of the other four carries the topic. Any other value returns an error listing these five."run_aiakiv_app_actionget_aiakiv_memory_guide1 field changedInput schema / properties / topic / descriptionPrevious value: -"One of `\"tour\"` (first-run tutorial, llms-tour.txt), `\"playbook\"` (projects and personas, llms-playbook.txt), `\"setup\"` (install and connect, llms.txt), `\"demo\"` (public demo-memory walkthrough, llms-tour-demo.txt), or `\"console\"` (the console app actions for teams, links, audit and cards, llms-console.txt). It defaults to `\"tour\"`, so a request for one of the other four carries the topic. Any other value returns an error listing these five."New value: +"One of `\"tour\"` (first-run tutorial, llms-tour.txt), `\"playbook\"` (projects and personas, llms-playbook.txt), `\"setup\"` (install and connect, llms.txt), or `\"demo\"` (public demo-memory walkthrough, llms-tour-demo.txt). It defaults to `\"tour\"`, so a request for one of the other three carries the topic. Any other value returns an error listing these four."run_aiakiv_app_actioncreate_aiakiv_cardfind_related_memoriesfind_related_memories4 fields changedInput schema / properties / candidate_ids / descriptionPrevious value: -"Candidate ids a preceding search response announced. Unannounced ids are treated as plain seeds."New value: +"Ignored."Input schema / properties / count / descriptionPrevious value: -"Max leads (1-5)."New value: +"Ignored."Input schema / properties / query / descriptionPrevious value: -"One self-contained sentence."New value: +"Ignored."Input schema / properties / seed_ids / descriptionPrevious value: -"Events to expand from, normally the top search hits. Omitted, it seeds itself and works standalone. Specific seeds give specific leads, while a seed hanging off an entity that appears everywhere buries its neighbours in noise."New value: +"Ignored."describe_memory_schemafind_memories_by_entityfind_memory_connectionsfind_partner_memory_connectionsfind_related_memoriesget_aiakiv_memory_guideget_memory_contentget_partner_memory_contentget_save_targethide_memorylist_memory_projectslist_memory_timelinelist_partner_linksquery_memories_with_sqlquery_memory_graphquery_partner_memory_graphrun_aiakiv_app_actionsave_memorysearch_memorysearch_partner_memoryupdate_memoryLong-term memory and a knowledge graph for AI agents: recall, notes, secrets and data sources.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Persistent long-term memory for AI agents: semantic search, knowledge graph, and task canvas.
Graph memory for AI agents: entities, cause-effect links, cross-session recall, time travel.
Add one secure layer between your agents and this server.
