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

Discloses that same name/class/tenant returns the same id (idempotent) and that it requires write scope, which aligns with annotations. Adds context about not duplicating nodes, though it does not describe failure modes or side effects beyond creation.

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 verbose and includes a rationale paragraph ('THE GRAPH NEEDS THESE') that, while informative, could be trimmed. It repeats the idempotency point and includes imperative naming/style advice that lengthens the text without drastically improving clarity.

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?

Provides comprehensive context: why entities are needed, when to create, naming conventions, class catalogue, and write scope. Despite no output schema, the description gives enough for an agent to invoke correctly, though it omits edge cases like duplicates or conflicts.

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 already covers all four parameters with descriptions; the description adds guidance for name formatting (plain proper name) and entity_class selection (from knowmind_schema catalogue). This adds value for the main parameters, while aliases and description rely on 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 the tool creates an entity node or returns an existing one, with clear scope (person, organization, application, host, technology). Mentions related tools like knowmind_link, but does not explicitly name an alternative sibling to avoid, so purpose is clear but not maximally distinguishing.

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?

Provides explicit conditions for when to create an entity (when a name recurs or before linking to something without a node) and instructs to connect with knowmind_link. This gives concrete usage guidance beyond the schema.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds useful context by stating read scope suffices, no parameters, and returns a status object per component, which helps the agent understand the tool's behavior 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?

The description is brief and well-structured: the first sentence states the purpose, the second provides usage and return details. No unnecessary information, and the key points are front-loaded.

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 simple health-check tool with no output schema, the description is complete. It covers what the tool returns (status per component), when to use it, and that it is read-only, leaving no ambiguity for the agent.

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

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

There are no parameters, so the input schema is trivially complete. The description explicitly notes 'takes no parameters', reinforcing that no arguments are needed and adding clarity beyond the empty 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?

Clearly states it returns the health of the knowmind backend and lists the components (Postgres, memory service, graph). The verb 'return' is specific and distinguishes this from sibling tools like stats or list operations.

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 provides usage scenarios: before batch writes or when calls fail, to distinguish an outage from an empty result. This gives clear guidance on when to use this tool versus alternatives.

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 annotations, the description discloses automatic inverse edge materialization, that certain derived edges are server-computed and must not be manually set, and that write scope is required. These behavioral details are not present in the annotations and materially affect how the agent plans its calls.

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 core purpose is front-loaded and the explanatory text is efficient. The long list of allowed rel_type values is necessary and directly actionable; while lengthy, it is the core value offered over the structured schema rather than fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nontrivial edge-creation tool, the description covers workflow, prerequisites, allowed values, semantic constraints, derived edges, and scope requirements. No output schema exists, but the tool's return format is not needed to invoke it correctly; the description is sufficiently complete.

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% for IDs and confidence, but the rel_type schema only says 'from the allowed list' without listing it. The description compensates with the full list of allowed values and the subject/object class mappings for each relation, which is critical for selecting a valid parameter value.

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: 'Create a typed relation between two memory nodes (a knowledge-graph edge)'. It clearly distinguishes this from recall/list/store operations and explains how it fits into graph construction.

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 when to use the tool ('after storing memories... connect them') and gives explicit prerequisites: get node IDs via knowmind_recall and call knowmind_schema for explanations. It also tells what NOT to do: 'never set derived edges by hand', which removes guesswork.

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 cover the read-only, idempotent, non-destructive profile, lowering the bar. The description additionally discloses the sorting key, the corpus identity, an important exclusion ('graph-only entities without a timestamp do not appear'), and the cross-tool discrepancy ('count intentionally differs from stats.memories') — the kind of nuance that prevents an agent from misinterpreting the result.

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?

Three sentences with zero wasted words: front-loaded purpose and ordering, then usage guidance, then behavioral caveats and scope. Every sentence earns its place, there is no redundancy with the schema or annotations, and the critical sibling routing appears early.

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 one-parameter, read-only tool this is nearly complete: annotations carry safety, the schema covers k entirely, and the description covers ordering, corpus, exclusion behavior, and permission requirements. The only minor gap is that no output schema exists and the description does not spell out the fields per returned entry; agents can partially infer them from the size of the data but a small hint would be fully closed.

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

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

