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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that the behavior is an alias with a fixed sectionType and that the tool is deprecated, giving loosely beyond the annotations but not much behavioral depth.

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 filler: the first defines the shorthand relationship, the second states deprecation and a removal version. Information is front-loaded and every phrase carries intent.

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 sole input is a simple ids array and the annotation provides a clear safety profile, so the structure is basic. However, the description does not say what ids must identify or what the response is acObContents.

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 shows a required 'ids' array but has zero parameter descriptions. The description does not explain what 'ids' should be, leaving the agent to infer they are content IDs from the 'shorthand for content' phrase.

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 that this tool is a 'Shorthand for content with sectionType: agent', which identifies the target resource and the fixed scope. It does not use an explicit verb like 'retrieve' or 'list', but the shorthand relationship to the base content tool gives enough purpose.

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 deprecation notice conveys that this tool should not be used for new work and that removal is scheduled in 2.0.0. It implies the base 'content' operation is the lower-level alternative, but it does not explicitly name the replacement tool or state 'use content with sectionType: agent instead'.

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 communicate idempotence, non-destructiveness, and a closed world, so the bar is lower. The description adds that this is a thin wrapper that forwards to learn with a fixed sectionType, and it discloses the deprecation lifecycle, which annotations do not. However, it does not explain what the learn operation actually does with the content, such as storage, merging, overlap, or response 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?

The description is only three sentences and every sentence contributes: the shorthand relationship, the content semantics, and the deprecation. It is front-loaded with the core identity and ends with the lifecycle warning. Slight room for a usage guidance sentence, but as written there is no fluff.

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

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

The tool has no output schema, so the description should help fill what happens and what the caller receives. It does not mention the effect of learning persona text, whether content replaces or edits existing agent knowledge, what the response looks like, or how the sectionType agent maps into the learn workflow. It is only complete for a caller who already deeply understands the learn 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?

The schema has 0% semantic description coverage, so the prose must compensate for the 7 parameters. It only clarifies that content is the persona text; no other parameters (tags, type, docid, title, replace, description) are explained. It also does not clarify that sectionType is hardwired and whether a caller can override the type property.

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 the operation as 'shorthand for learn with sectionType: agent' and states that content holds the persona text, which is specific enough to say what it does and how it differs from the base learn tool. It is clear about the resource (agent/persona) and the action (learn-like behavior), though it still relies on the caller already knowing what 'learn' itself does.

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

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

The deprecation warning says 'Deprecated; removal in 2.0.0.' which is an unambiguous when-not-to-use signal. By calling itself a shorthand for learn, the alternative is implicitly available, but there is no explicit 'use learn instead' statement or discussion of when to choose this tool over related agents like agent-search or skill-learn.

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 denote readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to cover safety. It adds the deprecation status and the fact that the tool injects 'sectionType: agent' as a shorthand behavior, which is beyond what annotations convey. The description is concise and 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?

The description is one short, direct sentence followed by a deprecation notice. Every word contributes meaning, and the core alias relationship is immediately clear. There is no waste.

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?

Even though the tool is deprecated, an agent that encounters it may still need to know what the five schema parameters mean in order to use it safely. The description only provides the alias relationship and deprecation, leaving the output schema as absent and the parameter semantics unspecified. Given the complexity of the input and zero schema description coverage, the description is not 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 has five parameters with zero description coverage, and the tool description does not explain kbid, depth, kbids, format, or maxTokens. The mention of 'sectionType: agent' provides some contextual meaning about the implicit section scope, but it does not map to or explain the actual input parameters. Since schema coverage is 0%, the description has a heavy burden and only marginally compensates for 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 clearly identifies the tool as a shorthand alias for 'recall' scoped to sectionType 'agent'. It names the parent operation and the section parameter, and the 'Deprecated' notice plus the explicit reference to 'recall' distinguishes it from sibling tools. An agent can understand exactly what this tool is and how it relates to the main recall tool.

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?

'Deprecated; removal in 2.0.0' provides explicit guidance not to use this tool in production, and the statement 'Shorthand for recall with sectionType: agent' names the alternative (recall) and the difference (agent scope). This effectively tells the agent when to avoid this tool and what to use instead.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, covering the safety profile. The description adds the useful behavioral context of the deprecation lifecycle and the fixed sectionType binding, which is extra information beyond the annotations and schema. 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?

Two sentences with zero filler: the first sentence states the purpose/equivalence, the second states the deprecation. The critical scoping fact is front-loaded and 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?

