Kage

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

Annotations already declare readOnlyHint=true, so the description correctly implies non-destructive behavior. It adds context about combined functionality and code graph answers, which is useful beyond the annotations.

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

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

Two sentences with no redundancy, front-loaded with core purpose, then usage guidance. Every sentence adds value.

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

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

Given the tool's complexity (6 params, no output schema, many siblings), the description adequately covers purpose and usage. Lacks detail on return format but acceptable without output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add extra semantic context for individual parameters beyond what the schema already provides.

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

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

The description clearly states the tool is the primary entry point that validates memory health, recalls packets, and queries code/knowledge graphs. It distinguishes itself from sibling tools by aggregating multiple functions into one call.

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

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

Explicitly advises to call at the start of every task and notes it reduces the need for a separate graph tool, providing clear when-to-use and implicit 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?

The description reinforces the annotation's readOnlyHint by stating 'Read-only' and 'Does not modify any memory.' It also details the return format (grouped entries with titles, types, etc.) and mentions call-outs for weak or undocumented hot paths, providing rich behavioral context.

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

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

The description is well-structured with a clear purpose, usage guidance, and behavioral notes. It could be slightly more concise but remains focused and front-loaded with essential 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?

Given the tool's simplicity (one parameter, no output schema), the description provides sufficient context: it explains what the tool returns, its use cases, and that it is read-only. This is complete for an agent to invoke correctly.

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

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

The sole parameter 'project_dir' is fully described in the schema as 'Absolute path to the repository root.' The description does not add any additional semantics beyond what the schema provides, so it meets baseline expectations.

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 defines the tool as summarizing the repo's 'why' memory, listing specific content types (decisions, gotchas, conventions) and distinguishing its purpose from sibling tools like kage_context.

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

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

It explicitly states when to use the tool: 'to brief yourself on a repo before changing it' and 'to audit where knowledge is thin.' It implies not to use it for modification but does not list alternatives explicitly.

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

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

Annotations declare readOnlyHint=true, so the description's 'reports' is consistent. However, the description does not disclose what happens if no path exists or other edge cases, which would enhance transparency beyond the annotation.

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

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

A single, well-front-loaded sentence that communicates the core functionality with no wasted words.

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

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

The description covers the main use case but lacks details on return format, error handling, or edge cases. Given no output schema, more completeness would be beneficial.

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 clear parameter descriptions. The tool description adds no additional parameter meaning, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: finding how two files are connected in a code graph, specifying three types of directions. This is distinct from sibling tools which focus on context, decisions, docs, etc.

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 implies usage for understanding file dependencies but does not explicitly state when to use this tool over others or provide exclusions. Usage is inferred rather than explicit.

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

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

Annotations provide readOnlyHint=true. The description adds algorithmic details (BM25, heading-anchored chunks), indexing scope (only files on disk), and output format. No contradictions.

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

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

The description is four sentences, front-loaded with the core purpose, and each sentence adds distinct value: what is searched, how it works, what is returned, and what is not indexed.

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?

Despite no output schema, the description explains the return fields and indexing source. It covers all essential aspects: scope, algorithm, constraints, and output, making it complete for a search tool.

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

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

Schema coverage is 100%. The description adds meaning by explaining query as search terms, project_dir as absolute path, limit with default, and returns doc_path, heading, line, snippet. It also describes the indexing source.

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

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

The description clearly states the tool searches committed documentation in the repo, using BM25 over heading-anchored chunks, and returns ranked results with specific fields. It distinguishes from internet search by specifying it indexes only files on disk.

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 implies usage when needing info from the project's own docs and explicitly says 'never the internet,' which helps avoid misuse. It does not explicitly mention when to use alternatives among siblings, but the context is clear enough.

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 that the tool 'Mutates the packet's quality signals on disk,' which is consistent with the readOnlyHint:false annotation. It also explains the effects of each kind (helpful, wrong, stale), providing full transparency beyond the annotation.

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

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

The description is two sentences, front-loaded with purpose, then usage guidance, and ends with behavioral disclosure. Every sentence provides essential information without 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?

