knowl

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

Annotations already establish readOnlyHint=true and openWorldHint=false; the description builds on this by explaining the system behavior behind the tool: the write path 'deliberately keeps [polarity pairs] side by side rather than letting either retire the other', and it discloses a limitation (REVERSAL reports are excluded). It does not conflict with the annotations and adds meaningful behavioral context beyond them.

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 main purpose is front-loaded in the first sentence, and each of the four sentences earns its place: purpose, when-to-use, when-not-to-use, and resolution path. The first sentence is somewhat dense with a nested parenthetical, but overall 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 list tool with no output schema, the description covers purpose, the two conflict kinds, usage triggers, an exclusion, and the resolution tool. The only notable gap is the lack of any hint about the output shape (e.g., what fields each listed conflict carries), which would be the description's responsibility given there is no output schema.

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

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

The tool has zero parameters (schema coverage is trivially 100%), so the 0-params baseline of 4 applies. The description correctly focuses on behavioral scope rather than inventing parameters; there is nothing in the empty schema for the description to clarify.

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

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

The description opens with a specific verb and resource: 'List contradictions among active items', and enumerates the two kinds of results (declared exclusive conflict keys and detected polarity pairs), explaining what a polarity pair is. This clearly differentiates it from siblings like knowl_query or knowl_drift, which could otherwise plausibly overlap.

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?

Two concrete trigger conditions are given explicitly: 'when a write reports an overlapping item left active, or when memory gives contradictory answers.' It also names an explicit when-not case ('A write that reports a possible REVERSAL is telling you something this command does not list -- act on it there') and identifies the alternative for resolution ('Resolve with knowl_update, never by storing a third item').

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering safety. The description adds meaningful behavioral context beyond that: it 'spreads across categories to fill the budget rather than ranking for one subject' and is 'deliberately broader and less precise.' This explains the tool's selection strategy, which is valuable and not inferable from the schema. It doesn't describe the return format, but that's a minor gap given the read-only 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?

Two sentences with zero redundancy. The core purpose is front-loaded, then usage constraints, then the alternative with its rationale. Every clause earns its place, and the structure is ideal for an agent scanning descriptions quickly.

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

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

Given the tool's moderate complexity, the description is complete enough. It explains what the tool does, when to use it, and how it differs from the key sibling. There is no output schema, but the description implies the output is a context pack sized to the budget. Minor missing details like the exact composition of the pack or how 'diversified' is enforced are not critical for invocation.

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

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

Schema description coverage is 100%, so each parameter (tokenBudget, task, query, explain) is already documented in the schema. The description adds some context about the query parameter ('steers selection') and the overall behavior, but it doesn't provide parameter-specific syntax or additional constraints beyond what the schema states. The baseline 3 applies; the description adds marginal but not essential value.

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

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

The description clearly states the tool's purpose: filling an explicit token budget with diversified project context. It names a specific verb ('fill') and resource ('token budget with project context'), and explicitly differentiates from the sibling knowl_query by contrasting its behavior ('spreads across categories' vs 'ranking for one subject'). This makes it unmistakable what this tool does and how it differs.

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?

Usage is precisely scoped: 'Use only when you have a budget to fill -- briefing a subagent, or packing a fixed-size prompt.' It also gives an explicit alternative: 'For a specific question use knowl_query instead.' This is a textbook example of when/when-not guidance, leaving no ambiguity for an agent.

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 only annotation is openWorldHint=false, so the description carries the behavioral burden. It discloses important side effects: superseded decisions are retired in the same write but remain queryable, no Knowl AI configuration is required, and the result reports any conflicting active decision plus the exact call to retire it. It does not cover every possible side effect, but the key write behavior is transparent.

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

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

The description is dense but purposeful, front-loading the core purpose and distinguishing sibling behavior before moving to constraints and supersede semantics. Each sentence carries information; only the 'Needs no Knowl AI configuration' sentence is somewhat peripheral, but it is short and relevant to adoption. 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?

For a 7-parameter tool with no output schema and minimal annotations, the description covers the essential decision-making context: what to record, when to use it, when not to, how supersedes behaves, and what the result will report about lingering conflicts. The full return shape is not specified, but the description gives agents enough to call it correctly and interpret the key output.

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 cross-parameter meaning beyond the schema: it explains that reasoning is the point (required here, optional in knowl_store), that alternatives capture what was rejected, and that supersedes links the write to retiring an earlier decision. This is meaningful semantic value, not schema repetition.

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

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

The description opens with a specific verb and resource: 'Record a confirmed project decision,' and enumerates the content (what was chosen, why, and what was rejected). It explicitly distinguishes this tool from knowl_store by naming when each is appropriate, so an agent can tell them apart without inspecting 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 guidance: use knowl_decide rather than knowl_store when reasoning and alternatives are the point, and record only settled decisions, not options under discussion. It also provides conditional guidance for the supersedes parameter, instructing the agent to retire replaced decisions rather than leave contradictions.

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 are minimal (title and openWorldHint only), so the description carries the full behavioral burden, and it delivers: the intentional edited-file exclusion with the signal-to-noise rationale, empty-result semantics, preview-by-default vs. apply-flagging behavior that persists to the next session, and the git repository/base-ref prerequisite. No contradiction with annotations.

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

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