For a deprecated alias, the description adequately covers deprecation and equivalence to search. However, with no output schema, 7 undocumented parameters, and no return/behavior hints, an agent would still need to consult the search tool's definition before calling this one, which limits completeness.

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 0%, so the description bears the burden of explaining the 7 parameters, but it does not. The only parameter-related insight is that sectionType is fixed to 'agent' — a detail not even visible in the schema. The required 'query' parameter and the enums (algo, mode) remain completely unexplained.

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 tool as a shorthand for the search tool scoped to sectionType: 'agent', and distinguishes it from the generic search sibling. However, it relies on the reader knowing what search does, since it never states the underlying query/return behavior itself.

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 deprecation note ('Deprecated; removal in 2.0.0') is an explicit when-not-to-use signal, and calling it a 'shorthand for search' implies the alternative route. It does not literally name 'use search instead', but the intent is unambiguous in context.

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

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

Annotations already declare `destructiveHint: true` and `idempotentHint: true`, so the safety profile is externally covered. The description adds the deprecation and alias behavior, but does not describe what unlearn actually does or any side effects beyond what annotations already signal.

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 short sentences with no filler. It front-loads the essential alias relationship and includes the deprecation warning, so 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 parameterized tool with no output schema and no parameter documentation, the description is too sparse. It does not say what `kbid` means, what `docid` is for, or what invoking this tool returns or changes beyond the generic destructive annotation.

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 has zero description coverage for `kbid` and `docid`, and the description does not explain either parameter. The mention of `sectionType: agent` is not part of the schema and does not clarify how `kbid` or `docid` should be populated.

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 alias relationship: it is the shorthand form of `unlearn` with `sectionType: agent`. This distinguishes it from the sibling `unlearn` tool, though the underlying behavior is not defined beyond that shorthand connection.

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 deprecation notice and 'shorthand for unlearn' provide clear contextual guidance: the tool exists as an alias, and the agent is warned it will be removed in 2.0.0. It does not explicitly say 'use unlearn instead', but the implication is direct and unambiguous.

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

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

It discloses a meaningful behavioral trait: the tool proposes content and waits for user confirmation, so it is not a silent write. This goes beyond the annotations' base safety hints, though it does not explain behavior on unsupported hosts or the legacy no-op action values in detail.

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

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

The entire description is one short, front-loaded sentence with no filler. It states the core action, the confirmation behavior, and the prerequisite in an economical way.

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 tool with three parameters, good schema coverage, and a non-destructive annotation, this description covers the essential use case. It could also explain the legacy action no-ops and unsupported-host behavior more explicitly, but the current level is enough for safe selection and 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 the parameters are already described in the input schema. The description only loosely maps 'knowledge' to the title/content parameters and does not add extra guidance on formatting or the meaning of different action values.

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—proposing knowledge for user confirmation—rather than being a tautology. It also distinguishes the tool from direct storage tools like 'learn' by emphasizing the user-confirmation step, though it does not explicitly name sibling alternatives.

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 clearly states the enabling condition: 'when the host supports elicitation.' This provides a clear context for use, but it does not say what to use instead when that condition is false or how to choose among the legacy no-op actions.

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

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

Annotations already indicate the tool is read-only and idempotent, so the description does not need to cover safety. The description adds value by specifying exactly what the tool reports: checksum mismatches, orphan sections, broken references, and circular references.

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, front-loaded sentence that states the purpose and the key output categories without any wasted words. It is compact, scannable, and informative.

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

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

For a parameterless, read-only diagnostic tool with no output schema, this description is sufficiently complete. It tells the agent what the tool checks, what kinds of reports it returns, and annotations cover the behavioral safety aspects.

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, so there is no input semantics to document. The description correctly focuses on behavior instead; a score of 4 is appropriate for a parameterless tool.

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

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

The description names a specific verb and resource: 'Verify the integrity of the knowledge base.' It also enumerates what the verification produces, so an agent can immediately recognize both the purpose and the tool's output domain.

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 intended use is clear: perform this when integrity validation is needed. However, the description offers no guidance about when to prefer sibling tools like 'status', 'contradictions', or 'gaps', which may overlap with the listed report categories.

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 explicitly discloses that the tool is non-destructive ('nothing of is merged') and that each group includes a 'weakest 'file link' in its output. It also goes beyond the annotations by stating a concrete limitation: without an 'entailment judge kbdb' cannot detect self-disagreement within a group. This is valuable behavioral context that the caller needs before relying on a proposal.

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 earns every sentence: a one-sentence purpose, a one-sentence reminder that no merging occurs, a one-sentence output feature, and a one-sentence critical warning. It is front-loaded and no redundant wording. Despite front-loading, it fits in under 30 words, giving it a strong signal/se to size ratio.

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 two optional parameters and no output schema, this description is complete. It states what the output contains (proposed groups with weakest link), clarifies the side-effect-free nature, and gives a decisive fairness warning. An agent can safely invoke and interpret the tool without missing critical 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?