Given the tool has 3 simple parameters, no output schema, and clear annotations, the description covers purpose, usage, behavior, and parameter semantics completely. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the meaning of each enum value (helpful, wrong, stale) and their consequences, which is not fully captured in the schema descriptions. However, the schema already describes the parameters adequately.

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

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

The description clearly states the verb 'Record how useful a recalled repo-local memory packet was' and identifies the resource as memory packets. It distinguishes from sibling tools like kage_learn (which adds knowledge) or kage_refresh (which updates) by focusing on feedback/rating.

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

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

The description explicitly says 'Use it right after a recalled packet helped you, misled you, or no longer matched the code,' providing clear when-to-use guidance. It does not explicitly mention when not to use or compare to alternatives, but the context and sibling tools make the distinction 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?

The description discloses important behavioral details beyond the readOnlyHint=false annotation: the write commits under .agent_memory/, rejects writes when cited paths are missing, scans for secrets/PII before writing, and returns the new packet id plus contradiction warnings. This gives an agent a clear picture of side effects, validation, and output 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 dense but efficient: it front-loads the core action, then gives usage timing, a preference rule, behavioral caveats, and the return value. Every sentence earns its place with no filler or repetition of schema content.

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

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

For a 13-parameter tool with no output schema, the description provides a complete mental model: what the tool does, when to use it, its side effects, its validation rules, and what it returns. The rich schema descriptions fill in the remaining parameter-level details, so an agent has enough to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful operational meaning for paths and allow_missing_paths by explaining the rejection condition and when to set the flag. It does not add semantics for every parameter, but the schema already covers the remaining ones.

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

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

The description clearly states a specific action and resource: capturing a durable, reusable learning as a repo-local memory packet committed under .agent_memory/. It is precise about the object and purpose, though it does not explicitly differentiate among the sibling tools like kage_supersede or kage_skills; it only contrasts with diff-based proposals.

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 use-case guidance: use it the moment you discover something a future session should know, with concrete examples such as decisions, bug root causes, conventions, and setup steps. It also says to prefer it over diff-based proposals when you already know what was learned, but it does not describe when-not-to-use it relative to named sibling tools.

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

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

The description goes well beyond the readOnlyHint annotation by disclosing important behaviors: results are capped to 10 actionable entries by default, stale packets are ranked by urgency, true totals and truncation notes are included, and the output leads with a human summary that should be relayed. It also explains how limit and verbose alter behavior. There is no contradiction with annotations.

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

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

The description is dense but well-organized, front-loading the core purpose in the first sentence and then adding behavioral details in subsequent sentences. Every sentence contributes essential information about what the tool returns and how to control output size. Nothing feels redundant or wasted.

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, the description does a strong job of explaining the return shape: a human summary first, then capped lists with totals and truncation notes. It does not explicitly describe the overall readiness verdict format, but the purpose statement conveys that a merge-ready assessment is returned. This is sufficient for an agent to invoke the tool and interpret results.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful value by explaining the default cap of 10, the urgency ranking for stale packets, that verbose returns everything uncapped, and that limit adjusts the cap. This goes beyond the schema's simple descriptions.

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

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

The description clearly states a specific verb and resource: it checks whether repo memory, code graph, memory graph, and stale-memory state are ready for merge. This distinguishes it from siblings like kage_context, kage_risk, or kage_refresh, which have different purposes. The title reinforces the same intent without ambiguity.

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

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

The description clearly implies use during PR/merge preparation, as it evaluates merge readiness for the current change. It explains what happens on repos with many stale packets and how to get more results, but it does not explicitly name excluded alternatives or state when a sibling tool should be chosen instead. This is clear context with no exclusions, so not 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?

Beyond the idempotentHint and readOnlyHint annotations, the description discloses substantial behavior: the quiet-refresh mechanism for non-default branches, the capping of stale_packets/validation.warnings to 10 entries with truncation notes, and the effect of limit/verbose. No contradiction with annotations.

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

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

The description is dense but well-organized: it opens with the core action, then covers usage timing, branch-specific behavior, and output truncation in a logical flow. Every sentence adds value with no 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?