Five sentences, each earning its place: what it reports, when to use it, the deliberate exclusion with rationale, apply behavior, and the repository prerequisite. The core purpose is front-loaded before caveats, 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 2-parameter tool with no output schema, the description covers detection scope, negative-result semantics, default vs. mutating behavior, and environmental prerequisites. An agent has everything needed to select and invoke the tool correctly without relying on the schema.

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 adds value beyond the schema by clarifying that preview is the default path and that `apply` marks matches so the next session sees them flagged rather than trusting them — persistence semantics 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?

The description opens with a precise statement of what the tool reports — atoms whose cited files the diff deleted or moved, plus symbol evidence that no longer resolves — giving a specific verb, resource, and detection mechanism. It differentiates from siblings like knowl_query or knowl_evidence_list by naming the exact invalidation signal it detects and what it deliberately excludes.

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 usage contexts are given: before opening a pull request, before knowl_task_finish on code-touching work, and when asked what a change breaks. It also provides a when-not-to-use signal by stating that edited files are deliberately not reported, and clarifies the empty-result meaning to prevent misreading.

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

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

Annotations already declare readOnlyHint=true, so the agent knows it is a safe read operation. The description adds the strategic context but does not disclose other behavioral traits (e.g., output format, ordering, or whether it returns all evidence or a subset). Given the annotations cover the key safety aspect, a 3 is appropriate; the description adds marginal value beyond the purpose.

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, no fluff. The core function is stated first, followed by a concise use-case rationale. Every word earns its place, and the description is front-loaded with the action.

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

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

For a simple read-only tool with two parameters and no output schema, the description is sufficient. It tells the agent what it does and when to use it. The only missing element is a hint about the output shape, but with no output schema and a straightforward 'list' operation, that is not a critical 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 description coverage is 100%: both 'repo' and 'itemId' have descriptive text. The 'repo' parameter description is unusually detailed, explaining the cross-repo semantics. The tool description does not add any parameter-level information, so it relies on the schema. Baseline 3 is correct.

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

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

The description states a specific action ('List the evidence linked to one knowledge item') and clearly identifies the resource. It distinguishes itself from siblings like knowl_recent or knowl_query by focusing on evidence for a single item, and even provides a motivational context (low-confidence, contested, old items).

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

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

The description gives explicit when-to-use guidance: 'Use before relying on an item that is low-confidence, contested, or old enough that its support matters more than its claim.' It does not mention alternatives or exclusions, but the scenario is clear enough for an agent to decide when to invoke this tool.

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 reveals the key behavioral trait that feedback is append-only, which is not visible from the annotations or schema. This adds meaningful transparency beyond the structured metadata, though it could go further in describing response behavior or effect on other entries.

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?

A single, tightly worded sentence that front-loads the core action ('Record append-only usefulness feedback') and immediately follows with the usage constraint. No filler or redundant phrasing exists.

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

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

For a simple boolean feedback tool with no output schema, the description covers the purpose, the mutation behavior, and the triggering condition. It could mention what happens if called with contradictory flags, but that is a minor gap given the schema's clarity.

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 does add a useful semantic tie between the boolean parameters and real-world conditions ('used, rejected, or caused a correction'), but it doesn't redefine or clarify individual parameters beyond what the schema already states.

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

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

The description uses a specific verb-resource pair, 'Record append-only usefulness feedback', and adds an explicit condition about when it is allowed. This clearly differentiates it from sibling tools like knowl_store or knowl_evidence_list without needing further context.

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?

'Only after a retrieved item was actually used, rejected, or caused a correction' provides a clear timing trigger for the tool. It doesn't name alternative tools, but the conditional guidance is strong enough to prevent premature or arbitrary calls.

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 mark readOnlyHint=true, and the description adds useful behavioral context: it covers live sessions on this machine, what each session is doing, and whether it can be messaged. It also clarifies the distinction between direct messaging and waiting for idle, which goes beyond the bare 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?

The description is dense but efficient: the first sentence defines what the tool returns, the second gives concrete use cases, and the third explains how to act on the results. It is front-loaded and every sentence earns its place, though the first sentence is a long fragment.

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

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

For a read-only tool with one optional parameter and no output schema, the description fully covers what is returned, when to use it, and how to interpret results. Nothing needed for correct invocation is missing.

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

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

The schema fully documents the single optional inRepo parameter, including what it filters and that omitting it returns every session. The description does not mention this parameter, but with 100% schema coverage the structured data already carries the meaning.

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

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