The description doesn't add much to parameter understanding beyond the schema, which already defines 'about' and 'limit' clearly and covers 100% of parameters. The body text does not explain how 'about' affects grouping or how 'limit' bounding, so it relies on parametric definitions. Schema coverage is high, so a baseline 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 action: it proposes groups of stored sections, not an actual merge. It concretely clarifies scope with 'Proposes ONLY — nothing is merged,' so an agent cannot confuse this with a mutating consolidation tool. The 'knowledge base ... become a few good ones' phrasing grounds the resource and use case, distinguishing this from search or revision tools.

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

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

The description gives a clear context for when to invoke the tool: when overlapping stored sections need to be reorganized into fewer, internally coherent groups. It also gives a crisp boundary: the tool never merges, so use it for proposals only. It does not name a sibling alternative, but the 'read every section before merging' warning helpfully tells the agent what follow-up caution is required.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful context that output is 'rendered Markdown', but does not disclose behaviors such as what happens with mixed/missing identifiers or whether large input sets are supported.

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 clearly front-loads the action and output. Every part earns its place, with no filler or unnecessary detail.

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

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

With only two parameters, a complete schema, and a clear output statement, this is an adequately described simple tool. It lacks usage guidance for sectionType and does not explain its relationship to skill-content or agent-content, leaving some ambiguity for an agent.

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

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

Schema description coverage is 100%, including 'One or more kbid or docid identifiers' and 'Partition to scope the operation'. The description does not add additional parameter meaning beyond what the schema already provides, so the 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 names a specific verb ('Compose') and a clear resource ('a rendered Markdown document') plus the inputs (kbid/docid identifiers). It distinguishes itself reasonably from generic read tools like search or retrieve, though it does not explicitly name 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?

There is no guidance about when to use this tool versus alternatives such as retrieve, recall, or the skill/agent-scoped content variants. The description states what it does but not when the agent should select 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?

The description discloses critical behavioral caveats beyond the annotations: this tool finds related pairs, cannot judge agreement, and an absent 'contradicts' result does not mean no conflicts exist. This prevents a dangerous ontological misinterpretation by the agent.

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

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

The description is three sentences with no wasted text: the main operation leads, followed by crucial caveats that are each valuable for correct invocation and interpretation. It is front-loaded and appropriately compact for a one-parameter read-only tool.

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 a clear endpoint purpose, the description is complete. It explains what the tool returns conceptually, how to interpret an empty result, and what the underlying mechanism can and cannot establish.

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, 'limit', is already fully described in the schema with a default value, so the description adds no new parameter-level meaning. Baseline 3 is appropriate because 100% schema coverage means the schema carries the semantic weight.

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: it reports pairs of stored sections that cover the same ground. It goes beyond the name and clarifies that the tool surfaces similarity, not contradiction, which is essential for distinguishing it from what the name might imply.

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 concrete usage context: use these pairs when you are about to trust stored sections and need to read corroborating or overlapping material first. It does not explicitly name alternatives, but the phrasing 'to read together before trusting either' implies the decision point for using the 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 adds meaningful behavioral context beyond the annotations by specifying that the output is a self-contained directory and that it includes sections, documents, and catalog but excludes indexes. It does not cover overwrite behavior, permissions, or return status, but the idempotent/non-destructive annotations already establish the core safety profile.

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?

One tight sentence conveys the action, output type, inclusion set, and exclusion set without redundancy. The most important information is front-loaded and every part of the 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 tool with one optional parameter and no output schema, this is close to complete: the destination and snapshot structure are clear, and annotations cover idempotence and safety. The only gaps are unspecified return/success behavior and whether the target path is created or expected to exist.

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

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

The schema coverage is 100% and the single parameter path is explicitly documented with a default value. The description adds no parameter-level meaning beyond what the schema already provides, so the 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 states a specific verb ('Export'), a clear resource ('the knowledge base'), and a concrete deliverable ('self-contained directory snapshot'), then enumerates what is included and excluded: 'sections, documents, catalog -- no indexes'. This clearly differentiates it from read/search/index-related 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?

The intended use is implied: call this when you want a directory snapshot of the knowledge base, not an index-aware operation. However, the description does not explicitly state when to use it versus alternatives, and none of the sibling tools are mentioned as alternatives or exclusions.

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 a critical caveat beyond the readOnlyHint and idempotentHint annotations: the ranking is triage, not measurement, because the log only records how searches went, never whether answers helped. This protects the agent from over-trusting the output.

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, front-loaded sentences: the first describes the output and ordering; the second tells when to invoke and how to interpret the ranking. 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?

