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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds material context beyond them: the deprecation window (removed 2027-03-31, answers unchanged until then), the write-scope requirement, and the dedup rule ("same name, same class and same tenant always return the same id, so calling twice creates no duplicate"). It also disambiguates upsert-vs-create semantics by noting it returns the existing node.

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 deprecation notice and replacement pointer are correctly front-loaded, and the operational guidance that follows is dense rather than padded. It runs slightly long for a deprecated alias, but nearly every sentence carries actionable instruction, so no serious trimming is warranted.

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 create-style tool with no output schema, the description covers purpose, idempotency, naming contract, class sourcing, dependency on knowmind_schema/knowmind_link, and the migration path. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters and baseline is 3. The description adds real meaning on top: name must be the plain proper name ("PostgreSQL", not "the database we use") and entity_class must come from knowmind_schema -> entityClasses.

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 the node for a thing the corpus talks about") and enumerates concrete entity types (person, organisation, application, host, technology). It also names its replacement, knowmind_upsert_entity, so an agent can distinguish it from every sibling 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 explicit routing (use knowmind_upsert_entity instead), the condition for using the tool at all ("when a name recurs across memories or when you are about to link something that has no node yet"), and the follow-up action ("then connect it with knowmind_link"). When-to-use and when-not-to-use are both covered.

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 and non-destructive, so the description rightly spends its words elsewhere: it discloses that a read scope suffices (auth requirement) and that it returns a status object per component. It stops short of describing status values or failure modes.

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 tight sentences, front-loaded with the purpose, then usage, then return/auth facts. Every sentence carries distinct information 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?

For a parameterless, output-schema-less health check, the description covers what it does, when to call it, the auth scope, and the shape of the return. 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?

Zero parameters, so the baseline is 4. The description confirms 'takes no parameters', aligning with the empty schema, though there is no parameter meaning to add.

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

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

States a specific verb and resource ('Return the health of the knowmind backend') and enumerates the components covered (Postgres, memory service, graph). An agent can tell this apart from stats/schema siblings immediately.

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 triggering conditions: 'before a batch of writes or when calls fail, to tell an outage apart from an empty result.' That is strong context, but it never names or excludes the near-identical 'knowmind_health' sibling, so an agent gets no routing help between the two.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond these by stating the authorization requirement ('Read scope suffices') and enumerating the return contents (edge types, subject/object classes, usage notes). It stops short of describing formatting or caching behavior, 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?

Three sentences, each earning its place: what is returned, when to call it, and the auth scope. The most important routing instruction (call before knowmind_link) is front-loaded and there is 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?

For a zero-parameter, read-only retrieval tool with no output schema, the description fully covers purpose, sequencing, auth scope, and the shape of the returned content. An agent has everything needed to call it correctly without opening any other field.

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 is 4. The description correctly implies the tool is scoped implicitly to the caller's tenant ('this tenant's knowledge graph'), which is the only contextual input that matters 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: 'Return the relation catalogue of this tenant's knowledge graph.' It further specifies the payload (every allowed edge type with subject/object classes and usage explanations), which distinguishes it from siblings like knowmind_link or knowmind_list_relations.

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 instructs 'Call this before building edges with knowmind_link,' naming the exact alternative and the condition that selects it. The rationale ('pick the right predicate instead of the nearest-sounding one') makes the when-to-use reasoning unambiguous.

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, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description still contributes the auth requirement ('Read scope suffices') and the fact that it takes no parameters, which the annotations do not convey. It stops short of noting anything about cost, caching or freshness of the counts, so it falls just short of a 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?

Two sentences: the first declares the return content, the second covers usage, alternatives and prerequisites. No filler, and the most important information (what is counted) is 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?

With no output schema, the description carries the burden of describing the return and it does so by enumerating the three count categories. Combined with the read-scope note and the zero-parameter statement, an agent has everything needed to call this correctly and interpret the result.

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 is 4; the description confirms this explicitly ('takes no parameters'), which removes any doubt about supplying arguments. Nothing further can be added about parameters.

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?

Names a specific verb and resource ('Return current counts for the tenant corpus') and enumerates exactly what is counted: memories, graph edges and vector chunks. It explicitly differentiates itself from knowmind_list_recent and knowmind_recall, so an agent can route correctly without opening sibling schemas.

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

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