The description clearly identifies the resource (other live agent sessions on this machine) and the information returned (working on, files editing, problem claimed, messageable). It lacks an explicit verb like 'list' or 'get', but the title and phrasing make the purpose unmistakable and distinguish it from sibling tools like knowl_state.

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

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

The description gives explicit when-to-use scenarios: before fixing a possibly shared error, before changing hooks/config/migrations/install, or when the user asks who else is running. It also provides follow-up guidance: messageable sessions can be reached via SendMessage, while others should be raised with the user.

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 annotations already flag destructiveHint=true, and the description builds on this by disclosing that purge is the one action with no undo and that deletion only occurs for approved, still-valid candidate ids. This adds meaningful safety context beyond the structured annotation and explains the conditional nature of destructive behavior.

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 dense sentences with no filler, and the critical precondition (preview + approval) is front-loaded. Every sentence earns its place by either stating the gating condition or explaining the destructive/archive semantics.

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 tool with one optional parameter, destructive annotations, and no output schema, the description covers everything an agent needs to invoke it safely: when to call it, what can be destroyed, what cannot be undone, and how the parameter controls the destructive path. The sibling-list context is also sufficient because the description names the relevant predecessor, knowl_gc_preview.

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 parameter description already explains the preview-origin and still-candidate rule. The tool description adds extra value by emphasizing the no-undo consequence of naming purgeItemIds and clarifying that archive and compress still run when the parameter is omitted, which reinforces the parameter's optional role.

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

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

The description states a specific action, 'Apply knowledge garbage collection', and clearly distinguishes it from the required sibling 'knowl_gc_preview' by making the preview a precondition. It also names the concrete effects (purge, archive, compress), so an agent can tell what this tool does without opening the schema.

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

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

The description explicitly states when to use the tool: only after knowl_gc_preview and explicit user approval. It also gives actionable guidance on the optional parameter, explaining that omitting purgeItemIds still runs archive and compress, which prevents an agent from assuming the call is a no-op without it.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'without changing the database.' It also discloses a subtle behavioral trait: the returned purgeItemIds are the IDs that knowl_gc_apply will not delete unless they are handed back. This adds real context beyond the annotation and is important 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 two tight sentences with no filler. The core purpose is front-loaded, the usage scenario follows, and the return-value caveat is placed at the end. Every sentence earns its place.

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

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

For a zero-parameter, no-output-schema tool, the description is complete: it explains what the tool does, why an agent would use it, that it is non-destructive, and what the single return field means. The reference to knowl_gc_apply's behavior also fills a critical operational 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?

The tool has zero parameters, and the schema description coverage is 100%, so there is no parameter information missing. The description adds no parameter-specific meaning, but none is needed. The baseline of 4 for zero-parameter tools 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: 'Preview knowledge garbage collection recommendations' without changing the database. It also distinguishes itself from knowl_gc_apply by explaining that the returned IDs are the ones knowl_gc_apply 'will not delete unless they are handed back to it.' The purpose is unambiguous.

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 to find duplicate, stale, or cold memory before applying GC,' which gives a clear when-to-use context. It references knowl_gc_apply as the follow-up action, though it does not spell out an explicit 'when not to use' or compare against non-GC sibling tools.

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 key behavior beyond the thin annotations (title and openWorldHint only): 'Delivered once, then archived - this is a pass, not a durable note.' This tells the agent the call has a one-shot side effect and gets archived, which materially affects tool choice. It falls short of a 5 because it doesn't say what archiving entails or what response or confirmation follows.

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 short sentences with zero waste: purpose first, then lifecycle disclosure, then sibling routing. Every sentence earns its place, and the most decision-relevant fact (one-shot, archived) 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?

For a 7-parameter tool with no output schema, the description plus a fully-covered schema gives an agent the essentials: what it does, that it is transient, and where durable content belongs. The main gaps are the unacknowledged overlap with knowl_park and unspecified return behavior, which are minor for a pass-along tool.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The tool description adds no parameter-level meaning beyond the schema, which meets the baseline of 3 but does not elevate it.

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

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

The description states a specific action (parking the current workstream so the next session picks it up) with a clear resource and purpose, and distinguishes itself from knowl_store by framing handoff as a one-shot pass rather than a durable note. However, the very verb it uses, 'park,' collides with the sibling tool knowl_park, and the description never explains the difference, so it doesn't fully stand apart from all siblings.

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

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