Complete for a read-only triage tool: it explains purpose, usage trigger, output ordering, and interpretation limits. It stops short of explicitly naming sibling alternatives or the precise returned shape, but overall covers the agent's key needs.

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%, with both limit and since already described clearly. The description adds useful context around interpretation but does not need to add parameter-level detail.

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

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

States a specific verb ('Report') and a specific resource ('what this knowledge base is repeatedly asked and answers badly'), with a clear output ordering ('worst first'). This clearly distinguishes it from sibling retrieval tools like search or retrieve.

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

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

Gives an explicit usage trigger: 'Call it to decide what to learn next.' It does not explicitly contrast with sibling tools or say when not to use it, but the intended decision point is clear enough to guide 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?

Annotations already declare destructiveHint=true, and the description adds meaningful scope: removal is limited to unreferenced sections and the exact eligibility rule is provided. This makes the operation more predictable. It doesn't discuss irreversibility or effect reporting, but the destructive annotation plus the precise scope is strong transparency.

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. The first states the action, the second states the condition. Every clause contributes and there is no redundant phrasing, making it easy for an agent to parse 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?

For a zero-parameter destructive tool, the description is complete: it states the action and the exact criterion of what will be removed. The annotations cover the destructive nature, and because the tool has no input schema or output schema requirements, there are no additional expectations to clarify.

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 accepts no parameters, so there is nothing the description needs to add about parameter meaning. Since parameters are absent, the description is not missing any parameter-level guidance; the eligibility condition in the description is the only relevant input context.

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 object: 'Remove unreferenced sections from the knowledge base.' It defines exactly what the tool does and the eligibility criterion. The name 'gc' is cryptic, but the description fully disambiguates it from sibling management tools like consolidate or rebuild.

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 a clear condition for which sections are eligible, but it does not explicitly tell the agent when to invoke gc versus related maintenance tools such as rebuild or consolidate. The intended usage is implied, not explicitly stated, and no alternatives or exclusions are mentioned.

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

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

Annotations only declare read-only/idempotent/non-destructive. The description carries the behavioral load: revisions are retired not deleted, a stale kb-id still resolves to the replacing text, and the enumeration has an edge case (revised once = two revisions; never revised = one). These are non-obvious behaviors an agent could not infer from annotations or schema.

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

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

Three sentences, each earning its place: the core behavior, the exact condition to invoke under, and the count edge cases. The key trigger is mid-placed.io keeping the description under ~50 words with zero redundancy.

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

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

With no output schema, the description acts as the return contrat; enumerates all revisions oldest first and names the current one. For a single-parameter, no-nested, no-enum tool it covers case, trigger, and edge cases — by not of what an agent needs to invoke it correctly.

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

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

Schema coverage is 100% ('Any revision, current or superseded'), so the baseline is 3. The description adds value by explaining what 'superseded' means operationally — that a stale/id no longer in search still resolves to its replacement — which is material to acceptable values beyond the schema's one-line description.

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

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

The description states the exact operation — 'List every revision of a section' — plus the ordering (oldest first) and the distinguishing output behavior (names the current one). This is specific verb+resource language and clearly separates it from siblings like content, retrieve, recall, and revise, none of which claim revision enumeration.

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: 'Call it when a kb-id you hold no longer appears in search.' It also explains the rationale (revisions are retired, not deleted) so an agent can recognize the staleness scenario and route here instead of re-running search or retreating. This is direct when-to-use guidance with a named alternative behavior.

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 say openWorldHint is false, idempotentHint is true, and destructiveHint is false. The description adds useful behavioral detail: structured content splits into sections sharing a docid, each with level and parent, and replace matching follows title/document/heading rules. This goes beyond the annotations without contradicting 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 description is dense but about 100 words, and it front-loads the core purpose before giving storage rules and replacement semantics. Every sentence contributes practical guidance, with no wasted repetition.

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

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

Given the large sibling family, the description gives sufficient context about why to perform the operation and how content and replace behave. The main gap is that it does not explicitly explain the role of sectionType relative to skill- and agent-scoped sibling tools, which would make it fully self-contained.

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 already high. The description adds semantic value by explaining why tags matter, how content splitting behaves, and how replace matches titles against documents or heading paths, which the schema descriptions do not fully convey.

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 clear action and resource: storing durable knowledge in the agent's second brain, with concrete examples like decisions, corrections, and facts. This distinguishes it from read/query tools such as retrieve, recall, and search.

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

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

It gives explicit guidance on what to store (facts that cost real effort to find), what not to store (code/docs content, chat summaries, guesses, secrets), and directs corrections to revise instead of duplicating knowledge. It does not explicitly address the general/member scopes such as skill-learn or agent-learn, but sectionType helps cover that gap.

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 states the persisted side effect: it accumulates real usage into an eval dataset. This goes beyond the annotations, which only indicate idempotence and non-destructiveness. The note about the usefulness of wrong answers is additional behavioral context that helps the agent decide when and how to call the tool.

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

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