Schema description coverage is 100% — the single parameter k is fully documented in the input schema with range and default, so the description carries no parameter-meaning burden. The description does not add new semantics for k beyond what the schema already states, making baseline 3 appropriate. This is acceptable, not strong.

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?

Identifies a specific verb and resource — listing the most recently created documents/memories — with the ordering semantics ('newest first by created_at') and corpus scope ('same corpus that recall searches'). It also names the sibling it is not ('use knowmind_recall when you already know what you are looking for'), so an agent can discriminate among the 12 siblings without opening schemas.

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

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

Gives explicit when-to-use ('review what was just stored or confirm a write landed') and an explicit alternative-route rule ('use knowmind_recall when you already know what you are looking for'). Also supplies the permission precondition ('read scope is sufficient') so the agent knows it does not need write credentials.

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 indicate read-only, idempotent, and non-destructive behavior. Description adds context by saying 'Read scope suffices' and explaining the intended use case, reinforcing safety but not contradicting 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?

Two concise sentences with no redundant wording. The structure clearly separates what the tool does from when to use it, and includes necessary cross-references.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the single parameter and clear purpose, the description covers all necessary context: what it returns, when to use it, and how to get the required ID. No gaps for the user to infer.

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 only parameter memory_id is fully described in the schema (including how to obtain it). The description repeats this but does not add new meaning, 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?

Clearly states the tool lists all relations of a memory, both incoming and outgoing, with edge type and connected node, distinguishing it from sibling tools like knowmind_link and knowmind_recall.

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 tells when to use it: before adding or removing edges with knowmind_link/knowmind_unlink, and instructs to get memory_id via knowmind_recall, plus notes that read scope is sufficient.

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 cover read-only and non-destructive hints; the description adds meaningful behavioral detail: hybrid recall (BM25 + pgvector + graph hops), top-k chunks with relevance scores and source references, and 'Read scope suffices' for permissions. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded, but contains minor redundancy: 'Retrieve relevant knowledge before answering anything...' and 'Suitable whenever earlier context would improve the answer' overlap. Overall it is appropriately sized, earning a strong score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the description covers the operation, when to use, return format (top-k chunks with score and source), and safety. The annotation set plus description provide a complete picture; no output schema exists, but the description compensates for it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the hybrid recall approach and the role of graph hops, which gives meaning to k and hops parameters, though it does not detail each parameter's syntax.

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 uses a specific verb ('Retrieve relevant knowledge') and resource (memory chunks from the tenant corpus), and explicitly distinguishes itself from knowmind_recall_at_time. It leaves no doubt about what the tool does.

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

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

The description explicitly states when it is suitable ('whenever earlier context would improve the answer') and names the alternative (knowmind_recall_at_time) for past-point-in-time retrieval. This is clear when/when-not 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?

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral detail about temporal validity filtering and notes that read scope suffices, going slightly 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?

The description is compact and front-loaded with the core purpose, followed by a concrete example of the question it answers and a clear tool-selection guideline. No unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the temporal recall behavior and relationship to the current-truth variant, while the schema covers parameter bounds and defaults. It does not describe output format, but no output schema is present and the core usage context is sufficiently covered.

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

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

The schema already covers all parameters with descriptions, so the baseline is 3. The description adds the validity-interval semantics (valid_from <= as_of <= valid_to, or still open), which clarifies how as_of is used beyond 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 clearly identifies the verb (recall), resource (memories), and temporal scope (valid at a given instant), and explicitly distinguishes it from the sibling tool knowmind_recall by noting when to use each.

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

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

It gives explicit usage direction: 'Use instead of knowmind_recall when the point in time matters; otherwise use knowmind_recall for the current truth.' This directly routes the agent to the correct tool choice.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description reinforces the read-only nature and adds useful behavioral context: it is scoped to the tenant's graph, returns a catalogue, and 'read scope suffices'. There is no contradiction and it adds meaningful non-schema context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each earning its place: what it returns, when to call it and why, and what scope conveys. It is front-loaded, specific, and free of 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?

