Shared long-term memory for AI agents: save and recall context as a searchable knowledge graph.
Scored across 21 tools
The set has five overlapping retrieval paths (search_memory, find_memories_by_entity, find_memory_connections, query_memory_graph, list_memory_timeline) plus a mirrored partner family, which is genuinely dense. Descriptions mitigate this well by explicitly naming the sibling to use instead ("Do not use it for X; use Y"), so an agent can route reliably, but boundaries still require careful reading rather than being self-evident from names alone.
Every tool is verb-first snake_case with a predictable verb vocabulary (create_, get_, list_, find_, search_, query_, update_, save_, hide_, describe_, run_). The home/partner pairing is systematic (search_memory/search_partner_memory, query_memory_graph/query_partner_memory_graph), which makes the mirrored surface easy to predict.
At 21 tools the surface is heavy, and roughly a third of it is a deliberate duplication of home tools for the partner-org path (search, connections, graph, content). Each tool is defensible in the domain, but the volume means agents must triage a large set to answer simple questions.
Coverage is broad: write (save_memory), correct (update_memory), reversible suppression (hide_memory), multiple read paths, schema/SQL introspection, projects/target, partner reads, cards, app actions, and docs. The gaps (no un-hide, no permanent delete, no card listing/removal) are explicitly delegated to the web console or an operator, so they are documented rather than dead ends.
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 | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare openWorldHint=true and idempotentHint=false, but the description goes well past them: it states the page and two images are public on return, that it is unlisted but unauthenticated-readable, that it cannot be edited or taken down from here, that the server never calls a model, and that retrying publishes a second card. The failure modes (`invalid_card`, `quota_exceeded`) are also disclosed, which annotations cannot 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?
It is well front-loaded—purpose, then when-to-use, then consequences, then limits—but the 'Limits' paragraph and the 'Args' section repeat the same six constraints almost verbatim, and the Args text is pure duplication given 100% schema coverage. That is a meaningful amount of non-earning text in an otherwise disciplined description.
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 publish-to-open-web mutation with six parameters, the description covers the durability of the side effect, image-fitting guidance that no schema field can express, markdown restrictions on `body`, and the error shapes. Even though an output schema exists, the return-value explanation adds the sequencing detail that `notice` must be surfaced to the user.
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 per-parameter constraints are already documented; the description's Args section largely restates them. What it genuinely adds is cross-parameter behavior: tags are baked into the images and immutable, bullets share one fixed vertical block so count and length trade off, and content is trimmed of whitespace and empty items before validation.
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 first sentence names a specific verb and artifact ('Publish a one-page AiAkiv card that summarizes memory the user already has') and the second narrows scope further. It explicitly distinguishes itself from `save_memory`, so an agent can route correctly without opening either 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 gives an explicit positive trigger ('when the user asks to turn something from their memory into a card, a shareable summary page, or a link') and an explicit exclusion plus the alternative ('Do not use it to save a memory; use `save_memory` for that'). 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.
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 declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context beyond that: the operation is cheap, the schema is public information, and table data remains protected by RLS.
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 short, front-loaded, and structured around purpose, usage, exclusions, safety, and return shape. The returns section is somewhat redundant because an output schema exists, but it does not bloat the definition.
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?
With an output schema present, rich annotations, and no parameters, the description supplies everything an agent needs to select and invoke the tool correctly. It covers purpose, usage, exclusions, cost, and security context.
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?
This tool has zero parameters, so the baseline is 4. There are no parameter semantics for the description to clarify.
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 and resource: it returns the memory database's tables, columns, and types. It clearly distinguishes this structural inspection tool from tools that read stored content or run SQL queries.
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 usage context: use when a SQL query needs the schema first. It also gives an exclusion: do not use it to read stored content. However, it does not explicitly name the alternative sibling tool such as query_memories_with_sql or get_memory_content.
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?
Adds genuine context beyond the annotations: scope is server-decided and surfaced in `searched_scope`, and the description clarifies query semantics such as the substring also matching tags. 'Read-only' merely restates readOnlyHint=true, which is why this is not a 5, but the scope-disclosure and tag-matching behavior are real additions.
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?
Well front-loaded: purpose and routing come first, then behavior, then args/returns. The Args section duplicates the schema nearly word-for-word, which is the one place sentences do not fully earn their space.
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 interpretive detail it cannot convey — that `top_partners` is a scope-wide co-occurrence ranking while `hint.entities[].hit_count` is sample-bound. That resolves a genuinely ambiguous choice between two similar-looking fields.
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% and the description's Args block reproduces the schema text almost verbatim, adding little beyond it. The precedence rule for `entity_id` is useful but already present in the schema, so the baseline 3 applies.
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 and resource ('look up entities by name and return the events they appear in') and explicitly contrasts itself with `search_memory`. An agent can distinguish it from siblings like `search_memory` or `find_memory_connections` without opening a 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?
Gives an explicit trigger ('when the user names a person, project, system, or term and wants what is recorded about it') plus a negative case ('Do not use it for an open question about a topic') and names the alternative tool to use instead. This is the full when/when-not/alternative pattern.
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 read-only, idempotent, non-destructive, closed-world, so safety is covered. The description adds genuinely beyond that: candidates are 'unverified pointers, not established facts', and `grounding="absent"` is an honest empty rather than a failure. That distinction (empty vs. error) is valuable behavioral context not present in 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?
Front-loaded with purpose, then routing, then behavior, then Args/Returns. Efficient for a 7-param tool, though the Args prose duplicates the schema descriptions nearly verbatim, adding some 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?
Given an output schema, annotations, and full param coverage, the description fills the remaining gaps: it explains grounding value semantics, the 2-round expansion multiplicity, and the empty-vs-failure distinction. 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 coverage is 100% and the schema descriptions are already rich, including the relation enum semantics and expansion_rounds mechanics; the description's Args section largely restates them. It adds some relational framing (no implicit 'now', contrast narrowing without judging) but the marginal value over the schema is modest, so baseline 3 fits.
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 (walk the entity-event graph outward from what a sentence finds, one or two hops) and contrasts it explicitly with the ranked-search behavior of search_memory. An agent can distinguish it from siblings 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 when-to-use ('what is linked to something a ranked search did not surface') and explicit when-not with named alternatives: search_memory for direct answers, query_memory_graph for stated patterns. This is model routing guidance with no inference left to the agent.
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?
Goes well past the readOnly/idempotent annotations: discloses that candidates are unverified pointers, that concurrency is one call per org with a `reason: busy` failure mode, that a revoke aborts mid-call, and that the partner side is only reached through bridges so `absent` is never reported. These are real operational traits an agent cannot get from annotations or schema.
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?
Routing rules are front-loaded and the description is broken into scannable blocks (usage, behavior, args, returns). It is on the long side and repeats schema parameter text in the Args block, which costs some efficiency.
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 graph-walk tool with 8 parameters, it covers the decision context, failure modes, response shape, and the key asymmetry of the search (remote side never at entry). An agent could call this correctly without reading anything else, even though an output schema is present.
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%, and much of the Args block mirrors the schema text, but the description adds cross-tool semantics the schema lacks: relation meanings are anchored to find_memory_connections, and the legacy link_id+anchor_event_id form is called out with its compat marker. Still, per-parameter detail is largely duplicated rather than newly explained.
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 and resource ('Walk the entity-event graph across the caller's org and a partner org') and immediately distinguishes itself from two named siblings. An agent can tell it apart from search_partner_memory and query_partner_memory_graph without opening either 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?
Explicitly gives the triggering case ('user asks what a linked partner team's memory connects to something of their own') plus two named exclusions with the alternative to use instead. Nothing is left to inference about routing.
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?
Annotations already cover readOnly/idempotent/non-destructive, and 'Read-only.' merely restates them. Beyond that, the description discloses server-side fetching that can fail (with a {error, hint} shape), a cached flag, and the rule that unknown topics return an error listing the five valid values — real behavioral detail not in 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?
The opening line and usage triggers are front-loaded and earn their place. Some space is wasted duplicating the schema's topic list verbatim in the Args block and restating 'Read-only.' which the annotations already assert, but overall it stays tight for a doc-fetch tool.
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?
Single optional parameter with a documented default, precise invocation triggers, failure modes, and a return shape — even though an output schema exists and technically relieves the description of that duty. An agent has everything needed to call it correctly and interpret the response.
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% and the description's topic enumeration is essentially a verbatim copy of the schema's own description, adding no new semantics. Baseline 3 applies when the schema already carries the parameter meaning in full.
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 and resource ('Return an AiAkiv guide document for a topic, as text') plus the exact domain of topics covered. This is unmistakably a documentation-fetch tool, clearly separable from the memory-query/mutation siblings whose names all reference memories, graph, or cards.
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?
Gives concrete triggers: user asks how to use AiAkiv or MWeft, wants the tutorial, or pastes an llms-*.txt link that cannot be opened here. It also frames the output as reference material 'not a set of commands.' It stops short of naming an explicit when-not or pointing at an alternative sibling, so it lands at 4 rather than 5.
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 read-only/idempotent/non-destructive, and the description still adds substantial operational detail: long bodies are paginated, a non-null `next_offset` means the body is incomplete, oversized `limit` values are clamped because the transport silently drops large responses, and `include_raw` pulls from `storage_uri`. These are non-obvious failure modes the annotations cannot 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?
Well front-loaded: purpose, then when-not, then the critical paging warning, then per-arg notes. The trailing `Returns:` field list duplicates the existing output schema and is the one block that doesn't earn 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 4-param read tool with full schema coverage, annotations, and an output schema, this covers everything an agent needs: id formats (`ev_`/`vec_`), the paging loop, the raw-vs-metadata tradeoff, and the truncation hazard. The Returns block is redundant rather than 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 earns above that by explaining the cross-parameter paging contract (feed `offset=next_offset` and concatenate until null) and the rationale for the 30000 clamp, which no single parameter description conveys on its own. The Args block largely restates schema text, which limits how much extra value it adds.
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 line names a specific verb and resource plus a tight scope: 'Fetch the stored text of one event.' The follow-up 'Do not use it to browse a topic; it takes one event id' separates it from search/browse siblings such as search_memory, so an agent can route correctly without opening a 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?
Gives a concrete trigger ('when a summary from a search or lookup result lacks the detail needed to answer') and an explicit exclusion ('Do not use it to browse a topic'). It stops short of naming the sibling to use instead (e.g. search_memory vs get_partner_memory_content), which is the only missing piece.
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 behavior, but the description adds crucial operational context: no raw storage pointer is accepted, link scope grants body access, calls are serialized per org with a busy response, and found=false is intentionally ambiguous. These are non-obvious traits an agent must know.
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 front-loaded with purpose and usage, then structured into Args and Returns sections. Every sentence contributes operational or semantic value, 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?
Despite having an output schema, the description still explains the return contract and the pagination rule (next_offset non-null means incomplete). It covers auth scope, concurrency behavior, and ambiguity of found=false, leaving no significant gap for 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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: event_id must come from search_partner_memory results, link_id is the authorization scope, and limit is server-capped. It does not repeat schema text verbatim.
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 ('Read one linked partner event's body, paged') and explicitly distinguishes the tool from its sibling get_memory_content. An agent can identify the operation and its scope without consulting 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?
It states exactly when to use it ('when a partner search result's summary lacks the detail needed') and when not to ('Do not use it for the caller's own events; use get_memory_content for that'), naming the correct alternative. This is explicit routing guidance.
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 | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the explicit 'Read-only.' sentence adds little. The real added value is the binding taxonomy (folder/api-key pinned vs main vs public-read/link-read) explaining why switch_url is null and when a target can change mid-session, which goes beyond 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?
Front-loaded with the purpose and the when-to-use block before the field glossary. It is longer than necessary in places, particularly the long enumerated return-value description that largely duplicates the existing output 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 a zero-argument read tool with a rich output schema, the description supplies the interpretive layer an agent needs: what binding values mean, when switch_url is null, when multi_connection_note appears, and what persona represents. Nothing required to 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 the baseline is 4; there is nothing for the description to disambiguate. The return-field explanation it provides is useful but belongs to output semantics, not parameter semantics.
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 and resource: reports where saves currently go and how the target is composed (account + team/domain/group). It also explicitly distinguishes itself from mutation siblings by saying 'It does not change the target', separating it from save_memory and switch actions.
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?
Names three concrete triggers (user asks where memory is saved, asks to switch project, expected memory is missing/account may have changed) and states what it does not do. It further explains the alternative paths: on Main-following connections the switch happens via switch_url, and on pinned connections the console cannot move it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Goes far beyond the annotations: declares it writes to an existing record, that cross-team events are refused, and that app-managed memory can be blocked by archived work or a disabled 'Write directly into app memory' permission that only a human can change. It also enumerates the error codes, which the annotations cannot 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?
Front-loads the what/scope, then when-to-use, then constraints — a good reading order. The 'Args' block duplicates the schema and the 'Returns' block duplicates the output schema, so those two sections are largely redundant padding.
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, everything an agent needs is present: effect scope, reversibility, permission gating, refusal conditions, and error shapes. Nothing material is left to inference.
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% and there is only one parameter, so baseline is 3; the description adds value by explaining the failure semantics of event_id (empty, not found, another org, app-managed). It does not, however, say where an event_id comes from (e.g., search_memory results), so it stops short of a 5.
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 and resource (hide a saved event) plus the exact blast radius ('from all recall — search, neighbors, and derived layers'). That scope statement distinguishes it from update_memory and the read/search siblings without needing to open 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?
Gives explicit triggers (saved by mistake, wrong project, superseded) and an explicit exclusion ('Do not use it to remove data permanently'), then explains the reversible-hide-vs-delete distinction and that un-hiding is an operator action rather than a tool. The agent knows both when to call and when to stop and ask.
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 | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so 'Read-only' earns little credit. The description earns its score by disclosing the key non-obvious behavior: the actual switch is performed by the user clicking switch_link, not by this call, plus what is_main, is_this_connection, read_only entries and main_paused mean.
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?
Well front-loaded — purpose, then when-to-use, then caveat, then returns. But the switch_link mechanic is stated twice (in the body and again in the Returns block), and the Returns section largely restates an output schema that already exists, costing efficiency.
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 zero-parameter read tool with a full output schema and complete annotations, the description covers everything an agent needs: when to call it, the fact that it does not itself switch, and how to interpret the fields that drive the user's next action.
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?
Zero parameters, so the baseline of 4 applies. The description instead uses the space to disambiguate the returned fields rather than input arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb and resource ('List the projects the signed-in account can save to or read'), which is specific and distinct from the memory-content siblings. It does not explicitly name the closest alternative (get_save_target) as the tool to use for a single current target, so sibling differentiation is only implied via the 'does not perform the switch' clause.
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?
Gives three concrete triggering user intents ('which projects they have', 'which one they are saving to', 'wants to move their saves elsewhere'), which is clear context. It also adds an exclusion clause — this tool does not perform the switch — but never names a sibling to use instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 carry readOnlyHint/idempotentHint/destructiveHint=false, so the 'Read-only' sentence is redundant, but the description adds real context beyond them: scope resolution is server-decided and surfaced as `searched_scope`, and omitting both anchors yields a full-domain flow. What's missing is behavior for large results beyond the `truncated` field mention.
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 exclusion, then behavior, then args/returns — good ordering. The Args section duplicates the schema word-for-word, which is filler an agent already has; trimming it would tighten the definition.
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?
Covers the tool's realistic complexity: 4 optional params with meaningful combinations, server-side scope selection, and a return envelope. `mode` and `anchor` in the return shape are named but not explained, a minor gap given an output schema exists and detailed return docs aren't required.
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% and the Args block is a verbatim restatement of the schema descriptions, so no new per-parameter meaning is added. The one genuine addition is the combination rule ('With neither `entity_id` nor `cg_id`, the flow covers the whole domain'), which the schema does not encode — but that alone keeps it at baseline rather than above.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb and resource ('Return events in chronological order') plus the three available scoping dimensions (entity, tag group, domain). It explicitly separates itself from `search_memory`, so an agent can choose between them without opening either 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?
Gives both the positive trigger ('how something developed over time, or what happened in a period') and the explicit exclusion plus the named alternative ('Do not use it to rank by relevance; use `search_memory`'). It also documents the no-filter default ('covers the whole domain'), which is the remaining usage ambiguity.
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?
The description adds meaningful behavior beyond the annotations: it is local and keeps answering even while the partner org is down, which is exactly when diagnosis matters. It also explains one-way link semantics, why provided links are not listed, that passing their ids is refused with principal_not_active, and that an empty list is an honest empty rather than an error.
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 front-loaded with purpose and usage, then organized into behavioral notes and Returns. It is somewhat long because it restates the return shape even though an output schema exists, but the return-field semantics and error meanings earn most of the space.
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 no-parameter diagnostic/list tool with annotations and an output schema, the description is complete. It covers when to call it, what it will not do, resilience during outages, return-field meaning, blocked_reason interpretation, one-way link behavior, and empty-list semantics.
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 input parameters, so the baseline is 4. The description does not need to explain input semantics, and it appropriately focuses on usage and return meaning instead.
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 first sentence gives a specific verb and resource: it lists the org partner links the caller can read through and whether each is currently usable. It also distinguishes this from the partner-content tools that actually read remote memory, so an agent can separate it from siblings 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?
The description states explicit when-to-use conditions: when the user asks which partner teams they can read, or when a link tool errored and the reason needs checking. It also explicitly says when not to use it and names the four partner content tools that should be used instead.
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?
The annotations already declare read-only and non-destructive behavior, but the description adds important operational context: server-side access control, automatic LIMIT application, and statement timeout behavior. These details go beyond the annotations and help the agent predict execution constraints.
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-loads the core purpose and usage constraints. The Args section duplicates the input schema descriptions, which is slightly redundant, but the overall text remains efficiently organized.
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 rich annotations, 100% schema description coverage, and an output schema, the description provides all the context an agent needs: read-only safety, access control, automatic limits, timeout behavior, and schema discovery guidance.
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%, and the description repeats the same parameter semantics found in the schema rather than adding new meaning. The SQL parameter points to `describe_memory_schema`, which is useful, but it is also already present in the schema description.
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 and resource: a read-only SQL query against the memory database. It explicitly distinguishes the tool from semantic search by naming exact counts, aggregates, and table-level facts, which helps an agent choose it correctly.
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 clear when-to-use guidance and an explicit when-not-to-use constraint: SELECT and WITH statements only, not data changes. It also points to `describe_memory_schema` for writing valid queries, covering the main prerequisite.
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 read-only, idempotent, non-destructive behavior, but the description adds substantial operational detail: the anchor must be events, default and maximum `k` values, `LIMIT` caps, truncation/partial-reporting semantics, exact vs filtered_ann scope, and error response shape. It also states that budget caps are reported in `truncated`, never applied silently.
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 long and dense, but much of the detail is justified by the complexity of the query language. Purpose and usage are front-loaded, followed by grammar and edge-case rules; some sections are very detailed but directly affect correct invocation.
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?
Complete for a complex query tool: it covers purpose, alternatives, grammar, constraints, start semantics, return structure, truncation behavior, and rejection shape, and an output schema also exists. No material invocation guidance 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%, but the description goes far beyond the schema by defining the Cypher subset grammar, `START` syntax, relation semantics, name matching rules, scoped start combinations, and allowed `params` values. This meaningfully prevents incorrect query construction.
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 ('Run a graph query') and resource ('the caller's own memory graph'), scoped to a Cypher subset. It explicitly distinguishes the tool from text queries and from relational SQL, so an agent can identify it without inspecting siblings.
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?
Gives explicit when-to-use cases (structured traversal such as shared-entity counts, paths between events, tag membership) and when-not-to-use cases with named alternatives: `query_memories_with_sql` for relational table facts and `find_memory_connections` for sentence-based starts with no stated pattern.
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?
Beyond the readOnly/idempotent annotations it discloses non-obvious behavior: per-org single-flight with a `reason: busy` short-circuit, that empty results over a `truncated` walk mean 'not seen' rather than 'absent', that aliased entities fold into the home spelling, and that `a.score` is null and sorts last on hop-reached events. These are real operational constraints an agent cannot infer from annotations or schema.
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 and usage are front-loaded correctly, but the body is a dense wall covering name-match semantics, scoped-start shapes, scoring/sorting, truncation codes, and optional MATCH — much of which duplicates the `query` schema text or belongs to the grammar reference. Structure exists (paragraph per topic) but several sentences could be trimmed.
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 tool with an output schema, annotations, and 3 params, the definition still covers the return envelope, error shape with `blocked_by` codes, the `side` field, and the `get_partner_memory_content` follow-up. Nothing an agent needs to call it correctly on the first try 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% and the `link_id`, `query`, and `params` descriptions in the schema restate the same text found here, so the description adds little parameter-level meaning beyond what is already structured. It does confirm `link_id` must come from `list_partner_links` and that `params` fills `$name`, but that is already in 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?
The opening sentence names a specific verb and resource — running the graph query language across the caller's org plus a partner org — and immediately separates it from `search_partner_memory` (partner alone) and `find_partner_memory_connections` (sentence start, no pattern). An agent can distinguish it from all three relevant siblings without opening a 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?
Explicitly states the triggering condition (how your own memory relates to a linked partner team's) and then two named exclusions with the alternative tool to use instead. This is the when/when-not/alternatives pattern at full strength.
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 | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations: it discloses that some apps publish results to the open web with a live, unlisted-but-reachable URL, that the publication cannot be undone from this tool, that content is caller-written and the server never invokes a model, and that a `notice` must be surfaced to the user. The `destructiveHint: true` and `openWorldHint: true` annotations are consistent with, and materially enriched by, these statements.
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, then warnings, then a conventional Args/Returns block — a sensible structure with no filler. It runs long and the Args section partially duplicates the schema text, costing a point, but every paragraph carries information an agent would otherwise have to guess.
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 three-parameter, open-world, destructive, non-idempotent tool this covers the failure modes that matter: unknown app names, shape errors naming the offending field, irreversible publication, and the error envelope. Even though an output schema exists, the description's return-value summary adds routing value that the schema alone would not convey.
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 baseline is 3, and the description still adds rationale beyond the schema — e.g. why the string form of `data` exists (transport mangling of long multi-line fields) and that `describe` is the canonical way to establish an app's input shape before writing. This is useful sequencing guidance rather than a restatement of field descriptions.
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 pair ('Create or query data in an AiAkiv app') and immediately scopes it against siblings by naming both the exclusion ('Do not use it to save a memory; use `save_memory`') and the adjacent card tool. An agent can route correctly 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?
Gives an explicit when-to-use clause tied to user intent ('when the user asks to make or look up something ... or to manage their AiAkiv account through the `console` app'), enumerates concrete sub-domains (teams, invitations, audit logs, save targets, project presets, cards), and states two explicit when-not cases with the correct alternative for each.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 tags. Reusing tags from a prior response's
`suggested_tags` first, then `tag_tree`, keeps them consistent. An
existing tag not shown in those lists still matches when written
by its name. 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, tags_created?, tag_tree, tag_tree_total?,
tag_tree_truncated?, suggested_tags?, saved_entities, rejected_tags?,
continuation_hint, edit_command, active_target}`.
`tag_tree` is not every tag: it holds up to a set number of existing
tags, those similar memories used first, then the most used, and
`tag_tree_total` gives how many the team has. `tags_created` names the
tags this save newly made. `saved_entities`, `tags_created` and
`rejected_tags` let the user correct a wrong entity, an unintended new
tag 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 tags. Reusing tags from a prior response's `suggested_tags` first, then `tag_tree`, keeps them consistent. An existing tag not shown in those lists still matches when written by its name. 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?
Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds genuinely non-obvious behavior: destination project/folder come from the active target and cannot be set, assert_project blocks rather than redirects, truncation-marker content is hard-refused with a named error code, and long content must be split across chained calls. It does not address what happens on a repeated identical save beyond "writes a new record", which is the main remaining gap.
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?
Well front-loaded with the usage ruling first, but the body is long and much of it duplicates schema property text and the output schema. With a structured output schema present, the multi-sentence Returns section is largely redundant and dilutes the high-value usage guidance.
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 10-parameter mutation tool with an output schema, the description covers call-form choice (payload vs discrete args), content splitting, refusal conditions, and target resolution — enough to invoke correctly. The duplication with schema/output schema is the only shortfall, not missing information.
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 carries the parameter detail. The Args block largely restates the schema property descriptions (payload/entities/tags/content wording is near-verbatim), so it adds little beyond structured data — baseline 3 applies.
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 ("Save a piece of conversation content to memory") and immediately scopes it against near-miss intents ("bare 'remember this'" and summarization requests). An agent can distinguish save_memory from update_memory and search_memory without opening either 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 explicitly asks to save or record something") and explicit when-not-to-use with the two most likely false positives named. Also implies the correction path via update_memory for wrong entities/tags, so the agent knows save is not the repair tool.
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 | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/closed-world, yet the description adds real value beyond them: scope is server-derived from the signed-in account and surfaced in `searched_scope`, `top_k` and `offset` are clamped, `mode="entities"` now errors, and multi-match principal returns `principal_candidates` for a re-call. These are behavioral facts an agent cannot infer from 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?
Front-loaded with purpose then routing then behavior, and each section is tight. The Args section duplicates schema text rather than earning its place, which is the only structural weakness; the Returns section, by contrast, adds information not visible at call time.
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?
Five parameters, one required, pagination via offset/continuation, deprecation handling, and return-shape documentation are all covered. Even though an output schema exists, the description's note about `hint` connection maps and `connections.sequential {prev, next}` is the kind of detail that materially changes how an agent consumes results.
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% and the Args block largely restates the schema field descriptions verbatim, so it adds little beyond structured data. It does add the query-authoring guidance ('self-contained sentence', resolving referents) which is genuinely useful, but that is already mirrored in the schema. 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?
Opens with a specific verb and resource ('Find stored memories that answer a question') and immediately demarcates scope from siblings by naming `query_memory_graph` and `find_memories_by_entity`. An agent can distinguish it from the 19 sibling tools without opening a 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 ('user asks about something that may already be recorded, or refers back to an earlier conversation, decision, or document') plus explicit when-not ('do not use it to follow connections... use `query_memory_graph`'). It also redirects deprecated mode usage to `find_memories_by_entity`, giving a second routing rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Goes well beyond the readOnly/idempotent annotations: it explains that a link is an agreed read capability rather than a scope switch, so the caller's own context is untouched and link_id is per-call. It also discloses the per-org concurrency limit and that a colliding call returns reason: busy without running — behavior no annotation conveys — plus the semantics of error reasons (link state vs. caller failure).
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 the sibling exclusion before any mechanics, and the returns block is scoped to what matters (error reasons, event_id handoff). The middle paragraph on link semantics is slightly long but each clause carries real behavioral information.
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?
Covers trigger, exclusion, prerequisites (link_id source), concurrency caveat, error taxonomy, and the follow-up tool for returned hits. With an output schema present it still explains the parts that matter (status/reason semantics), leaving no gap an agent would hit at call time.
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% and the description's Args section restates the schema field-for-field ('One complete sentence, not keywords', 'server-capped at 50'), adding no new meaning. The only marginal value is the pointer that link_id originates from list_partner_links, which the schema also states. Baseline 3 for full-coverage schemas is correct here.
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 and resource ('Search a linked partner org's memory') and immediately scopes it against the caller's own memory. It also names the downstream tool for the returned event_id, so an agent knows exactly where this fits relative to search_memory and get_partner_memory_content.
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?
Gives an explicit when-to-use trigger ('user asks what a partner team has recorded about something'), an explicit when-not ('Do not use it to search the caller's own memory') with the correct alternative named, and tells the agent where link_id comes from (list_partner_links). 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.
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 | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Far beyond the annotations: it discloses refusal codes (protected_source, conflicting_request), the all-or-nothing behavior on conflicting lists, the soft-revoke/revive semantics, permission requirements (write on this event, read on the peer), and the app/team constraints for realization edges. The per-parameter "Idempotent" for add_entity_ids is scoped to that field and does not contradict the tool-level idempotentHint=false.
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, then a scannable Args block; every sentence carries operational content. It is long, but the length comes from 10 interacting parameters rather than filler — only the Returns enumeration mildly overstays, since an output schema already exists.
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 destructive, non-idempotent mutation over a graph, it covers refusal modes, permissions, directionality and side effects, which is what an agent needs to avoid bad calls. The verbose Returns listing is redundant given the output schema, and the missing piece is that it never states the effects of removal on downstream/linked data beyond 'orphans are deprecated.'
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% and the Args section is verbatim duplicated in the schema property descriptions, so the description adds little that the schema does not already carry. Its only marginal gain is spelling out cross-parameter interactions (opposite directionality of add_prev_events vs add_resolved_by) in one narrative place.
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?
"Correct the entities, tags, and order links on a saved event" states a specific verb and the exact facets that can change, then explicitly contrasts with content editing ("the stored content is never modified"). An agent can separate this from save_memory and get_memory_content without reading 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?
It names the triggering user utterances (wrong/missing entity or tag, two saves belong in sequence) and an explicit exclusion ("Do not use it to change the saved text"). Alternatives are pointed at by reference, e.g. tag rules follow save_memory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
save_memory1 field changedInput schema / properties / tags / descriptionPrevious value: -"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."New value: +"List of short tags. Reusing tags from a prior response's `suggested_tags` first, then `tag_tree`, keeps them consistent. An existing tag not shown in those lists still matches when written by its name. Ids, hashes, and dates are soft-rejected."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.
Persistent working memory for AI agents: a knowledge graph with semantic search and decay.
Add one secure layer between your agents and this server.