The description gives an explicit routing rule: 'Store anything worth keeping with knowl_store,' implying this tool is for transient pass-along only. That is a clear context signal, but it doesn't address closely related siblings such as knowl_park, knowl_resume, or knowl_session_finish, leaving the when-not-to-use story incomplete.

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 include openWorldHint=true, which says nothing about side effects or safety. The description says 'process' and 'ingest' but doesn't disclose whether this mutates the knowledge base, whether it's reversible, or what happens to existing knowledge. It also doesn't mention the autoResolve behavior that could change knowledge. Given the low annotation coverage, the description should carry more behavioral detail but doesn't.

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 two sentences, front-loaded with the core purpose and a critical usage caveat. Every word earns its place; there is no fluff or repetition. It is concise and immediately actionable.

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 and minimal annotations, the description should clarify what the tool returns and any side effects. It doesn't mention the return value (e.g., a commit ID or status), nor does it explain how it differs from knowl_ingest_atoms. The tool likely has side effects (ingesting knowledge), so more context about consequences and the resulting state would be needed for an agent to call it confidently.

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 parameters are documented in the schema. The description adds a bit of context by saying 'explicitly supplied raw source text,' which clarifies that text should be raw and explicitly given, and it implies the text param is the main input. It doesn't add meaning for autoResolve or commitMessage beyond what the schema says, so baseline 3 is appropriate.

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

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

The description states a clear purpose: 'Process explicitly supplied raw source text through the configured Knowl AI pipeline.' It specifies the resource (raw source text) and the action (process through pipeline). It doesn't name a specific sibling but distinguishes the explicit-ingestion scope, which is enough to differentiate from related tools like knowl_ingest_atoms, though that distinction is implied rather than stated.

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 strong usage rule: 'Use only for an explicit ingestion request; never silently ingest the current conversation or prompt.' This tells the agent when to call it and when not to. It doesn't compare with alternatives like knowl_ingest_atoms, but the explicit request condition is a clear guideline that covers most usage decisions.

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 provide only openWorldHint=false, so the description carries nearly the full burden of behavioral disclosure. It does so well: it reveals this is a write operation, discloses that superseded items are 'retired in the same write,' and describes the result shape ('reports each atom individually, including any overlapping item left active and the exact call to retire it'). It falls short only of disclosing idempotency, partial-failure behavior, or concurrency semantics.

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

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

The description is dense but every sentence earns its place: core purpose, content exclusions, timing, routing preference, supersedes workflow, and result reporting. The supersedes sentence is somewhat long and could be tightened, but there is no redundancy or filler.

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

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

For a write tool with 3 parameters and a heavily documented atoms schema, the description covers the operational essentials: what to store, when to ingest, the correction/retirement workflow, and the high-level result shape. The exact result structure is described only vaguely and the 50-item batch limit is left to the schema, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining when and why to set supersedes ('so it is retired in the same write; never leave two active items asserting different values for the same thing') — conditional usage guidance the schema's field-level description does not convey. This lifts it 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 opening sentence states a specific verb and resource: 'Store pre-extracted structured knowledge atoms from an MCP client.' It further clarifies scope by listing the accepted categories (facts, decisions, constraints, architecture, state, skills) and explicitly excluding raw chat transcripts. The claim 'This is the preferred MCP ingestion path' differentiates it from the sibling knowl_ingest and knowl_store without needing to open their 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?

The description gives explicit content rules ('Do not store raw chat transcripts; extract durable facts...') and timing guidance ('during execution or after each completed subtask'). It also instructs when to set supersedes for corrections. However, it does not name alternative tools or state conditions under which another tool should be chosen instead, so the guidance is strong on content but weaker on explicit exclusion.

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 establish non-destructive behavior, and the description adds meaningful behavioral context beyond them: it mints a short key, returns a hand-off line, is not consumed on resume, and works from any directory across sessions. It does not elaborate on persistence mechanics, but the disclosed traits are genuinely useful and not redundant with annotations.

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

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

The description is three tightly packed sentences: the first states purpose, the second states the essential behavioral outcome, and the third differentiates the tool from its closest sibling. Every sentence earns its place 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?

The description covers the key context needed to call this tool confidently: what it does, what it returns, and how it differs from knowl_handoff. The schema covers all parameters. Since there is no output schema, a little more detail about the exact shape of the returned line could improve completeness, but the current description is already sufficient 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?

All 7 parameters are fully documented in the schema, so the description does not need to repeat them. The description adds no parameter-level detail beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Park a workstream the user means to return to.' It also explains the core behavior of minting a short key and returning a verbatim line, and explicitly contrasts itself with knowl_handoff, making the tool's purpose unambiguous even among many siblings.

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

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

The description states when the tool is appropriate ('a workstream the user means to return to') and explicitly names the alternative knowl_handoff, explaining the key distinction: this tool is 'not consumed by resuming' and works 'from any directory, any number of sessions later.' This gives an agent clear selection criteria.

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 provide readOnlyHint=true, and the description adds substantial behavioral context beyond that: content truncation at 2000 characters, the meaning of affectedPaths, the score vs cosine distinction, uncalibrated score behavior, workspace foreign-item semantics, and the strong provenance warning that stored bodies are data, not instructions. No contradiction with annotations.

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

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