For a zero-parameter, read-only schema tool, the description is appropriately complete: it specifies the output content, its purpose, the tenant scope, and the read permission requirement. Agents have enough to invoke it correctly without more detail.

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 has zero parameters and an empty input schema, so no parameter-level semantics are needed. The baseline for a no-parameter tool is 4, and the description already explains what the returned data will contain.

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

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

The description states a specific action and resource: 'Return the relation catalogue of this tenant's knowledge graph' with the exact content (allowed edge types, subject and object classes, usage explanations). This clearly distinguishes it from data-query siblings like knowmind_list_relations and knowmind_recall, since it returns schema rather than graph instances.

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 guidance: call this before building edges with knowmind_link and use it to pick the correct predicate. The 'read scope suffices' note also sets permission expectations. It does not explicitly state when not to call it or contrast with alternatives like knowmind_list_relations, but the core usage context is strong.

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 readOnlyHint=true and destructiveHint=false, so the agent knows it is a safe read operation. The description adds 'Read scope suffices', which is consistent with the annotations but does not introduce new behavioral details such as rate limits or side effects. Since annotations cover the safety profile, the description adds minimal extra value.

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 concise, comprising two sentences, and is well-structured. It efficiently conveys the purpose, usage, and alternatives without unnecessary detail, making it easy to parse.

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 simple stats tool with no parameters, the description is complete: it defines the output (counts of corpus components), the purpose (gauge storage), and directs to alternatives. No additional context is required for an agent to use 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?

The tool has zero parameters and the schema is empty. The description explicitly states 'takes no parameters', which reinforces the fact despite the schema already being empty. The baseline for 0 parameters is 4, and the statement adds clarity without any ambiguity.

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

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

The description clearly states the tool returns counts for the tenant corpus (memories, graph edges, vector chunks) and explicitly distinguishes it from sibling tools by directing users to knowmind_list_recent or knowmind_recall for actual entries. The verb 'Return' is specific and the resource scope is defined.

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

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

The description explicitly indicates when to use the tool ('to gauge how much has been stored') and also states when not to use it, pointing to alternatives for retrieving actual entries. This provides clear usage boundaries.

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 annotations, the description reveals append-only behavior ('the same title replaces nothing'), a specific idempotence rule ('sha-identical content is detected as idempotent'), the returned value ('new memory id'), and a prerequisite ('Requires write scope'). It also explains that relations are persisted in the same call with no second tool needed. Slightly opaque on failure/error behavior and what happens to the graph node when there are no edges, so not a full 5.

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 purpose and a routing sentence in the first two lines. It is longer than it strictly needs to be because the 'GIVE THE EDGES ALONG' section and the schema description for relations repeat the same example and explanation. Still, most sentences earn their place by addressing behavior, routing, or parameters.

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 a complex tool with 7 parameters and no output schema, the description covers what matters most: what counts as an atomic memory, how to add relations in the same call, which sibling to use instead, and that it returns the new memory id. It is sufficiently complete for an agent to call the tool without requiring the schema or separate documentation.

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 operational nuance to key parameters: content should be a single short fact, relations should be filled in the same call with a concrete example, and title is not a uniqueness key. It also rationalizes the relations parameter by explaining the difference between a note and a graph memory, which helps an agent decide how to fill it.

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: 'Store durable insights' and 'Persists one memory entry in the tenant corpus (Postgres + vector index + graph node)'. It clearly differentiates this tool from close siblings: 'for long or multi-fact text use knowmind_upload_document' and 'use knowmind_update_fact to supersede'. An agent can immediately tell what this tool does and where it fits among the other memory tools.

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

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

