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

Annotations only cover the safety profile (not read-only, not destructive, open-world, not idempotent). The description adds real context beyond that: the return payload (ID, store label, up to three active overlaps), the defaulting behavior for store/author/authority/confidence, and the notable quirk that an explicit zero confidence is treated as 0.8.

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 dense sentences with the primary action and return shape front-loaded; no filler. The middle sentence packs defaults and link rules tightly enough that it reads slightly as a spec dump, but every clause carries information an agent needs.

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

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

For a 12-parameter mutation tool with no output schema, the description covers return values, defaults, and the supersession constraint well. Minor gap: relevance and projectRoot routing are left entirely to the schema, so the picture is near-complete rather than 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%, so parameters are already documented, but the description still adds value by restating the defaults and the non-obvious confidence-zero behavior, and by clarifying that supersedes is comma-separated and gated by allowCrossScope. It doesn't cover relevance or projectRoot routing, so it is not a full supplement.

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

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

Opens with a specific verb + resource plus a distinguishing trait ('without an LLM call') and immediately states what is returned. It explicitly separates itself from gnosys_update, so an agent can route between the two without opening a schema.

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

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

Gives an explicit exclusion: use gnosys_update to change an existing memory or to unlink a predecessor via superseded_by="". It also states the precondition for cross-scope/cross-project supersession (allowCrossScope=true), so the branch conditions 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, idempotentHint, destructiveHint=false and a closed world, so safety is covered. The description adds value beyond that by disclosing the return format (Markdown, not JSON) and the precedence/default semantics. It doesn't explicitly say there are no side effects, but the read-only annotations make that clear.

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 dense sentences, each carrying distinct payload: output contents first, then selector precedence and defaults, then the sibling disambiguation. No repeated or filler 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 still names the return format and its components, and the selector/default rules cover the main invocation ambiguity. Nothing material is missing for a zero-required-param read tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: projectId precedence over projectRoot, cwd auto-detection, and that all=true silently ignores both selectors. That precedence rule is exactly the ambiguity an agent would otherwise trip on.

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 ('Summarize a project as Markdown') and enumerates the output contents (memory counts, categories, 7-day activity, top tags, summary). It also names the distinguishing sibling, gnosys_dashboard, so an agent can differentiate 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?

Explicitly gives selector precedence (projectId over projectRoot), fallback behavior (detect from projectRoot or cwd), and the all=true override that ignores both selectors with a stated default of false. It also routes the agent away to gnosys_dashboard for system health/graph stats/provider status.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so safety is covered. The description adds valuable context: returns JSON with specific sections and that omitting projectRoot uses the detected context. It doesn't mention performance, caching, or failure behavior, keeping it a step below the top.

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 with zero waste, front-loading the purpose and return contents before the alternative routing. Every clause 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?

No output schema exists, so the description carries the return-value burden, which it handles by listing the JSON sections. Combined with annotations covering the safety profile and the lenient default for projectRoot, it is nearly complete, missing only output shape details like nesting or formatting.

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

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

Schema coverage is 100% and the schema documents projectRoot as routing to a project's store. The description adds the meaningful default behavior that omission falls back to the detected context, which the schema does not state.

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 (Inspect) and resource (local memory-system health), enumerates the returned content (memory counts, maintenance health, graph statistics, LLM provider status), and explicitly names the sibling gnosys_briefing as the alternative. An agent can distinguish it from siblings without opening any schema.

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

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

Explicitly routes the agent to gnosys_briefing when a Markdown project summary and recent activity are wanted, and clarifies the projectRoot omission behavior. Clear usage context, though it doesn't state when-not to use this tool beyond that single alternative.

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 safety flags; the description adds real behavioral context beyond them – the shape of the return (scores, status, dates, replacement links), defaults for mode/limit/activeOnly, and prerequisite toolset state. The one gap is that annotations set readOnlyHint=false and idempotentHint=false while the description reads as a pure query, and it never explains what side effect or non-idempotency an agent should expect.

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 what the tool does and what it returns, then compresses the sibling routing and prerequisites into single clauses with no filler. Every sentence carries either a routing decision or a setup requirement.

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 correctly takes on the burden of describing return values and does so concretely. It also covers the toolset-unlock and reindex setup path; the only shortfall is that it doesn't account for the non-read-only, non-idempotent annotation profile.

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

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