The description is compact, front-loaded with the core action, and then adds a practical usage instruction. The 'wrong answer is the more useful judgment' clause is relevant guidance rather than filler. No unnecessary content is present.

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, the description tells an agent what it does, when to invoke it, and what bias of behavior is expected. The annotations cover safety and idempotence, and the schema fully documents the parameters. Nothing essential for correct invocation is missing.

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

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

The input schema has 100% parameter description coverage: query, kbid, and useful are each described. The description adds modest semantic value by explaining that a false answer is still a valuable 'useful' signal, but it does not need to restate 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 clearly identifies the action ('Record'), the target resource ('whether a recalled section answered a query'), and the broader purpose ('Accumulates real usage into an eval dataset'). This makes it confidently distinguishable from the retrieval, learning, and search sibling tools, which do not perform feedback recording.

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 timing guidance: call it once you know whether a result helped, and explicitly calls out that negative judgments should also be recorded: 'It is wrong answer is the more useful judgment.' It does not enumerate what not to use or name alternative tools, so it stops 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 already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, but the description adds valuable behavioral context: seven relations are recorded facts while 'similar' is inferred from a cosine score. It also warns the agent about the 'Related' relation, which is not generic but task-judgment sensitive. This materially shapes invocation and result interpretation.

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

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

The description is compact but information-dense: it front-loads the action, then packs the eight relation names and the key fact-vs-inference distinction into a few terse sentences. Every sentence contributes behavioral or selection value, 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 output is a graph of neighbours with relation types, and no output schema is provided; the description still tells the agent what to expect (relations and their provenance) and how to use it. Gaps are minor: it doesn't fully define what a 'neighbour' edge looks like, but coverage is 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?

Schema description coverage is about 100%: kbid is 'The section to look around' and the limit is 'Maximum neighbours to report (default 20)'. The tool description adds no additional parameter meaning beyond the schema, 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 starts with a specific verb-resource pair: 'List what relates to a section and HOW'. It enumerates the eight relation types and explains which are recorded facts versus inferred, clearly distinguishing this navigation tool from content/search/recall 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 a clear usage context ('so you can decide what to read next') and explicitly warns that 'Related is not relevant -- judge these against your task.' It could be stronger by contrasting it to specific sibling tools like search or retrieve, but the intended selection condition is clear.

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 and destructiveHint=false. The description adds valuable context that the tool rebuilds derived data from source files, which aligns with destructiveHint=false and clarifies the safety of the operation. It does not describe side effects like overwriting existing indexes, but the non-destructive hint mitigates this need.

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 short sentences: the first states the concrete action and source, the second states the exact usage scenario. There is no redundancy and no unrelated detail, so 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?

For a zero-parameter, no-output-schema tool, the description is complete: it tells the agent what the tool does, what it consumes, and when to call it. No extra context is needed 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?

The tool has zero parameters and schema coverage is 100%, so there is nothing left undocumented. The description mentions the source of reconstruction ('section files and document manifests'), which is behavior, not parameter detail. This fully satisfies the parameter semantics dimension.

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 action with a specific verb ('Reconstruct'), the resource ('all index files'), and the input sources ('from section files and document manifests on disk'). It distinguishes itself from sibling tools like search or retrieve, which query indexes, by focusing on rebuilding them.

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

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

The sentence 'Use this to recover from index corruption' explicitly identifies the condition for invoking the tool. It does not mention alternatives or when not to use it, but the context is strong enough for an agent to select it appropriately among siblings.

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, idempotentHint=true, and destructiveHint=false, and the description adds context beyond that: it states what will be returned (section text, level, parent, metadata, references, back-references) and explains maxTokens as a payload budget that replaces depth. No contradiction with annotations.

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

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

Three sentences with no filler: purpose first, then usage instruction, then key parameter guidance. Every sentence earns its place and the important scoping cue 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?

The schema covers all parameters, the annotations cover safety, and the description covers invocation, output content, and budget/format choices. It is slightly incomplete because it does not clarify when to use default recall versus skill-recall/agent-recall, nor which identifier combination is actually required.

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 some contextual meaning, such as calling it on search-returned kbids and using compact when only content is needed, but it does not substantially deepen what the schema already says about each parameter.

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

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