For a tool with no output schema, the description covers the main operational concerns: when to run, how branch affects behavior, output capping, and override options. It implies the return includes stale_packets and validation.warnings, which is sufficient for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds nuance to force (persists rewrites on non-default branches), limit (caps entries), and verbose (uncaps), which go beyond the schema's basic field descriptions. It does not elaborate on project_dir, but that is self-evident.

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

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

The description opens with a precise verb-resource combination: 'Rebuild repo indexes, code graph, memory graph, metrics, and stale-memory metadata.' It clearly states what the tool does and distinguishes it from siblings like kage_pr_check by positioning it as a pre-PR maintenance step.

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

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

Explicit timing rules are given: 'run this after meaningful file/content changes before PR checks; push-only or same-tree commits do not need another refresh.' It also explains when to override the quiet refresh (pass force) on non-default branches, leaving no ambiguity about invocation 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 provide readOnlyHint=true, signaling a safe read operation. The description adds value by detailing the method ('Kage's code graph plus local git history') and the specific risk factors assessed, without contradicting 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 consists of two concise sentences. The first sentence front-loads the core purpose, and the second provides usage advice. No unnecessary words or 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?

The description lists the analysis dimensions (dependents, impact surface, etc.), giving a good idea of the output content. However, without an output schema, it does not specify the exact return format (e.g., score, report), leaving a minor gap for an agent to infer.

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

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

Schema description coverage is 100%, so parameters are already clearly documented. The tool description does not add additional meaning beyond what the schema provides for each parameter, resulting in a baseline score.

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

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

The description uses a specific verb ('Assess modification risk') and resource ('files'), and lists concrete analysis dimensions (dependents, impact surface, churn, etc.). It distinguishes itself from sibling tools like kage_context or kage_decisions by focusing on risk, not context or decisions.

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

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

The description explicitly states when to use the tool: 'Use before editing hotspot or shared files.' This provides clear context, but it does not mention alternatives or when not to use it, which would be expected for a top score.

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 it writes files (non-read-only) and filters packets, matching idempotentHint. But it does not describe overwrite behavior or what happens on conflict, leaving some behavioral ambiguity.

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

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

The description is concise at four sentences, front-loading the core purpose in the first sentence. Every sentence adds essential information without 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?

While the description covers the main action and parameters, it lacks details on return value or error handling. Given no output schema and the tool's write nature, additional clarity on outcomes would improve 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 100%, so the schema already documents all parameters. The description adds no new semantic information beyond what is in the schema, making baseline 3 appropriate.

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

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

The description clearly states the tool's purpose: creating SKILL.md files from repo memory. It specifies the target location (.claude/skills/) and the selection criteria (only grounded, non-stale packets). This distinguishes it from siblings like kage_context or kage_decisions.

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

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

The description provides usage guidance by mentioning dry_run for previewing and dir for output override. However, it lacks explicit 'when not to use' or comparison with sibling tools, which would enhance differentiation.

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

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

Beyond the annotations, the description discloses significant side effects: it marks the old packet superseded, writes bidirectional lineage edges, keeps the old packet but withholds it from recall, and mutates both packets on disk. It also clarifies that it returns only ids, paths, and titles rather than full packet bodies.

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

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

The description is compact and information-dense, with each sentence forwarding a distinct fact: purpose, behavior, when to use, and output expectations. No filler or redundant restating of the title.

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 mutating tool with no output schema, the description covers effect, lineage behavior, return value shape, and usage conditions. An agent has enough information to invoke it correctly and understand the consequences.

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

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

The input schema already documents all four parameters with meaningful descriptions, so the description benefits from full coverage. The description reinforces the roles of old and replacement packet, but does not add substantial detail beyond the schema.

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

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

The description opens with a specific action and object—'Replace one repo-local memory packet with a newer one'—and clarifies what that means by describing the suspension and lineage updates. It distinguishes itself from deletion and from other kage tools by specifying its unique job.

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

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

It explicitly says 'Use this instead of deleting when new knowledge updates an old fact, or to resolve a contradiction surfaced by kage_conflicts.' This gives concrete selection criteria and points to an alternative behavior to avoid.

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