States the use case directly ('Use to gauge how much has been stored') and names the alternatives to pick instead when actual entries are wanted ('for the actual entries use knowmind_list_recent or knowmind_recall'). It also gives the prerequisite ('Read scope suffices'), leaving nothing to 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?

Beyond the readOnly/idempotent/destructive annotations, it discloses lifecycle behavior (deprecated, removed 2027-03-31, answers unchanged until then), the auth requirement ('read scope suffices'), that it takes no parameters, and the shape of the result ('status object per component'). These are substantive traits the annotations do not carry.

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

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

Front-loaded with the deprecation warning, then purpose, usage, return shape and auth in four tight sentences. Every sentence adds information; nothing is repeated from the schema or annotations.

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?

There is no output schema, so the description compensates by stating the return is a per-component status object. Deprecation, auth scope, and usage context are all covered, leaving nothing an agent needs 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. The description confirms 'takes no parameters', which is consistent with the empty schema and leaves no 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?

States a specific verb and resource ('Return the health of the knowmind backend') and enumerates the components checked (Postgres, memory service, graph). It also distinguishes itself from its replacement knowmind_get_health and flags its own deprecation, so an agent can place it immediately.

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 conditions: 'before a batch of writes or when calls fail, to tell an outage apart from an empty result.' It also names the successor tool and the migration deadline, which is exactly the routing information an agent needs.

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 only declare idempotentHint=true, destructiveHint=false, readOnlyHint=false and openWorldHint=false; the description adds substantially beyond that: ontology shape validation before write, warn-only behavior for classless entries, the evidence-required rule, the fact that rejects return the violated rule, automatic inverse-edge materialization, and the 'Requires write scope' auth note. This is exactly the behavioral context annotations cannot carry.

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

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

The deprecation notice and replacement name are correctly front-loaded, and the workflow/procedure sentences earn their place. The trailing enumeration of ~49 relation types is long but necessary because no enum exists in the schema; the only real cost is that this bulk sits at the end rather than being summarized earlier. Slightly over-long but not wasteful.

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 still covers the return path for failures ('A rejected edge returns the violated rule') and the automatic inverse/derived edge behavior. Combined with write-scope, evidence, and validation rules, an agent has everything needed to call this correctly or to choose the successor tool instead.

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%, which sets a baseline of 3, but the description materially exceeds it: it enumerates all allowed rel_type values with their subject→object class domains (a list the schema only references as 'from the allowed list' with no enum), and reinforces the evidence and confidence requirements. The rel_type catalogue is the single most important piece of parameter meaning and the schema does not contain 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?