The description clearly names a specific operation ('Expand remembered context', 'Retrieves full content and context') and a specific resource ('sections by identifier'). It also differentiates the tool from search by stating it operates on the kbids search returned, which makes its role in the workflow 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 gives explicit call-time guidance: 'Call it on the kbids search returned' and advises when to use maxTokens and compact format. It stops short of a 5 because it does not mention exclusions or direct the agent to the dedicated skill/agent variants.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the 'low-level fetch' framing and implies it returns raw content without metadata or back-references, but no additional behavioral details like empty results or error handling are provided. The description does not contradict 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 core purpose is stated first, and the important routing guidance about `recall` appears second. 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 simple, read-only, idempotent fetch tool with fully described parameters and explicit sibling routing, the description is nearly complete. It stops short of specifying response shape, but the absence of an output schema and the intentionally low-level nature make that acceptable.

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

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

Schema description coverage is 100%, with both `kbid` and `docid` already documented in the schema. The description only repeats the notion of fetching 'by identifier' and adds 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 states a specific low-level fetch operation targeting a section or document by identifier, and contrasts it with `recall`. This clear differentiation makes it easy for an agent to distinguish this tool from the many sibling retrieval-like tools such as recall, content, and search.

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 that for AI agent workflows, `recall` should be preferred because it includes metadata, context, and back-references. This gives clear when-to-use and when-not-to-use guidance and names the alternative tool directly.

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

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

The description goes well beyond the annotation by explaining the mutation model: content addressing creates a new kb-id, the old record is retired but not deleted, search visibility changes, direct read by kb-id still works, and history can walk between versions. It also clarifies partial updates (omitted fields keep values).

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?

Every sentence in the description earns its place: when to use it, the core mechanic, the old-record behavior, and the partial-update rule. It is dense without being verbose.

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 definition gives the agent what it needs to call rev like safely: it explains what happens to the old and new versions, how search/read treat the revision, and how optional fields behave. With no output schema, the remaining detail burden is minimal.

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?

Only 2 of 7 parameters are described in the schema (kbid and content). The description adds the important partial-update behavior: omitted fields keep their existing values. But the meanings of tags, docid, title, description, and sectionType are still inferred solely from names, so the low schema coverage is not fully compensated.

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 is explicit and specific: it says when a stored fact is wrong, fix it with revise rather than adding a duplication. It also distinguishes the action from copy-like alternatives and from hard deletion, making it clear this is a correction/update operation.

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?

Opens with a clear condition, 'when a stored fact is wrong', and tells the agent not to create a second copy. It does not explicitly name sibling tools or state when to use unlearn/learn instead, but the usage context is strong.

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

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

The description reveals concrete behavioral properties beyond the annotations: unresolved kbids cause rejection, duplicates are dropped, and a single invented kbid fails the entire batch. These details are non-obvious and valuable for safe invocation, and they align with the idempotentHint and destructiveHint annotations.

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

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

Three compact sentences communicate core purpose, validation behavior, and the critical invocation precondition with no redundant filler. The most important operational restriction is placed at the end for emphasis while the first sentence front-loads the primary purpose.

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 a 100%-described schema and no output schema, the description covers the essential decision factors: persist semantics, validation rules, duplicate handling, and batch failure behavior. An agent has enough to call it correctly without hunting for hidden edge cases.

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 describes the only parameter 'cases' as JSONL with query, expectedKbids, and grades. The description reinforces that kbids must come from actual search results, which adds some semantic color, but it does not add a substantive layer beyond the already-complete 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-resource pair ('Validate and persist retrieval eval cases') and identifies the source workflow ('drafted via the eval-generate prompt'). This clearly distinguishes the tool from the generic sibling tools like retrieve, learn, or search.

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 important constraint: call it only with kbids a search actually returned, and explains the consequence of violating that. However, it does not explicitly name an alternative tool or define a contrasting situation where a different tool should be used instead.

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 the tool as read-only, idempotent, and non-destructive, and the description adds meaningful behavioral context beyond that: ranked retrieval, a sibling score boost for sections from the same document, the meaning of the retrieval_verdict value, and the recommended query strategy. No contradiction with annotations exists.

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

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

The description leads with the core purpose, then the return shape, then ranking behavior and usage guidance, followed by an important semantic about the retrieval verdict. Every sentence serves a distinct purpose and there is no redundant wording.

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 lack of an output schema, the description compensates by naming the returned fields and explaining the retrieval verdict semantics. Combined with fully documented schema parameters and safety annotations, the agent has enough information to select the tool, invoke it correctly, and interpret its results without guessing.

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 coverage is 100%, and every parameter already has a clear description covering its purpose, defaults, allowed values, and meaning. The tool description does not need to repeat parameter details, and while it adds general search guidance, it does not meaningfully extend the schema's parameter-level 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 operation: ranked search over knowledge base content using keyword and semantic relevance, and it lists the exact result fields returned. It also distinguishes itself from the sibling `recall` tool by explicitly saying 'Use recall for full content', so an agent can tell them apart without opening either schema.

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

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