The description gives explicit selection criteria: 'Use for a single short fact; for long or multi-fact text use knowmind_upload_document' and names knowmind_update_fact for superseding existing entries. It also tells the agent when not to use linking tools here: 'Use knowmind_link separately only to connect two entries that already exist'. This is full usage guidance with routing to alternatives.

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 carry destructiveHint=true, idempotentHint=true and readOnlyHint=false. The description adds genuine value beyond those by disclosing the cascade side effect ('the inverse edge is removed with it') and the write-scope requirement, which annotations don't state. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with zero waste: the primary action and its most important side effect are front-loaded, followed by idempotency, a use case, and a scope requirement. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, idempotent delete tool with 100% schema coverage and no output schema, the description is complete — it specifies the action, the cascade side effect, the intended use case, and the required authorization scope. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema fully documents from_id, to_id, and rel_type. The description's 'typed relation between two memory nodes' maps onto the parameters but adds no syntax or format detail beyond what the schema already provides, 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 ('Delete a typed relation between two memory nodes') and adds a key distinguishing behavior (the inverse edge is removed with it). It clearly contrasts with the sibling knowmind_link that creates relations, so an agent can tell them apart 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?

Explicitly names the use case ('Use to correct a wrong link created via knowmind_link') and the creation counterpart, plus a prerequisite ('Requires write scope'). It gives clear when-to-use context, though it doesn't enumerate exclusions against other sibling tools like knowmind_update_fact.

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 annotations (readOnly=false, etc.), the description reveals key behaviors: the old memory is marked with valid_to=now, the new memory is created with valid_from=now, and the old one is not deleted but linked via SUPERSEDES. It also discloses write-scope requirements and that it returns the new memory id, all essential for correct invocation.

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 structured and front-loaded with the core purpose, then elaborates the process, whether to use it, and return value. It's slightly dense in the last sentence (covering return, write scope), but every sentence earns its place and there is no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for a mutable tool with no output schema: it states the return (new memory id), the required permissions (write scope), the change semantics (not destructive), and the intended use case. Nothing an agent needs to know to choose and invoke the tool correctly is missing.

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

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

Schema description coverage is 100%; every parameter already has a clear meaning. The description does not further explain parameter-specific behavior (e.g., what update_reason is used for), so the baseline of 3 is appropriate – it adds no redundant detail but also doesn't go beyond the schema.

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

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

The description clearly states the verb 'supersede a known fact' and the resource (knowmind memory), with explicit semantics: valid_to=now, valid_from=now, and SUPERSEDES link. It distinguishes itself from knowmind_store_memory by naming that sibling and the exact condition ('when a fact CHANGES').

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

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

The description explicitly says 'Use this instead of knowmind_store_memory when a fact CHANGES (address moved, contract renewed)' and highlights that old statements are not deleted, making the tool suitable for auditable timelines. It also mentions the query tool knowmind_recall_at_time for reading history, providing clear context and alternatives.

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?

The description goes beyond the annotations by disclosing the upsert-by-title replacement behavior, server-side chunking/embedding, and the fact that it returns a document id plus chunk count. It also clarifies the destructive edge case in which an existing document with the same title is replaced, which is exactly the kind of context an agent needs despite destructiveHint being 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?

The description is dense and efficient, front-loading the core purpose in the first sentence. Every sentence carries meaningful information: when to use it, the behavior, the output, the alternative tool, and the follow-up workflow. No filler or redundant restating of the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is strong overall: it covers return values, write-permission requirements, upsert behavior, and follow-up links. Minor ambiguity remains because it directs the agent to create edges via knowmind_link after ingesting, even though the input schema allows edges via the 'relations' parameter in the same call, leaving two possible workflow interpretations.

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 input schema already covers all four parameters with full descriptions (100% coverage), so the baseline is 3. The description adds useful high-level context ('title acts as the upsert key', 'content is chunked and embedded server-side') but does not materially improve on the structured parameter documentation.

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 names a specific verb and resource ('Ingest a longer text as one document into the tenant corpus') and specifies the processing pipeline (chunking, embeddings, vector chunks, graph nodes). It also explicitly contrasts with knowmind_store_memory for short facts, making the tool's purpose distinguishable from siblings without opening them.

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

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

It explicitly states when to use the tool ('long-form or multi-fact content') and when not to ('for a single short fact use knowmind_store_memory'). It also gives a clear post-ingestion workflow via knowmind_link and the required write scope, giving the agent actionable context for choosing and using the tool.

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