States a specific verb and resource ('Create a typed relation between two memory nodes (a knowledge-graph edge)') and frames the tool's role in graph construction, not just its mechanics. It immediately distinguishes itself from sibling knowmind_link_entities by declaring the deprecation and the replacement name, so an agent can route 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 explicit when-to-use ('after storing memories, connect them'), when-not ('derived edges ... never set them by hand'), the replacement tool for new work (knowmind_link_entities), and the prerequisite workflow (get both node IDs via knowmind_recall first, call knowmind_schema for the catalogue). Alternatives and prerequisites are spelled out rather than implied.

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=false, idempotentHint=true, destructiveHint=false, so the safety profile is known. The description adds substantial behavioral context beyond that - server-side ontology-shape validation, subject/object class requirements, evidence-required rejection with the violated rule returned, and automatic inverse/derived edge materialization. This is genuinely rich beyond the annotation bar, though the annotation already covers the write/idempotency basics.

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 critical usage constraints are front-loaded and earn their place, but the inline enumeration of ~60 rel_type values dominates the text and partly duplicates the referenced knowmind_schema catalogue, which the description itself tells the agent to consult. Structure is good; length is heavier than needed.

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 5-param write tool with no output schema, the description covers purpose, prerequisites, validation/failure behavior, idempotency implications of automatic inverse/derived edges, and the full rel_type value space. An agent has everything needed to call it correctly and to anticipate rejection.

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, and the schema already documents from_id/to_id/evidence/confidence. The description goes further by enumerating the full allowed rel_type catalogue against a schema that declares no enum, plus the class-compatibility constraint the value must satisfy - real added meaning for the key parameter.

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 ('Create a typed relation between two memory nodes (a knowledge-graph edge)') and immediately frames the role in the graph. It names the sibling helpers it depends on (knowmind_recall, knowmind_schema), giving an agent enough to distinguish the task.

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 says when to use it ('after storing memories, connect them'), why it matters ('a corpus without edges answers only what a single note already says'), and what NOT to do ('derived edges ... are computed by the server - never set them by hand'). It routes to alternatives for prerequisites (recall, 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is the domain behavior it discloses: open relations do not feed derivation rules until confirmed, and read scope suffices for authorization. Useful context beyond the structured fields, though paging/volume behavior is not discussed.

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 purpose before enumerating states and reasons; each sentence carries information. It is dense and packs several parenthetical definitions into one paragraph, which slightly slows scanning but wastes no words.

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 present, the description carries the return-shape burden and does so: it explains per-relation state, reason, connected entries, source, evidence, and per-state counts. Combined with the sibling pointer and scope note, an agent has everything needed to call and interpret 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 description coverage is 100% for all three parameters (limit, offset, status), including ranges and enum values, so the schema already carries parameter meaning. The description adds nothing about parameter syntax, making the baseline 3 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 concrete verb+resource+scope: relations awaiting a human decision, with their review state and reason. It implicitly separates itself from knowmind_list_relations by narrowing to inferred/pending items, though it never names that sibling to make the boundary 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?

Gives a clear use case ('review what the graph learned on its own') and names the companion tool that records the decision (knowmind_review_inferred). It does not state an explicit when-not or contrast against knowmind_list_relations for already-confirmed relations.

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/idempotent/non-destructive, but the description goes well beyond them: it names the retrieval architecture (BM25 + pgvector + knowledge graph), the return shape (top-k chunks with relevance score and source reference), the meaning of every metadata.review_flags value, the kein_belastbarer_treffer signal for 'no answer in corpus', and the auth requirement ('Read scope suffices'). This is exactly the extra context annotations cannot carry.

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

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

Front-loads the deprecation notice and the replacement tool, then the purpose, then the flag semantics — good ordering with no filler sentences. The review_flags enumeration is dense and long, but each clause defines a distinct value that would otherwise be opaque; only mildly over-sized.

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?

No output schema exists, and the description compensates by describing the return shape (top-k chunks, relevance score, source reference) plus the semantics of embedded flags. Combined with the deprecation timeline and scope note, an agent has everything needed to call and interpret it correctly.

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

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

Schema description coverage is 100%, so query/k/hops are already fully documented, including that hops currently has no effect. The description adds no syntax, format, or trade-off guidance beyond the schema (e.g., no guidance on choosing k), 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 ('Retrieve relevant knowledge') plus the situations it serves (decisions, preferences, project state, people, deadlines, past conversations). It explicitly distinguishes itself from two siblings by name (knowmind_recall_memories as successor, knowmind_recall_at_time for point-in-time), so an agent can route without opening any schema.

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

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

Gives an explicit when-to-use ('before answering anything that benefits from prior context'), an explicit when-to-use-the-alternative ('use knowmind_recall_at_time when you need what was valid at a past point in time'), and a deprecation route to the replacement tool. Nothing is left to inference.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, but the description adds real behavioral context they cannot: review_flags on OKF pages (stale/superseded judged against as_of), the kein_belastbarer_treffer sentinel meaning, and the 'read scope suffices' auth note. It stops short of describing pagination or result ordering, so it is strong rather than 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?

Front-loads the core purpose and routing rule in the first two sentences with no wasted framing. The back half (review_flags, kein_belastbarer_treffer, 'unless they clearly answer the question, say so') is dense and the final clause is slightly ambiguous, costing a point.

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 burden of explaining notable return semantics, and it does so for review_flags and the kein_belastbarer_treffer sentinel. The bounded k and default-to-now as_of are covered by the schema, so an agent has what it needs; only ordering/pagination of results is unspecified.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above baseline by explaining what as_of actually controls - the valid_from/valid_to validity window and how review_flags are evaluated against it - which the schema's 'ISO-8601 timestamp to evaluate validity at' does not spell out.

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?

Names a specific verb and resource ('Time-travel recall: return only memories that were valid at a given instant') and states the exact validity predicate (valid_from <= as_of <= valid_to, or still open). It explicitly distinguishes itself from the sibling knowmind_recall, so an agent can route 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 an explicit selection rule: 'Use instead of knowmind_recall when the point in time matters; otherwise use knowmind_recall for the current truth.' Names the alternative and the condition that picks it, leaving nothing to 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?

Annotations only cover the safety profile (readOnly/idempotent/non-destructive/closed-world); the description goes well beyond that, disclosing the retrieval pipeline, the return shape (top-k chunks with relevance score and source reference), the auth requirement ('Read scope suffices'), and a full decode of metadata.review_flags values (stale, unverified, superseded, drifted) and of kein_belastbarer_treffer. No contradictions with 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 purpose and the sibling distinction, and every clause carries usable information. It loses a point because the review_flags enumeration is delivered as one very dense semicolon-chained sentence that is harder to parse than the rest of the text.

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 burden of explaining returns and does so: chunk count, relevance score, source reference, review_flags semantics, and the negative-signal flag. Auth scope and the time-scoped alternative are also covered, leaving nothing essential missing for correct invocation.

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

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

Schema description coverage is 100%, so all three parameters (including k's bounds and hops' no-op status) are already documented structurally; that sets the baseline at 3. The description adds only indirect hints ('top-k', hybrid recall) and no per-parameter syntax or format detail beyond the schema.

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

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

States a specific verb+resource ('Retrieve relevant knowledge') plus the scope ('over the tenant corpus') and the retrieval mechanism (hybrid BM25 + pgvector + knowledge graph). It explicitly names the sibling it is not (knowmind_recall_at_time) and the condition that distinguishes them, so an agent can route 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 an explicit trigger ('before answering anything that benefits from prior context - decisions, preferences, project state, people, deadlines, past conversations') and names the alternative tool plus the condition selecting it ('when you need what was valid at a past point in time'). It also tells the agent what to do when the result is empty of signal ('unless the hits clearly answer the question, say so').

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 explains the exact effects of confirm, reject, and undo, including that reject sets valid_to=now on the relation, its reverse, and all derived relations while deleting nothing. It also notes the return payload and that write scope is required, giving rich operational 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 front-loaded with the core action and then systematically covers decision semantics, parameter usage, return values, and scope requirements. Every sentence carries necessary information 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?

For a mutation tool with no output schema, the description is complete: it covers inputs, decision effects, return contents, and authorization scope. An agent has everything needed to invoke it correctly.

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

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

The schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond schema: it defines the semantic consequences of each decision enum value and clarifies that evidence is optional. This goes well beyond the schema's terse 'confirm, reject, or undo a rejection'.

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: 'Record a human decision on one inferred relation from knowmind_list_inferred.' It explicitly names the sibling tool that produces the input, so an agent can distinguish it from other review 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?

The description clearly places the tool after knowmind_list_inferred and explains what each decision value accomplishes, giving strong context for when to use it. However, it does not state when not to use it or name alternative tools for related tasks.

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 only cover the read-safe profile, but the description adds the deprecation lifecycle (removal date, unchanged behavior until then) and the authorization requirement ('read scope suffices'), which annotations cannot express. It also confirms idempotent stable answers via 'keeps answering unchanged'.

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 deprecation warning is front-loaded, followed by what it returns and when to call it. Four short sentences, each carrying distinct information with no repetition.

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 compensates by describing the payload shape (edge types plus subject/object classes and usage explanations) and the precondition for calling it correctly. Nothing needed to invoke it 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 beyond confirming the call needs no arguments, which is implicit in 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?

States the resource precisely: the tenant's relation catalogue, every allowed edge type with subject/object classes and usage explanations. It also names the exact replacement sibling (knowmind_get_schema), so an agent can distinguish this legacy alias from its successor 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 routes the agent: use knowmind_get_schema instead, and call this before building edges with knowmind_link to pick the right predicate. Both the when-to-use and the named alternative are stated rather than implied.

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 past the annotations: the deprecation window (removed 2027-03-31) and the guarantee that behavior stays unchanged until then are lifecycle facts no annotation can express, and 'read scope suffices; takes no parameters' documents the auth requirement and call shape. It also discloses the return contents (three count categories), which matters since there is no output 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?

The deprecation warning is front-loaded, followed by purpose, routing guidance, and call requirements — four clauses, no filler, nothing repeated for its own sake.

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 zero-parameter read tool with no output schema: it covers purpose, return shape, migration path, auth scope, and lifetime. An agent has everything needed to decide and call 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 takes zero parameters, so the baseline is 4, and the description correctly confirms 'takes no parameters' rather than inventing inputs. There is no additional parameter meaning to add.

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

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

States a specific verb and resource ('Return current counts for the tenant corpus') and enumerates exactly what is counted: memories, graph edges and vector chunks. It also names its own replacement (knowmind_get_stats) and the entry-listing siblings it is not, so an agent can separate it from the other stats/list 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?

Gives explicit when-to-use ('gauge how much has been stored') and explicit when-not plus alternatives ('for the actual entries use knowmind_list_recent or knowmind_recall'). It also routes future callers to knowmind_get_stats with a concrete sunset date.

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 give the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds substantial context beyond them: 'Always creates a new entry' with titles as non-keys, sha-identical content treated as idempotent, the never-hard-delete/supersede model, the write-scope requirement, and 'Returns the new memory id.' The idempotency nuance refines rather than contradicts the annotation.

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 scoping, but the body is long and repeats content already in the schema and annotations — notably the 'A memory without edges is a note...' metaphor appears here and again verbatim in the relations schema description. The all-caps emphasis and duplicated predicate list dilute the density.

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 7-param mutation tool with no output schema, the description covers everything an agent needs: effect (creates one entry), return value (the new memory id), auth scope, the never-deleted/superseded lifecycle, and the edge-creation side effect. Nothing material is missing.

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

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

Schema coverage is 100%, so the schema already documents all 7 parameters and even embeds the allowed predicate list. The description still adds meaning by insisting relations be set in THIS call ('GIVE THE EDGES ALONG') and warning that the server creates the counterpart node and edge, so no separate knowmind_recall/entity/link call is needed — semantics beyond the schema.

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

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

States a specific verb+resource ('Store durable insights... Persists one memory entry in the tenant corpus') and enumerates what qualifies (decisions, preferences, facts, results, appointments). It explicitly separates the tool from siblings: knowmind_recall/knowmind_list_recent for retrieval, knowmind_upload_document for long text, knowmind_update_fact for superseding, knowmind_link for connecting existing entries.

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 and when-not: 'Use for a single short fact; for long or multi-fact text use knowmind_upload_document' and 'Use knowmind_link separately only to connect two entries that already exist.' It also routes supersession to knowmind_update_fact and removal to knowmind_unlink_entities, covering the alternatives by name.

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: inverse and inferred edges are removed along with the edge (cascade), the edge is retained in history and retrievable via knowmind_recall_at_time (soft delete, reversible read path), repetition is a no-op, and write scope is required. Annotations already declare destructive/idempotent; the description adds the consequential detail.

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 deprecation and replacement, then packs functionality, cascade semantics, history behavior, idempotency, and auth into short declarative clauses 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?

No output schema, so the description must cover behavior, and it does: lifecycle (deprecated with date), side effects (inverse/inferred edges), durability (history + recall_at_time), idempotency, and permission requirements. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% with all three parameters documented (including the UPPER_SNAKE_CASE, 'exactly as created' constraint), so the schema carries the parameter burden. The description adds no parameter-level detail beyond the schema, which is the baseline 3.

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 precise verb+resource: 'End a relation between two memories.' It also names the sibling that supersedes it (knowmind_unlink_entities) and the inverse operation it undoes (knowmind_link), so an agent can place it exactly in the graph-editing family.

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 away from this tool to knowmind_unlink_entities, gives the cutoff date (2027-03-31), and states the remaining legitimate use case ('Fixes a wrong knowmind_link'). When-to-use, when-not-to-use, and the alternative are all present.

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 destructive and idempotent, but the description adds real behavioral depth beyond them: inverse and inferred edges are cascaded, the edge persists in history where knowmind_recall_at_time can find it, and the call requires write scope. Cascade scope and the auth requirement are exactly the kind of context an agent cannot get from the hints alone.

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 short sentences, front-loaded with the core action and effect, then cascading consequence, then idempotency, then the auth prerequisite. Nothing is padding; every clause carries a distinct fact.

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 covers the important call-time concerns: cascade effects, history retention, idempotency, and write-scope requirement. It stops short of describing what happens if the named relation does not exist, but that is largely implied by the stated idempotency.

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 from_id, to_id and rel_type are already fully documented in the schema, including the UPPER_SNAKE_CASE convention. The description adds no syntax or format detail 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 states a specific verb and resource ('End a relation between two memories') and immediately scopes it against siblings by naming the inverse operation (knowmind_link) and the history lookup tool (knowmind_recall_at_time). An agent can distinguish this from knowmind_link_entities 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 one usage scenario ('Fixes a wrong knowmind_link'), which implies when to reach for it, but never states when NOT to use it or names an explicit alternative tool for corrections. The routing signal is implied rather than spelled out.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds materially: what actually happens to the superseded version (it stays retrievable via knowmind_recall_at_time), the content-based dedup behavior (no new document, response carries 'deduplicated'), and the write-scope prerequisite. This clarifies the practical meaning of the destructive flag rather than merely restating it.

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 scoping first, then upsert/dedup semantics, then when-to-use, then the required scope. Dense but every sentence carries information; the only cost is that it is long and packs several distinct concerns (title upsert, dedup, return fields, post-ingest linking) into one block.

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?

There is no output schema, and the description compensates by naming the return values it can (document id, number of chunks written, replaced_document_ids, 'deduplicated'). With annotations covering safety, auth scope stated, and the alternative tool named, nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the upsert-by-title resolution rule, the same-domain constraint, and content-level dedup that no parameter documents. Minor tension: the description tells the agent to set edges via knowmind_link 'AFTER INGESTING', while the relations parameter description says to set them 'HERE, in the same call', which muddies rather than clarifies that parameter.

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 with scope: 'Ingest a longer text as one document into the tenant corpus', then enumerates the pipeline steps (chunk splitting, embeddings, vector chunks, graph nodes). It explicitly distinguishes itself from the sibling knowmind_store_memory ('for a single short fact use knowmind_store_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?

Gives an explicit when-to-use ('long-form or multi-fact content (a report, a page, a doc)') paired with when-not and the named alternative ('for a single short fact use knowmind_store_memory'). It also prescribes the follow-up workflow (extract facts, create edges via knowmind_link) and states the required write scope.

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 non-read-only plus idempotent, but the description goes further: it names the identity key ('same name, same class and same tenant always return the same id, so calling twice creates no duplicate') and discloses the authorization prerequisite ('Requires write scope'), neither of which appears in the annotation block. It stops short of describing the returned payload beyond 'the existing one', which is a minor residual 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?

Front-loaded with the core action and its dedup behavior, and the routing sentence to knowmind_link comes before the finer naming conventions. The capitalized 'THE GRAPH NEEDS THESE' framing is rhetorical padding that does not add actionable content, but the remainder is dense and 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 four-parameter, partially-required write tool with full schema coverage and no output schema, the description covers the essential set: when to call, key identity semantics, authorization scope, naming convention, and where to source the class catalogue. There is no output schema, so return values need not be enumerated.

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, and the description adds meaning beyond it by directing where entity_class values come from ('pick the class from the catalogue in knowmind_schema') and reinforcing the naming convention for name. That cross-tool pointer is genuinely useful, though the naming advice partially duplicates the schema's own wording.

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 ('Create the node for a thing the corpus talks about') and immediately covers the upsert fallback ('or return the existing one'), listing the entity kinds it applies to. It also separates itself from knowmind_link, which is the nearest sibling, 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 explicit triggering conditions ('when a name recurs across memories or when you are about to link something that has no node yet') and names the follow-up tool ('then connect it with knowmind_link'). Alternatives and ordering relative to linking are both stated, not implied.

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