The description gives concrete usage guidance: use multiple short keyword queries for best coverage, and use `recall` when full content is needed. It also explains how to interpret retrieval_verdict: 'unanswered' means the knowledge base does not contain the information, so the agent should investigate rather than guess.

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 provide read-only, idempotent, and non-destructive safety signals. The description adds deprecation status and an odd alias relationship, but does not disclose expected return behavior, failure modes, or any invocation-specific effects.

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 entire description is two short fragments with no redundant phrasing. Every part, the 'shorthand' framing and the deprecation notice, ear 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?

Given there is no output schema and the only parameter is undocumented, the description is too thin for safe invocation. It leaves the agent without a clear replacement, no output expectations, and no guidance about how the use of 'skill-content' relates to the other content-related siblings.

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 has a required 'ids' array, but the description provides zero explanation for it. With 0% schema description coverage, the description completely fails to help the agent understand what IDs mean, what format they take, or how they relate to 'skill' content.

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 the tool as a shorthand for content with sectionType: skill, giving it a specific resource and scope. It does not state an explicit verb (fetch/list/retrieve), so the action is partly inferred, but the core purpose is still reasonably 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 main usage signal is 'Deprecated; removal in 2.0.0', which suggests the agent should avoid using it, but no preferred replacement is named. Calling it 'Shorthand for content' hints at the sibling tool 'content', but there is no explicit when-to-use or when-not-to-use guidance.

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

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

Annotations already report idempotentHit and non-destructive, so the description need not repeat those. It adds important behavioral context: skills are prompt templates, placeholders use the {{argName}} syntax, and the tool is deprecated with a planned removal version. This goes beyond the structured annotations and describes useful runtime 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?

The entire definition is two sentences and includes a definition, a domain example (placeholder syntax), and a deprecation warning. No word is wasted, and important lifecycle info is placed near the end where it does not obscure the core purpose. This is appropriately sized and cleanly structured.

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 is incomplete for full usage: only the placeholder mechanism is explained, and most parameter semantics are absent. That said, the deprecation note and the phrase 'shorthand for learn' delegate detailed usage to the non-deprecated sibling, making the description enough for an agent to route the call without tripping over undocumented params.

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 0%, so the description carries the full burden of explaining parameters. It successfully describes the core param for writing template-like content, but there are 7 parameters (tags, type, docid, title, replace, description, content) and only content is touched. The sectionType: skill hint indirectly relates to type, but the rest are unexplained. This is a clear gap.

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 explicitly states that the tool is 'Shorthand for learn with sectionType: skill', clearly naming the target resource (skills) and the verb/action (learning). It also defines what a skill is—a prompt template with {{argName}} placeholders—which separates it from other section types. It is not a full descriptive definition, so it does not earn a 5.

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 makes usage context clear: this is a shorthand for a specific variant of `learn`. 'Deprecated; removal in 2.0.0' provides a clear reason not to use this tool when a newer direct alternative exists. However, it does not explicitly say 'use learn instead' nor does it state conditions for choosing among other sibling tools, stopping short of 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 establish the read-only, idempotent, non-destructive profile, so the description does not need to restate those. It adds value by disclosing the exact sectionType mapping and the pending removal in 2.0.0, which is useful context 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?

The description is extremely compact, front-loads the core meaning, and adds a deprecation notice without filler. Every sentence contributes necessary semantic or lifecycle information.

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

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

For a deprecated alias tool, some brevity is acceptable, but the five completely undocumented parameters leave too much implicit. Without output schema or parameter details, the description is not self-sufficient; it only works if the agent happens to know the parent recall tool's interface.

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 0%, and the description offers no meaning for kbid, depth, kbids, format, or maxTokens. The agent cannot determine how to construct a valid call from this definition alone, and the tool name gives only a weak hint that these match the recall tool's parameters.

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

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

The description defines this tool as a shorthand for recall with sectionType fixed to 'skill', which is a precise resource and scoping statement. It also clearly communicates its deprecated status with a removal version, distinguishing it from plain recall and other skill-* 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 deprecation notice tells the agent the tool should no longer be preferred, and 'shorthand for recall' identifies the alternative tool. It is clear this exists for backward compatibility, although it does not explicitly say 'use recall instead' or describe when new code should avoid 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 cover read-only, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: the fixed 'sectionType=skill' semantic and the lifecycle status. This is appropriate for a thin deprecated alias.

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 short sentences with no fluff. It front-loads the main semantic ('shorthand for search with sectionType: skill') and communicates the deprecation and removal version. 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?

The description clearly tells the agent what the tool is and why not to use it, but it leaves the agent without any description of return values or parameter details. Given the absence of an output schema and 7 unannotated parameters, the description is a bit too terseained to be fully complete in 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?

