STEM — Persistent AI Memory

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

Adds substantial context beyond the annotations: no undo tool exists, an absent ID is a no-op so a success response does not prove prior existence, and deletion is confined to the user's STEM account (not original conversations or other users). The destructive/idempotent hints are already in annotations, so this is additive rather than restated, though it does not cover link cascade details or auth requirements.

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?

Four sentences that are front-loaded with the action and each carry distinct information (trigger, prerequisite, return semantics, scope exclusions). Slightly dense but no sentence is 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?

With a single parameter fully documented and no output schema, the description covers what the return contains ('ok and the requested numeric ID'), edge-case behavior (no-op on absent ID), and scope boundaries. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100% and the id parameter already documents that it comes from remember or recall and must not be guessed. The description reinforces the recall-before-delete workflow but adds no format or resolution detail beyond the schema, so 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 ('Delete one saved memory and its attached links') plus the scope ('from the authenticated user's STEM account'), which distinguishes it cleanly from recall, remember, and link within the sibling set.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger ('when the user requests that deletion') and a required prerequisite workflow ('identify the intended memory with recall before deleting'), effectively naming recall as the identification alternative. It also bounds scope by listing what this does not delete, so the agent knows when another tool or assistant is responsible.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real value by describing the return shape (layers, labeled nodes, typed edges, subset counts), the m-prefixed display IDs, and the synthetic core/you nodes. It stops short of pagination or size/perf behavior, but the added context is substantive.

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 core action and its bounded nature, then IDs/node conventions, then the recall handoff. Dense but nearly every clause carries information; the trailing negative list is slightly boilerplate but does bound scope.

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 no output schema, the description carries the return-value burden and does so: layers, nodes with short labels, typed edges, subset counts, and the distinction between synthetic nodes and m-prefixed memory IDs. An agent knows what it will get and what it will not (full text, account-wide totals).

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 single limit parameter is fully documented in the schema with range and default. The description adds nothing about limit (e.g., that lowering it truncates visible edges), so it does not go beyond what the schema already provides — 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 (read/inspect) and resource (bounded visualization of memories and relationships), plus scope limits (authenticated user's account, subset not totals). This clearly separates it from siblings like recall, which the description names explicitly.

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 routes the agent: 'Use recall for full saved context and numeric memory IDs,' which is the key selection decision between the two tools. It also states what the tool is not for (changing memories, enumerating assistants, web search, other users' data), covering both when-to-use and when-not.

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

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

Goes beyond the annotations by spelling out the practical consequence of non-idempotency — 'Each call creates a new link; retries can duplicate links' — which an agent cannot infer from idempotentHint=false alone. It also discloses the authenticated account scoping and the returned fields (link ID, from, to, type, weight), which matters since no output schema exists.

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 core action, then preconditions, return value, duplicate caveat and scope limits in a tight sequence with no filler. The final sentence is a slightly long exclusion list but each clause rules out a plausible agent misread.

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 four-parameter mutation tool with no output schema, the description covers what is created, required ownership, ID source, return payload, duplicate risk and out-of-scope actions. Nothing an agent needs in order to call it safely is missing.

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

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

Schema description coverage is 100%, so the direction semantics, the m12/core ID warning and the 0–1 weight convention are already documented in the schema. The description reinforces directionality ('directed relationship') and lists the allowed types, but adds no syntax or format detail beyond the schema. 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 ('Create a directed relationship between two existing memories') and enumerates the four relationship types, so the agent knows exactly what is produced. It also implicitly separates itself from read-only siblings like 'graph' and 'recall' by framing the tool as link creation.

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 clear preconditions ('Use numeric memory IDs returned by remember or recall; both memories must belong to this account') and explicit scope exclusions (no assistant accounts, no conversation import, no cross-user links). It never names a sibling tool as the alternative for viewing the graph, so it stops short of full routing guidance.

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

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

Although annotations already declare readOnly/idempotent/non-destructive, the description adds real context: connection-scoped permission, no settings change, no memory-storage consumption, no cross-user access, and fail-closed error behavior. It stops short of describing latency or what 'unavailable' concretely looks like, so it is strong but not exhaustive.

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 the empty-object requirement are front-loaded, and every clause adds a distinct constraint. It is dense with some redundancy — the 'never permit automatic saving' condition is stated twice in close succession — but nothing is 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?

With no output schema, the description carries the return contract and does so precisely (automaticSavingAllowed, mode, consentVersion) while explicitly excluding expected-but-absent data. For a pre-flight permission check, nothing an agent needs in order to call it safely 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?

A zero-parameter tool, but the description does more than restate the empty schema: it mandates sending only an empty object and explicitly forbids smuggling conversation content, user IDs or consent claims into the call — a guardrail the schema cannot express.

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 — 'Read the current automatic-memory permission for this authenticated STEM connection' — and immediately scopes the result ('not saved memories or account-wide settings'), which separates it from recall/remember siblings that touch actual 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 explicit timing ('before any automatic context save') and an explicit decision rule: only 'automaticSavingAllowed exactly true' permits a best-effort save, while false, unavailable or errors never do. It also names the boundary against alternatives — host confirmations and user no-save instructions are not overridden.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses the return shape (ranked candidates with numeric IDs, text, source, type, timestamps, relevance scores), warns that results may be weak or empty, and states retrieval is bounded. It also rules out side effects such as changing memories, searching the web, reading unsaved chat history, or accessing other users' data.

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 the core action and then layers use cases, return details, caveats, and boundaries in a tight sequence. Every sentence adds a distinct operational detail, and there is no repetition or 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?

Given that there is no output schema, the description compensates by explaining return fields, result quality, and retrieval bounds. It also covers authentication scope, data boundaries, and side-effect exclusions, leaving no major gap for an agent deciding whether and how to call the tool.

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 explains query, type, source, and limit in detail. The description mentions returned fields such as source and type but does not add meaningful guidance about how to use those fields as filters beyond what the schema provides, so the baseline of 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?

The description gives a specific verb and resource: search previously saved memories in the authenticated user's STEM account. It clearly separates itself from mutation siblings by stating 'This read does not change memories,' but it never names or routes to a specific sibling tool such as graph or memory_status, so sibling differentiation is implied rather than explicit.

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 provides clear when-to-use cases: recall preferences, past decisions, resume a project, or reuse context saved by another compatible assistant. It also sets boundaries by saying retrieval is bounded and not an exhaustive archive search, but it does not explicitly point the agent to an alternative sibling when a broader search is needed.

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

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

Annotations already flag mutation and non-idempotency; the description goes further, disclosing cross-session persistence, cross-assistant visibility, the returned fields (memory ID, source, type, autolinked IDs), and the duplicate-on-retry risk. That is exactly the operational context an agent needs before a write call.

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 action and its trigger, then constraints, then return values — a sensible order with no filler. It runs six sentences, and the return-value sentence partially duplicates what a caller could infer, so it is dense rather than perfectly 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?

A mutation tool with no output schema, yet the description covers the trigger, exclusions, persistence model, return payload, and retry hazard. Nothing material is missing for an agent to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it clarifies that saving creates links and can duplicate on retry, and that tags are labels not permissions. It largely restates rather than extending type/source semantics, keeping it 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 (Save) plus the exact resource (a distilled fact, preference, decision, idea or note) and the destination (the authenticated user's STEM account). It also names what it does not do (read/import conversations, browse the web, access other users' data), which separates it cleanly from recall, forget and remember_automatically.

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 crisp trigger — 'when the user explicitly asks to remember it' — implied contrast with the automatic sibling, plus hard exclusions ('Do not store whole transcripts or secrets'). It never explicitly names remember_automatically as the alternative path, so routing between the two still requires inference.

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

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

Goes well beyond the annotations: consent is re-checked server-side on every write, saves are best-effort, retries can duplicate an entry, and it enumerates what is returned (memory ID, source, type, autolinked IDs). It also discloses negative scope (no transcript import, no browsing, no cross-user access), which annotations alone could not 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 action and the consent prerequisite, and each subsequent sentence carries a distinct constraint or exclusion. It is denser than typical, but no sentence is filler; the prohibition list is the only mildly repetitive part.

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 non-idempotent mutation gated on consent, the description covers prerequisite, call-time checks, failure/duplication behavior, return shape (compensating for the absent output schema), and prohibited inputs. An agent has everything needed to decide whether and how to call it.

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

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

Schema coverage is 100%, so the per-field semantics are already documented; the description nonetheless adds constraint-level guidance on what may be passed ('never store whole transcripts or secrets') and notes that autolink results surface as autolinked IDs in the response. Tags, type and source are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (save distilled context to the user's STEM account) and scopes it to opted-in automatic saving. It is clearly separable from siblings by explicitly naming memory_status as a prerequisite and remember as the explicit-save alternative.

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 precondition ('First call memory_status with an empty object: only automaticSavingAllowed exactly true permits...'), the conditions that block a save (host confirmations, no-save instructions), and the alternative tool for explicit requests ('Use remember for explicit user save requests').

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