Schema description coverage is 100% and already documents mode, limit, activeOnly and projectRoot defaults, so most of the description's parameter talk is repetition. The worked example ({"query":"JWT refresh flow","mode":"keyword","limit":5}) and the recall/read routing add modest value, but projectRoot's gnosys_init error path is left entirely to the schema.

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

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

States a specific verb and resource ('Search memories by keyword and meaning') plus the exact return payload (ranked snippets, IDs, scores, status, dates, replacement links). That return-field list and the mode vocabulary let an agent distinguish it from gnosys_recall and gnosys_read without opening either schema.

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

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

Explicitly routes to alternatives with conditions: gnosys_recall for a context block, gnosys_read for a full body, gnosys_search for plain keyword, gnosys_federated_search for scope boosts, gnosys_discover for metadata only, gnosys_semantic_search for embedding-only. It also states the toolset gating required to see those specialists and the extra steps (full toolset then gnosys_reindex) for embedding setup.

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 discloses side effects the annotations don't spell out: it creates .gnosys/ metadata and writes a registration into the central SQLite store, which explains the openWorldHint. But annotations declare destructiveHint=true and idempotentHint=false, and the description never says what happens on re-initialization of an existing root or what could be overwritten — the key risk an agent needs to know.

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

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

Three tight sentences that front-load purpose then prerequisites then the alternative. The return-value clause and the absolute-path example are both useful, though the example is arguably redundant with 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?