With 7 parameters and 0% schema description coverage, the description carries the burden of explaining parameters, but it only mentions the implicit 'sectionType=skill'. It does not clarify 'algo', 'mode', 'docid', 'limit', 'offset', or 'relaxed', although enum names and parameter names are somewhat self-explanatory. This is insufficient for a tool with such a low coverage rate.

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 exactly what the tool is: a shorthand for 'search' with sectionType fixed to 'skill'. It distinguishes itself from the generic 'search' sibling and from other 'skill-*' tools by naming the parent operation and the filtering constraint, while also flagging its deprecated status.

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 when-not-to-use signal: it is deprecated and scheduled for removal. It also identifiers the alternative by describing the tool as 'shorthand for search', implying that the full 'search' tool should be used instead.

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?

It discloses the alias behavior, the fixed 'sectionType: skill', and the deprecation status, which go beyond the annotations. However, it does not describe what data is affected by unlearning or what consequences the destructive hint entails.

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 exceptionally terse: two sentences carry the alias identity, fixed parameter behavior, deprecation, and removal version. There is no redundant language.

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 deprecated tool meant as a shorthand alias, the description is enough to identify and avoid it, but it leaves destructive behavior, parameter semantics, and output behavior unexplained. It is minimally adequate but not 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 description coverage is 0%, and the description does not explain 'kbid' or 'docid' or clarify optionality, so the agent must infer meaning from names alone. The hidden 'sectionType: skill' is helpful but does not compensate for the lack of parameter documentation.

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

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

The description states this is a shorthand for 'unlearn' with 'sectionType: skill', which clearly identifies the resource type and distinguishes it from generic and agent-scoped unlearn/skill tools. The title 'Unlearn Skill' reinforces the verb-resource pair.

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?

Describing the tool as deprecated and as shorthand implies the canonical 'unlearn' tool should be preferred, but it does not explicitly tell the agent when to use this tool versus other alternatives. It provides lifecycle guidance but not clear selection conditions.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context by listing the specific statistics returned (document count, section count, etc.), but it does not describe return shape or whether this is a live aggregation versus a cached snapshot. With annotations present, this is adequate but not rich.

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 front-loading the operation (Get) and resource (knowledge base status), then enumerating the included metrics. There is no filler and every phrase adds relevant detail.

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

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

For a zero-parameter, read-only tool with rich annotations, the description is largely complete: it states the operation and the information delivered. The only gap is that the exact output format is not specified, but no output schema exists and the printed metric names provide sufficient expectation for an agent.

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

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

The tool has zero parameters, so there is no parameter semantics to document. The schema covers 100% of parameters trivially, and the description's mention of status outputs is not needed for parameter understanding.

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 names the operation (get) and the target (knowledge base status), and it lists the concrete metrics included (document count, section count, index size, cache statistics). It does not explicitly differentiate from sibling tools like check or content, but no sibling is a direct status duplicate, so the risk of confusion is limited.

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 purpose statement implies usage: call this when you need status or health statistics for the knowledge base. However, the description provides no explicit when/when-not guidance compared to sibling tools such as check, content, or gc, so the guidance is inferred rather than stated.

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

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

Annotations already declare destructiveHint and idempotentHint, which lower the burden. The description adds an important fact beyond those annotations: using docid removes an entire document and its member sections, which is a cascading destructive effect an agent should know. It does not discuss reversal/auth/returns, but the main risk is disclosed.

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

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

One sentence with zero waste, the principal action ('Remove') is front-loaded, and all follow-up information is packed in a single useful branching structure. The parenthetical about member sections is essential and does not bloat the text.

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

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

Combined with the rich schema (including sectionType) and annotations, the description is enough for an agent to invoke the tool correctly for the main use cases. A little more context about sectionType default behavior or the return value could improve it, but for a destructive, idempotent deletion tool structured information covers most of the gaps.

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

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

The schema already provides a description for every parameter, including the sectionType partition choices, so the description is not required to carry the parameter load. However, the description only restates what the schema says and introduces a slight terminology mismatch by saying 'docid' while the schema calls it a 'document kbid', which prevented extra 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 names a specific verb and resource: a section can become a document can be removed, with the second mode explicitly editing all member sections. This makes the tool's purpose unmistakable in the broad sense. It does not explicitly route an agent away from the sibling skill-unlan and agent-unlan tools, so it does not fully earn a 5.

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 'or an entire document by docient' wording implies when to use the doc mode instead of a single-section deletion. There is no explicit comment about when to use this tool over the skill- or agent-scoped siblings, and the sectionType parameter's role is not reflected in the description. Guidance is therefore decent but implicit.

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