The description is long, but almost every sentence earns its place given the tool's complexity and the absence of an output schema. It is front-loaded with the most important guidance. Some sentences are dense and could be tightened, but there is no filler or repetition of schema content.

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 tool with no output schema, this description is exceptionally complete. It covers result semantics, truncation behavior, file-inspection decision rules, rerun behavior, workspace repo behavior, and prompt-injection risk. An agent has enough information to call the tool correctly and interpret its results without additional context.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains how to construct the query parameter ('use every word that names the subject...'), how to read truncated content via id, and how to interpret the numeric results that accompany a query. This meaningfully exceeds schema-only guidance.

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 frames the tool as the first-line retrieval mechanism for specific project questions against Knowl, and the skip list distinguishes it from lifecycle-context tools. However, it never states the core operation in a direct verb phrase such as 'retrieves knowledge items matching a query' — the behavior is strongly implied rather than stated.

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?

This is exemplary. It says when to use the tool first, when to skip it, when to inspect files instead, and when to rerun with different words. It names a specific sibling (knowl_task_start) and gives concrete exclusion conditions, leaving almost no decision 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 readOnlyHint=true and openWorldHint=false, so the safety profile is already established. The description adds that the return is compact and the tool is a fallback/refresh path, which is useful but not extensive. No side effects or additional behavioral caveats are disclosed, which is acceptable given the read-only 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?

The description is a single sentence that front-loads the core action and immediately provides usage conditions. There is no wasted text and the key advice about when to use the tool appears prominently.

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 covers what the tool returns and when it should be invoked, and the schema covers all parameters. The lack of an output schema is a minor gap, but the trigger conditions and compactness make this sufficient for most selection and invocation decisions.

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

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

The input schema fully documents all three parameters with descriptions and constraints, so the description does not need to add per-parameter detail. 'Compact recent session context' gives general intent but contributes little 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 names a specific action and resource: 'Get compact recent session context', and adds a scoping condition. It does not explicitly distinguish itself from sibling tools such as knowl_context or knowl_state, so it is clear but not fully differentiated.

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

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

The description gives explicit usage criteria: use it only when 'lifecycle bootstrap is unavailable (including manual mode)' or when an 'explicit refresh is needed'. It does not name alternative tools directly, but the when-to-use guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, and the description does not contradict that—'resume' is ambiguous but likely means retrieving context. The description adds the behavior that with no key it lists parked items, which is useful. However, it does not clarify what 'resume' returns or what side effects (if any) occur, leaving some ambiguity.

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 the main action front-loaded, then the trigger condition, then the fallback. Every word earns its place; no redundancy or filler.

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

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

For a tool with one optional parameter and no output schema, the description covers the two modes of operation and the triggering condition. It does not describe the return format, but the low complexity and read-only annotation make this a minor gap. Overall it is sufficiently complete.

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

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

Schema coverage is 100% and the parameter is simple. The description adds meaning by explaining the key's role: it is optional, and its presence switches the tool from listing to resuming. This goes beyond the schema's generic 'The key the user pasted' by linking it to the tool's dual behavior.

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: "Resume a parked workstream from its key." It also distinguishes the no-key behavior (listing parked workstreams), which separates it from siblings like knowl_park or knowl_recent. The purpose is immediately clear and unambiguous.

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

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

It provides an explicit trigger: "Call this as soon as a user supplies something that looks like a resume key." It also covers the fallback case: "With no key, lists what is parked." However, it does not name alternative tools or state when not to use it, so it falls short of a full 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 provide only openWorldHint=false, so the description carries most of the behavioral burden. It discloses the potentially harmful consequence of finishing a hook-owned session and clarifies that 'failed' status still records learning via the schema. It does not describe output behavior, but that is less critical here.

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 no filler. The key scoping condition ('you explicitly own') is front-loaded, and the warning about hook-owned sessions is placed exactly where it adds value.

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 tool with four well-described parameters and no output schema, the description covers the essential contextual distinction: manual ownership vs hook ownership. It could mention the effect of 'promote' more explicitly, but the schema already documents that parameter.

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 each parameter already has a clear description. The tool description adds context around 'own' and 'promote', but it does not add meaningful semantics beyond the schema, so baseline 3 is appropriate.

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

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

Description states a specific verb ('Finish') and resource ('manual memory session you explicitly own') and further clarifies the optional 'promote' behavior. It also distinguishes this tool from hook-owned session handling, making it easy to differentiate from sibling 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?

It gives explicit when-to-use guidance: manual sessions you own. It also clearly says when not to use it (hook-owned sessions), explaining that lifecycle hooks finalize themselves. No explicit alternative tool is named, but the exclusion is unambiguous and actionable.

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 are minimal (only openWorldHint: false), so the description must carry the behavioral disclosure burden. It mentions 'create and index a file-backed skill', which implies mutation and file creation, but it does not disclose potential side effects such as overwriting existing skills, failure conditions, or any permission requirements. The description is too sparse to adequately inform the agent about the tool's behavioral traits beyond the basic create action.

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 a single sentence that is both concise and front-loaded with the core purpose and usage condition. There is no fluff or redundant information; it earns its place by immediately conveying the tool's function and when to use it.

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

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