No output schema exists, and the description does say what comes back, plus the setup prerequisite and the sibling route. The remaining gap is re-initialization semantics, which matters given destructiveHint=true.

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 applies. The description reinforces the absolute-path requirement with an example and restates the projectName default, but it adds nothing about projectRoot, the one parameter whose routing behavior ('routes the call to that project's store') is the least obvious.

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 ('Initialize a project directory') and immediately names what it returns (identity, store path, setup summary). It also separates itself from the sibling gnosys_briefing, which inspects an existing project rather than creating one.

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

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

Explicit when-to-use ('run this before project-scoped operations on a new root') and an explicit alternative with its condition ('Use gnosys_briefing instead to inspect an already registered project'). Little 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 declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds value beyond that: which fields are returned, that missing keys yield a not-found message, and the kebab-case key convention. It does not disclose ordering or volume behavior when listing all preferences, which is the main remaining gap.

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

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

Two sentences, front-loaded with the primary behavior, then the list-all mode, then the alternative tool. Every clause carries information an agent needs; nothing is padding.

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

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

There is no output schema, so the description correctly compensates by naming the returned fields (title, value, confidence, modified date) and the failure mode. Minor gap: no guidance on result size or ordering for the list-all path, which matters for an enumerating call.

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

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

Schema coverage is 100% and the schema already documents both parameters, so the baseline is 3. The description goes further by giving the kebab-case convention and a concrete example ({"key":"code-style"}), which is meaning the schema does not supply.

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

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

States a specific verb and resource (read a user preference by key), then covers the second operating mode (omit key to list all) and the return fields. It distinguishes itself from the sibling that writes preferences by naming gnosys_preference_set explicitly.

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

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

Gives explicit mode selection ("omit key to list all preferences") and names the alternative tool with the condition that selects it ("Use gnosys_preference_set instead to save or replace"). An agent can route between read and write without opening either 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 declare destructiveHint=true and idempotentHint=false, so the overwrite risk is partly covered structurally. The description adds real context beyond that: preferences persist as user-scoped memories and generated rules files only refresh via 'gnosys sync'. It could say more about what happens to an existing value when the key is reused, but the operational side effects are disclosed.

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 front-loaded sentences: purpose and return, then the key-format example, then persistence and the get-alternative. Every sentence carries weight, though the kebab-case guidance duplicates the schema slightly.

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 usefully states what is returned (key, title, value) and explains the persistence model and sync requirement. The remaining gap is what 'replace' means for an existing key's tags or title, but nothing essential for a correct call 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 baseline is 3. The description's kebab-case example and the note that 'title is generated from the key if omitted' restate what the schema already documents rather than adding new semantics, so no credit above baseline.

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 ('Save or replace') and resource ('user preference'), states the scope ('across projects') and the return shape ('key, title, and value'). It also explicitly distinguishes itself from the sibling gnosys_preference_get, so an agent can choose 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 a clear routing rule: use gnosys_preference_get to inspect or list, and this tool to write. The kebab-case convention and the 'gnosys sync' follow-up are practical usage context. It lacks explicit exclusions versus other write-ish siblings such as gnosys_add_structured, which keeps it from a 5.

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, closed-world, non-destructive, so the safety profile is covered. The description adds value beyond that with the precedence-order store resolution for unprefixed paths and the shape of what comes back (content, metadata, supersession links). Not a full 5 only because it does not discuss ambiguity when an ID exists in multiple layers.

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 carrying distinct information: capability and return shape first, then path resolution semantics, then sibling routing. Zero filler and 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?

No output schema exists, yet the description summarizes the return payload and the supersession links. Combined with full schema coverage and exhaustive annotations, an agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description earns above baseline by giving concrete path syntax examples (arch-012, project:decisions/why-not-rag.md) and explaining the semantics of an unprefixed path. projectRoot is left entirely to its schema description, which is fully documented.

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?

Specific verb (Read) plus resource (a memory) with two accepted identifier forms shown by example, and it declares the return payload (Markdown content, metadata, supersession links). It is unmistakable against siblings like gnosys_hybrid_search and gnosys_recall, which it names.

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

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

Explicit routing: use this when you know the ID, use gnosys_hybrid_search when you do not, and gnosys_recall for several relevant memories as context. It also states the fallback behavior for unprefixed paths (search stores in precedence order), covering the ambiguous case.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive behavior beyond that: query="*" selects by reinforcement/confidence/recency, limit is capped at 15 and defaults from config, aggressive defaults to true, and registered projectRoots span project+user+global. It does not say what the unregistered-root failure looks like or how memory bodies are trimmed in the block, keeping it 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?

Front-loaded with purpose and example, then alternatives, then parameter behavior, then scope caveats — a sensible ordering. It is dense and slightly run-on in the final two sentences, but no sentence is filler.

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

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

For a 5-parameter read tool with full schema coverage and no output schema, the description supplies everything the agent needs: output form, wildcard behavior, caps, defaults, project scope, and the hook-duplication caveat.

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 still adds value by documenting the special wildcard value query="*" and its ranking semantics, which the schema does not mention. The limit and aggressive defaults largely restate schema text, so it is additive but not fully independent.

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?

Starts with a specific verb+resource ('Recall relevant memories') and names the exact output shape (a <gnosys-recall> context block for a task) with a concrete example query. It also explicitly distinguishes itself from gnosys_hybrid_search and gnosys_read later, 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?

Names alternatives and the conditions that select them: 'Use gnosys_hybrid_search instead to inspect ranked results or gnosys_read for one complete body.' It also gives explicit projectRoot rules (omit for all projects, run gnosys_init for unregistered roots) and warns that hooks may already inject this context, which is a real when-not-to-call signal.

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 declare non-readonly, non-idempotent, non-destructive, closed-world, but the description adds substantial behavior: default deltas, clamping to 0.05..1, that success reinforces targets and adds validates links while failure adds contradicts links, and the return payload. This is exactly the kind of write-operation semantics the annotations cannot convey.

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

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

Front-loads the return payload then the parameter defaults then the sibling alternative, with no wasted sentences. It is dense and packs several clauses into the middle sentence, but every clause carries information.

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

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

No output schema exists, yet the description enumerates the returned fields (ID, confidence delta, updated memory IDs and confidences, relationship count) and explains side effects on linked memories. Nothing needed to invoke it correctly or interpret its result is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: memoryIds defaults to 'up to five keyword matches on outcome', and success/confidenceDelta defaults are tied to each other and the clamping rule. Minor overlap with schema text keeps it from a 5.

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

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

States a specific verb and resource: 'Record an outcome as a new reflection memory', and lists what it returns. It explicitly names the sibling gnosys_reinforce as the alternative, so an agent can distinguish the two without opening either schema.

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

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

Explicitly routes the agent: 'Use gnosys_reinforce instead for usefulness feedback without creating an outcome memory', and warns that each reflection call creates a new record and reapplies the delta. Both the when-to-use and the when-to-use-something-else conditions are stated.

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 say readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description adds real substance by disclosing the side effect of every signal branch: useful increments reinforcement and resets decay, not_relevant records a routing miss without mutating the memory, and outdated only marks it for review. That both explains the non-idempotency hint and reassures the agent that two of three branches are effectively non-destructive.

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 effect of the tool is front-loaded in the first clause before the branch semantics and the sibling exclusion, which is the right ordering. The semicolon-chained enumeration of signal effects is dense but every clause carries distinct information; only the trailing repeat-behaviour note could be tightened.

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

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

For a 4-parameter tool with full schema coverage and no output schema, the description covers what is needed: what changes per signal, what is returned, and when to choose the sibling. Minor gaps remain around projectRoot routing and whether the signal confirmation has any payload, but nothing blocks a correct call.

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 earns above that by giving behavioural meaning to the signal enum values rather than restating the field. It adds nothing about context or projectRoot, which is acceptable since the schema already describes both.

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

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

The first clause names a specific verb and resource ("Record usefulness feedback for one memory") and states the return ("signal confirmation"). It goes further by spelling out the effect of each of the three signal values, so the agent knows exactly what operation it is selecting 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?

It names the alternative sibling explicitly ("Use gnosys_reflect instead to record an outcome memory, link evidence, and adjust confidence") and gives the condition that selects it. It also clarifies repeat behaviour ("repeated useful calls reinforce again"), removing the main ambiguity about calling this tool more than once.

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 mark this as a non-readonly but idempotent, non-destructive mutation, and the description adds the crucial context that switching affects 'this session' and returns added/removed tool names. That session-scoped effect goes beyond the annotations, though the exact return shape of an unchanged inspect is left implicit.

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 tightly packed sentences front-load the capability, then the switching semantics, then a compact example. Nothing is redundant relative to the schema.

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

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

For a single-param, no-output-schema tool, the description covers defaults, action vs inspection, session scope, and an example. A little more on what the returned catalog actually contains would close the remaining gap.

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 param is already documented. The description reinforces meaning with the omit-to-inspect rule and a worked example ({"set":"standard"}), adding practical clarity beyond the enum 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?

States specific verbs (list, set) and resources (active tier, higher-tier tool catalog, added/removed tool names), and names the exact enum values. This is clearly distinguishable from the sibling memory/query tools.

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

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

Explains the inspect-vs-switch decision ('omit set to inspect without switching') and the default ('starts on core'), plus a concrete example. Clear context, though it doesn't explicitly name when other tools should be preferred over switching tiers.

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, and closed-world behavior, and the description adds the traversal algorithm (BFS), output shape, and defaults for direction and depth. It does not discuss performance/pagination on large graphs, but the added behavioral context is substantial.

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 output shape, then defaults, then the alternative. The example and relationship-type list add length but each earns its place; only minor redundancy with schema-documented defaults.

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 fully describes the return format, and it covers defaults, valid values, and the sibling alternative. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description goes further by spelling out default and range for depth, the enum semantics of direction (out/in/both default), relTypes omission behavior, and a concrete example call. This meaningfully clarifies how the parameters interact.

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 ('Traverse stored memory relationships breadth-first') and describes the exact output form (indented text tree of IDs, titles, confidences, depths, edges). It also distinguishes itself from the sibling gnosys_trace by scoping that tool to relationship creation.

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

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

Explicitly routes relationship-creation use cases to gnosys_trace, which is a clear when-not/alternative clause. However, it does not distinguish itself from other retrieval siblings like gnosys_recall or gnosys_hybrid_search.

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 destructive/openWorld/idempotent annotations: it discloses that hard deletion is impossible here by design, that links reject cycles, that cross-scope supersession requires allowCrossScope=true, and that superseded_by="" unlinks a predecessor. These are non-obvious behavioral constraints an agent could not infer from annotations or schema.

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

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

Front-loads the core action, then packs archive/delete semantics, field semantics, and sibling routing into one dense paragraph. Every clause carries information, though the single-block density makes it slightly harder to scan than a bulleted or sentence-per-topic form.

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

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

For an 11-parameter mutation tool with no output schema, the description covers the return shape, the destructive-path policy, link/cross-scope constraints, and the create-vs-update boundary. Nothing an agent needs to invoke it safely appears to be 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 already 100%, so baseline is 3; the description adds real value for the trickier fields — supersedes creates predecessor links, superseded_by empty string unlinks, allowCrossScope governs cross-scope/project operations, and superseded_by maps to the CLI flag. It does not elaborate on tags/title/relevance beyond 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?

States a specific verb and resource ('Update an existing memory by ID or path') plus the return shape ('confirmation and changed fields'). It also explicitly distinguishes itself from the sibling gnosys_add_structured for creating new memories, so an agent can pick it apart from alternatives 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 routing rules: use this tool to archive/retire/'delete' via status=archived or superseded, hard deletion is human-only via the CLI, and use gnosys_add_structured for new memories. When-to-use, when-not-to-use, and the alternative are all named.

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