Given the tool's complexity (6 parameters, nested objects like files and entrypoints) and the absence of an output schema, the description is relatively short and does not cover important contextual aspects such as return values, success criteria, or how this tool relates to siblings like knowl_update. While the schema is very detailed, the description leaves gaps around operational context that an agent would benefit from.

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%, meaning all six parameters are already fully documented in the input schema. The description adds no additional meaning about parameters, so it relies on the schema. Per the rubric, a baseline of 3 is appropriate when schema coverage is high and the description does not add extra semantic value.

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

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

The description clearly states a specific action: 'Create and index a learned file-backed skill'. It also includes a conditional clause ('only when the user explicitly requested a reusable workflow to be codified') that distinguishes its use from general-purpose tools. This makes the purpose unambiguous and differentiates it from siblings like knowl_skill_list or knowl_skill_run.

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 provides an explicit condition for when to use the tool: 'only when the user explicitly requested a reusable workflow to be codified'. This is a clear 'when' and implies a 'when-not' (don't use otherwise). However, it does not name any alternative tools (e.g., knowl_update for modifying existing skills), so it lacks explicit alternatives, which would make it 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 mark readOnlyHint=true, and the description adds useful context beyond that: the on-disk source (`.knowl/skills`), the reduced payload ('name and purpose only'), and the bridge/persistence rationale. No contradictions or hidden side effects are present.

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 no filler: the first states the operation and scope, the second explains the rationale and points to the sibling for more detail. The key information 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?

For a zero-parameter, read-only listing with annotations, the description is complete: source, payload scope, purpose, and differentiation from knowl_skill_read are all present. Even without an output schema, it states what the result contains (name and purpose).

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

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

There are zero parameters, so the schema leaves nothing ambiguous and the description confirms this is a parameterless listing. This matches the 0-parameter baseline of 4; no parameter documentation is missing.

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 ('List'), a specific resource ('learned file-backed skills from `.knowl/skills`'), and an explicit scope ('name and purpose only'). It is clearly distinguishable from the sibling knowl_skill_read, which is pointed to for reading manifest details.

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 context for when this is useful ('stable MCP bridge so old sessions can discover newly created skills') and names the alternative for deeper reading ('read one with knowl_skill_read for its manifest and instructions'). This clearly routes an agent to the correct sibling.

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 annotations already declare readOnlyHint=true, and the description aligns with that by describing a read-only operation. It adds useful behavioral context beyond annotations by specifying the exact filesystem location and the files the operation covers, which helps the agent predict the tool's scope and output without 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 sentences with no filler: the first states what the tool does, and the second explains when and why to use it. The core action and resource are front-loaded, and 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?

For a simple single-parameter read tool with readOnlyHint=true and no output schema, the description is complete: it names the path, the files read, and the intended usage sequence. No additional information is necessary for an agent to select and invoke this tool 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%, and the parameter is already described as 'Skill package name.' The description adds mild value by mapping `name` to the `<name>` path segment in `.knowl/skills/<name>/`, but it does not substantially extend the schema's own documentation.

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

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

The description states a specific action ('Read'), a concrete resource (`.knowl/skills/<name>/`), and the exact contents included ('skill.json' and 'SKILL.md'). It also clearly differentiates this from knowl_skill_run and knowl_skill_list by framing it as reading a skill package rather than listing or executing 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?

The description gives explicit usage guidance: read a skill before running it. It names the related tool knowl_skill_run and explains why this ordering matters ('executes an entrypoint you have seen rather than one you guessed at'), providing both a when and a rationale.

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 openWorldHint and destructiveHint, so the bar is lower. The description adds valuable behavioral context beyond them: edits to the package revoke approval, autoRun is not the default, and refusals must be surfaced to the user rather than bypassed. It does not contradict 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?

Four sentences, each earning its place: purpose, approval requirement, autoRun condition, and refusal handling. The core verb+resource is front-loaded in the first sentence, 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 code-executing tool with destructiveHint/openWorldHint and no output schema, the description covers the critical decision flow (approval, autoRun, refusal behavior) thoroughly. The only gap is the success return value, since no output schema exists to document 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%, so the schema fully documents name, args, and entrypoint — including the script-vs-shell distinction for args. The description adds no param-level detail, 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 first sentence states a specific verb and resource: 'Run an approved learned-skill entrypoint.' This clearly differentiates the tool from its siblings (knowl_skill_list, knowl_skill_read, knowl_skill_create) as the execution tool, and adds the distinguishing constraint that only approved skills with autoRun: true execute.

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

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

The description explicitly states the preconditions for use — prior user approval via `knowl skill approve <name>` and author-set autoRun: true — and the when-not path: if refused, relay the approval command instead of attempting a workaround. This gives an agent an unambiguous decision procedure.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds the scope distinction (broad vs specific) and implies a comprehensive snapshot, which is useful behavioral context. It does not detail output structure or potential cost, but with annotations covering the main trait, this is adequate.

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 a single, focused sentence that front-loads the main purpose and then gives usage guidance. No wasted words, and the alternative is mentioned efficiently.

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

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

For a simple read-only tool with one optional parameter and annotations covering safety, the description fully covers what an agent needs: what it does, when to use it, and how it differs from the main sibling. The output format is implied by the parameter description (markdown). Nothing essential 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 sole parameter maxChars is fully described in the schema (max, min, default, and meaning), achieving 100% schema coverage. The description adds no extra parameter context, 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 clearly states the tool gets the full current active state of the project, and explicitly contrasts it with knowl_query for specific factual questions. The title 'Whole-project memory overview' reinforces the purpose, making it unambiguous and distinct from siblings.

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

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

The description explicitly says to use it for broad summaries, status checks, or full-state requests, and directs to prefer knowl_query for specific facts. This gives clear when-to-use and when-not-to-use guidance, naming the 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?

Beyond the minimal annotation (openWorldHint: false), the description discloses determinism, no config requirement, supersedes retiring the old item in one write, and the result reporting any still-active item with the exact retiring call. It doesn't cover content-length limits or auto-supersede behavior, though those live in the 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?

Five dense, purposeful sentences, front-loaded with the verb-object purpose and then usage timing, behavioral guarantees, the supersedes rule, and result expectations. 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 19-param write tool with no output schema, the description supplies essential orientation and the key output behavior (left-active items plus retire call). Remaining parameter nuance is covered by the 100% schema descriptions.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a 4 by giving actionable meaning to `supersedes` — when to pass it, what it does ('retired in one write'), and the rule against leaving two active conflicting items. No other params need further semantic help given the rich 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 names the specific action ('Store one concise structured knowledge atom directly') and explicitly excludes raw chat transcripts, making the purpose unmistakable. It doesn't name a sibling tool, but the contrast with transcript ingestion is enough to orient an agent.

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 timing ('immediately after discovering durable project knowledge or completing each subtask, not only at the end') and notes determinism and no-config operation. It stops short of naming alternatives like knowl_ingest_atoms, leaving the when-not-to-use largely 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 only carry openWorldHint:false, so the description carries the behavioural burden. It discloses determinism, evidence-backed nature, and the automatic-execution constraint, which adds value. However, it does not explain what 'refresh' entails (e.g., whether it overwrites existing understanding) or any side effects. This is moderate coverage.

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 filler. The purpose is front-loaded, followed by clear usage exclusions. 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?

For a single-parameter tool with no output schema and minimal annotations, the description adequately covers when to use, what it does, and key behavioural constraints. It could mention expected output or result format, but that is not critical for a synthesis operation where the agent likely just calls it. Overall it is complete enough.

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 description covers the single parameter fully (subject to synthesise, example, one scope per call). The tool description adds no extra meaning about the parameter beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific action (create or refresh) on a specific resource (evidence-backed project understanding). It clearly distinguishes itself from siblings by explicitly ruling out background tidy-up and session summarisation, so an agent can tell it apart from other knowl 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?

It gives explicit usage conditions: only for scopes the user explicitly asked to synthesise, never as background tidy-up, never to summarise a session, and never runs automatically on normal writes. This is direct and unambiguous, though it does not name specific alternative tools.

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 openWorldHint=false and destructiveHint=false, so the description carries most behavioral burden. It states the action is a 'checkpoint' but does not disclose that this persists a snapshot for later resume, whether it can overwrite prior checkpoints, or that it does not finish the task. This is a significant gap for a state-mutating tool in a manual work loop.

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 no filler; the first sentence states the action and scope, and the second sentence adds a sharp exclusion. Every word earns its place, and the restriction is front-loaded rather than buried.

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 tool with 8 parameters, no output schema, and sparse annotations, the description gives the essential usage context but leaves lifecycle details (relationship to knowl_task_finish/knowl_resume, what happens on repeated checkpoints, response shape) to be inferred from the schema and sibling names. Adequate but not fully 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 all eight parameters already have meaningful descriptions. The tool description adds that taskId comes from knowl_task_start and frames summary as progress/blocker, which is helpful but not extensive. Baseline 3 fits because the schema does the heavy lifting.

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 identifies a specific action ('Checkpoint meaningful progress or a blocker') on a task resource scoped to a 'manual work loop' and explicitly ties it to the taskId from knowl_task_start. It does not explicitly contrast with knowl_task_finish, but the 'progress or blocker' framing prevents confusion with task completion.

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

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

It explicitly states when to use the tool (manual work loop) and when not to use it ('Never use for a hook-owned session or routine command noise'). It does not name an alternative tool, so it stops short of the full five-level criterion, but the exclusions are clear and actionable.

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?

With only openWorldHint=false in annotations, the description carries the behavioral burden. It discloses that the tool should be used exactly once and only for manual loops, which is useful, but it does not describe what happens on repeat calls, side effects, or the nature of the completion beyond 'summary.' Some behavior is revealed, but not deeply.

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 carry the essential scope, timing, and exclusion with no filler. The primary constraint is front-loaded ('exactly once after verification'), and the critical safety exclusion follows immediately.

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

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

For a simple two-parameter tool with fully described parameters, the description provides the needed usage context and constraints. It lacks any mention of return values or post-finish behavior, but the absence of an output schema and the minimal parameter surface make this a minor gap rather than a blocking one.

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 reinforces that taskId comes from knowl_task_start, but adds no new meaning beyond the schema's own parameter descriptions. It does not need to compensate for coverage gaps.

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 ('Finish'), a precise resource ('one manual work loop'), and a key constraint ('exactly once after verification'). It ties directly to the taskId from knowl_task_start and explicitly distinguishes itself from hook-owned sessions, helping an agent tell it apart from knowl_task_checkpoint and knowl_session_finish.

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

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

The description gives clear timing guidance ('after verification'), the source of the required identifier, and an explicit exclusion ('Never use for a hook-owned session'). It does not name alternative tools for intermediate checkpoints or session-level finishing, but the conditions are specific enough for correct routing.

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 openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that the tool 'Returns relevant memory and a taskId', which is useful behavioral context beyond the annotations. However, it doesn't disclose side effects like whether a session is created, whether the loop persists, or what happens on repeated calls. With annotations covering the main safety traits, a 3 is appropriate.

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. The core action and return value are front-loaded, and the exclusion ('Never use for a hook-owned session') is placed at the end as a sharp warning. Every sentence earns its place.

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

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

For a 2-parameter tool with 100% schema coverage and annotations covering the safety profile, the description is nearly complete. It states the return value (memory + taskId) and the key usage constraint. The only gap is that it doesn't explain what a 'manual work loop' is or how it relates to the sibling lifecycle tools, but that's a minor omission given the schema and annotations.

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 both parameters. The description adds a small semantic detail: 'query' defaults to the task title, which is not in the schema. That is a genuine addition, but it's minor. Baseline 3 is correct when the schema does the heavy lifting.

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 ('Start') and resource ('one manual work loop') and adds a clear qualifier: for multi-command or resumable work when verified lifecycle hooks are unavailable. It distinguishes itself from hook-owned sessions, though it doesn't name a specific sibling alternative. The phrase 'manual work loop' is somewhat jargon-heavy but the core purpose is clear.

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

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

The description gives an explicit condition for use ('when verified lifecycle hooks are unavailable') and a strong exclusion ('Never use for a hook-owned session'). It doesn't name alternative sibling tools explicitly, but the when/when-not guidance is clear enough for an agent to route correctly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds useful context about the immutable nature of the history and what the response contains ('what it claimed, when, and what superseded it'), which goes beyond the structured 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 sentences with zero waste. The core purpose is front-loaded first, and the usage guidance comes in the second sentence. Every word 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?

The tool is a simple read operation with no output schema, and the description explains what will be returned and when to use it. The only minor omission is behavior for edge cases like a missing item, but this is not critical given the tool's simplicity and annotations.

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 fully documents both repo and itemId. The description implies itemId through 'one item' but adds no new syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Read one item's immutable assertion history...' and explicitly differentiates from knowl_query by contrasting 'what it says now' vs 'how it got there.' This clearly distinguishes it from siblings.

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

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

It gives explicit conditions: 'Use when memory looks contradictory or you need to know whether a fact changed,' and names the alternative (knowl_query) with a clear delineation of when each is appropriate. This is exactly the kind of when/when-not guidance expected.

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 annotations already carry destructiveHint=true and openWorldHint=false, so the description only needs to add context; it does so by explaining that updates can retire another item through supersedeId and by clarifying the NEW vs OUTDATED id relationship. It does not contradict the annotations and gives enough behavioral color to support safe 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?

Three sentences: one purpose statement, one usage trigger, one special-case recipe. It is front-loaded and contains 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 destructive multi-parameter update tool with no output schema, the description plus rich per-parameter schema descriptions cover the main use and the tricky supersede case. It could add a note about what happens on success or permissions, but the agent has enough 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 description coverage is 100%, so the baseline is 3, but the description adds extra meaning by mapping id to the NEW item and supersedeId to the OUTDATED item, which is the trickiest parameter relationship in this tool. Most other parameters remain adequately explained by 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 opens with a specific verb and resource ('Update the metadata, status, or content of an existing knowledge item') and clearly differentiates itself from the duplicate-adding path by saying it should be used instead of adding duplicates. The retire/supersede explanation further defines a distinct responsibility.

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

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

It gives an explicit trigger ('when execution reveals stale or contradicted memory'), an explicit when-not ('instead of adding duplicates'), and a concrete recipe for the retire case with correct id/supersedeId roles. This is actionable usage guidance beyond a generic intent statement.

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