Cartographer

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

With no annotations, the description carries the full burden. It usefully discloses a non-obvious side effect (deleting the now-empty containing artifact directory for skills/hooks) and implies optimistic concurrency via the required if_match. However it says nothing about permissions/auth needs, whether deletion is reversible, or what happens on an if_match mismatch.

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

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

Front-loaded with the action and its scope; the long path enumeration is informative rather than filler. The if_match requirement is stated compactly in a second sentence. Slightly dense but no wasted phrasing.

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 deletion tool with no annotations and no output schema, the description covers scope, the directory side effect, and required-parameter sourcing, which is solid. Yet it omits failure/mismatch behavior and authorization requirements that an agent needs to call a destructive operation confidently.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by clarifying that if_match is the sha256 of the current content and must be sourced from artifact_read/artifact_list. The path and reason parameters are left to the schema, which is adequate.

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 ("Deletes") and a precisely scoped resource ("KB-root artifact file"), then enumerates the exact path patterns covered (skills/<slug>/**, agents/<slug>.md, hooks/**, etc.). This makes the tool recognizable against siblings like asset_delete or concept_delete. It stops short of an explicit sibling contrast, keeping it at 4.

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

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

Gives clear operational context: it declares if_match as required and specifies where to obtain it (artifact_read/artifact_list), effectively routing the agent to prerequisite siblings. It does not state when NOT to use it or name the alternative delete tools, so it lacks explicit 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?

With readOnlyHint=true and idempotentHint=false already declared, the safety profile is covered. The description adds genuinely useful non-obvious behavior: the return includes sha256, that sha256 is the if_match token for artifact_write/artifact_delete, and that if_match is only present when the KB sets allow_artifact_write. This is exactly the kind of contextual detail annotations can't convey.

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

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

Two sentences, front-loaded with the action and resource, then the return semantics. No filler. Slightly dense in the enumeration but every item earns its place by delimiting the valid path space.

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

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

No output schema exists, so the description carries the return-value burden and does partially: it names content and sha256. But it omits the encoding parameter's behavior entirely and doesn't describe what 'content' looks like under base64 encoding. Adequate but with a real gap given the 0% schema coverage.

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% for 2 parameters (path, encoding). The description implies path semantics through the enumerated artifact locations, which adds some value, but encoding (text vs base64) is completely unexplained in both schema and description despite having an enum. This is a clear gap the description should have filled.

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 (Reads) and resource (a KB-root artifact) and enumerates the exact path space (skills/, agents/, hooks/, mcp/, instructions.md, templates/<slug>.md, paths.yaml, glossary.yaml). This is very concrete and distinguishes it from sibling reads like asset_read or concept_read. It loses a point because it doesn't explicitly frame itself against artifact_write/artifact_delete beyond the if_match mention.

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

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

Usage is implied: you read to obtain content and the if_match token needed for artifact_write/artifact_delete. However, there is no explicit when-to-use versus asset_read/concept_read, and no articulation of when-not-to-use. The link to write/delete is helpful but only one-directional.

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

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

With no annotations, the description carries the full burden and does well: it names the failure modes (stale_write on missing/mismatched if_match, already_exists when a supposedly-new file is present) and discloses that structured artifacts are validated against paths.yaml and glossary.yaml schemas before writing. It omits permission/auth requirements and any note on reversibility, so it is strong but not exhaustive.

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

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

The purpose and scope are front-loaded, and the create-vs-update semantics follow logically. The parenthetical path lists and schema digests make the single paragraph heavy, but every clause carries operative information rather than filler.

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

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

For a mutation tool with no annotations and no output schema, the description covers scope, concurrency (if_match), failure modes, and validation behavior well enough to invoke correctly. It does not describe what the tool returns on success, though that is a minor gap given no output schema exists to lean on.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by surfacing the actual error codes for if_match misuse and by cross-referencing artifact_read/artifact_list for obtaining the hash. It also documents the paths.yaml/glossary.yaml validation expectations that constrain the content parameter.

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

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

States a specific verb+resource ('Creates or updates a KB-root artifact file') and enumerates the exact path families in scope (skills/<slug>/**, agents/<slug>.md, hooks/**, mcp/<slug>.json, etc.). This scope enumeration lets an agent distinguish it from sibling write tools like concept_write and asset_write without opening schemas.

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

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

Gives clear create-vs-update branch logic: include if_match to overwrite an existing file, omit it to create a new one, and points to artifact_read/artifact_list as the source of the sha256. It does not explicitly say when to prefer this over sibling write tools such as concept_write or asset_write, so it falls short of full when/when-not 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?

With no annotations, the description carries the full burden and does disclose the key behavioral trait: the delete is permanent/irreversible. The if_match requirement also signals optimistic concurrency, and 'from an expanded concept' hints at a required state. It still omits permissions, side effects on references, and error behavior for stale if_match.

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, zero waste, with the destructive nature front-loaded and the hard precondition immediately after. 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?

A destructive mutation tool with no annotations, no output schema, and 4 parameters at 25% schema coverage needs more than this. It covers irreversibility and the if_match contract but leaves path/concept_id semantics, permission prerequisites, and failure modes unexplained.

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 only 25% (only 'reason' is documented), so the description must compensate. It adds strong meaning for if_match (raw-byte sha256, must be current, sourced from asset_read/asset_list) but says nothing about path, concept_id, or the trailer meaning of reason.

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 ('permanently deletes') and a scoped resource ('a non-Markdown asset from an expanded concept'), which cleanly separates it from concept_delete and asset_write/asset_read. It does not explicitly name which sibling to use instead, and the boundary versus artifact_delete is left implicit.

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 supplies a genuine precondition ('if_match is mandatory and must be the current raw-byte sha256 returned by asset_read or asset_list'), which implies the caller must read first. However it gives no when-to-use / when-not guidance relative to the other delete tools (artifact_delete, concept_delete).

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

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

With readOnlyHint=true already covering the safety profile, the description still adds real substance: the exact fields returned, and the rule that files over 10 MiB report oversized: true and are 'deletable only'. That constraint is meaningful behavior an agent could not infer from annotations or schema. It does not explain the idempotentHint=false, which is the remaining gap.

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

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

Two sentences, both dense with usable information and nothing redundant; the scope statement is front-loaded ahead of the oversized-file caveat.

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

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

With no output schema, the description usefully enumerates the returned fields and flags the oversized case. It omits ordering, recursion depth, and whether the list is exhaustive, but for a single-parameter read tool this is close to 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% for the single concept_id parameter, so the description must carry it. 'Of an expanded concept' hints that the id refers to an expanded concept, but no format, source, or example is given. Partial compensation only.

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

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

Specific verb+resource: 'Lists the non-Markdown assets of an expanded concept', with the returned fields enumerated (path, size, sha256, executable). It differentiates itself from artifact_* and source_list by scoping to non-Markdown assets of a concept, though it never names a sibling directly.

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

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

Usage is only implied: 'of an expanded concept' signals that the concept must first be expanded (via concept_expand) and that concept_id is an expanded-concept identifier. No explicit when-to-use/when-not, and no alternatives (asset_read, asset_write, artifact_*) are contrasted.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value by disclosing the returned fields and specifically that the sha256 serves as 'the if_match to change or delete it' — linking a read to write/delete concurrency control, which is not derivable from schema or 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?

A single front-loaded sentence with zero filler. The colon-delimited field list is dense but readable, and the primary action leads.

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

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

With no output schema, the description usefully enumerates return fields and the sha256 token role. However, for a three-parameter tool at 0% schema coverage it omits input-parameter semantics and any usage routing, leaving a meaningful gap.

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

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

Schema description coverage is 0%, so the description must carry the param burden, yet it clarifies neither path vs concept_id nor the text/base64 meaning of the encoding enum (encoding appears only as a returned field, not as input semantics). This leaves all three parameters effectively undocumented.

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?

Specifies a clear verb and resource ('Reads a non-Markdown asset of an expanded concept') and even enumerates the fields returned (content, encoding, sha256, size, mode). The 'non-Markdown' qualifier implicitly scopes it away from concept/artifact reads, but no sibling is named explicitly, so differentiation is inferential.

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 phrase 'of an expanded concept' hints at a prerequisite but never states when to choose this over asset_list, concept_read, or artifact_read. There are no when/when-not statements and no alternative routing.

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

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

With no annotations, the description carries the full burden, and it discloses several behavioral traits: a 10 MiB size cap, the optimistic-concurrency mechanism via if_match/sha256, and the executable mode behavior (omitted = preserve on update, non-executable on create). It omits permissions/auth requirements and error behavior on a sha mismatch.

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

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

Three dense, front-loaded sentences with no filler. The create/overwrite mechanics and key constraints are stated first; every clause carries semantic load.

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 write tool with no annotations and no output schema, the description covers the critical write semantics well but is silent on authentication, reversibility of overwrites, and failure modes, leaving gaps an agent would want before mutating an asset.

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 only 14%, so the description must compensate. It meaningfully explains if_match (create vs overwrite), encoding (text or base64, matching the enum), and executable, but leaves path, concept_id, and reason (a commit trailer) undefined.

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 pair and resource: 'Creates or updates a non-Markdown asset of an expanded concept.' The 'non-Markdown asset' qualifier implicitly separates it from concept_write/artifact_write, but no sibling is named explicitly, so it stops short of full differentiation.

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

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

Gives explicit procedural conditions: 'New: omit if_match; overwrite: if_match = current sha256.' This tells the agent exactly which path to take for create vs update. It does not name alternatives like asset_read or asset_delete, so no exclusions are provided.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral value by disclosing what the 'structure: true' flag changes in the response (central concepts and link-graph communities), but says nothing about response size, cost, or what the default/omitted case returns.

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

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

Two dense sentences with the returned content front-loaded and the parameter effect second; nothing is padded. The telegraphic style (colon-joined clauses) is terse but not wasteful.

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

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

For a parameterless-required read tool with no output schema, the description gives an adequate picture of the payload and the optional flag's effect. It leaves domain terms ('Maps', 'Journals', 'atlas') unexplained and does not state what the baseline (structure omitted) response looks like, so an agent still has to infer the default shape.

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 0% and the single boolean carries no schema description, so the description must compensate — and it does, explaining that structure=true augments the output with central concepts and link-graph communities. It leaves the false/omitted behavior implicit, so it is not exhaustive.

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 resource bundle — the root index.md plus Maps and Journals with concept counts — and signals an orientation purpose ('where to start reading'). It does not, however, distinguish itself from near-neighbors like index_get or graph_context, so an agent must infer which overview-flavored tool to pick.

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 trailing clause 'where to start reading' implies the use case (initial orientation, entry point discovery) but never states when to prefer this over index_get, map_list, or graph_context, nor any exclusions or prerequisites. Usage is implied rather than specified.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real value beyond that by disclosing the returned content (newest change, authors, agent clients, operations, reasons) and the conditional behavior of the links flag (links added/removed, orphan transitions). It is silent on the odd idempotentHint=false and on pagination, so it falls short of 5.

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

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

Two dense sentences with no filler; the core scope is front-loaded, and the conditional `links` behavior follows in a clean subordinate clause. Every phrase carries information.

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

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

With no output schema, the description does a fair job sketching the return payload and the links-mode delta. But the undocumented `limit` parameter, unknown pagination behavior, and lack of differentiation from siblings leave gaps for a three-parameter read tool.

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

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

Schema coverage is only 33%: `since` is documented in the schema, and the description meaningfully explains the conditional semantics of `links: true`, which is more than the schema provides. However, `limit` is left entirely unexplained in both places, so the description only partially compensates for the coverage 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?

States a specific verb+resource ('Concept changes from git history since a timestamp or duration') and enumerates the returned fields. It does not, however, distinguish itself from close siblings like concept_history or log_tail, so an agent cannot tell which to pick from the description alone.

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 temporal framing ('since a timestamp or duration') hints at a recent-changes query, but there is no explicit when-to-use statement, no exclusions, and no mention of the obvious alternative concept_history. The agent is left to infer the selection criteria.

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

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

With no annotations, the description carries the full burden and does so richly: atomicity ('one commit and log entry; a failure leaves the KB untouched'), hard limits (50 operations, 512 KiB decoded, patches count edits), and the create-only vs update semantics of if_match. This is exactly the behavioral context an agent needs for a mutation 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?

Dense and front-loaded: atomicity and limits lead, operation semantics follow. Every sentence adds distinct information; no filler or restatement of the tool name.

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 still discloses the return shape (id, content_hash, findings per operation) along with limits, atomicity guarantees, and operation modes. Nothing an agent needs to invoke this correctly and interpret results is missing.

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

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

Schema coverage is 100%, but the schema lists flat fields with no per-field meaning. The description adds real semantic value by mapping fields to operation types — if_match optional means create-only write, if_match required means patch, index_entry only valid on a creating write — which the schema alone does not 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?

States a specific verb pair (write/patch) on a specific resource (distinct concepts) with the defining scope constraint: atomic all-or-nothing batching. An agent can immediately distinguish it from the single-operation concept_write and concept_patch 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 'Not covered' sentence explicitly lists what this tool does not do (delete, move, expand, assets, other index edits), which routes the agent to siblings without naming them. It also clarifies that patch requires if_match while write does not, giving clear selection criteria between the two operation modes, though it never names the alternative tools 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?

With no annotations, the description carries the full burden and does so well: it discloses permanence, git-commit side effect, refusal-with-linkers behavior, that links are never rewritten, and the second force condition for expanded concepts owning assets. It stops short of permission/auth requirements or confirmation semantics, so not a perfect 5, but the destructive profile is clearly conveyed.

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

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

Three tight clauses, front-loaded with the destructive action and its refusal mechanics, then the alternatives, then the extra force condition. No filler sentences; each one carries a distinct constraint.

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

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

For a four-parameter destructive tool with no annotations and no output schema, the description covers the behavioral essentials an agent needs to call it safely and correctly. It does not describe the response shape (e.g., the linker list payload) or the id hash format, which is a minor residual gap.

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

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

Schema coverage is 75%, with id undocumented. The description still adds meaning beyond the schema by explaining the second trigger for force=true (an expanded concept owning assets), complementing the schema's own wording about broken inbound links and asset deletion. id's meaning is self-evident from context, so this lands above the baseline-3 case.

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?

A precise verb+resource ('Permanently removes a concept') plus the notable detail that this is a git commit. It explicitly distinguishes itself from the siblings that could be confused with it (supersede, concept_move), so an agent can route correctly without opening another 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?

States the refusal condition (inbound_links unless force=true) and names the two alternative tools with the conditions that select them: keep the page -> supersede, rename -> concept_move. This is explicit when-to-use and when-to-use-something-else 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?

With no annotations, the description carries the full burden, and it does surface the key trait that the operation is one-way ('No inverse'), which is exactly the irreversibility fact an agent needs. It also notes links keep working. It says nothing about permissions, whether a commit is produced (the 'reason' param hints at git), or failure modes.

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

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

Three tight clauses with no filler; the transformation and its constraint are front-loaded. Slightly telegraphic phrasing costs a point but nothing is 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?

No output schema and no annotations, so the description must stand alone for a filesystem-restructuring mutation. It covers the transformation and irreversibility, but omits error behavior for malformed ids, git/side-effect implications, and any post-condition beyond 'links keep working'.

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 50%: 'reason' is documented in the schema as a commit trailer, while 'id' has no schema description. The description compensates partially by defining id's required shape ('exactly two segments, map/concept') and its role in the file-to-directory mapping, which is meaningful added meaning.

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

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

States a concrete verb and transformation: '<id>.md' becomes a directory '<id>/' with an index.md, so satellites can hang off it. The 'No inverse' note disambiguates it from reversible siblings like concept_move. It stops short of naming a sibling alternative explicitly, but the resource and effect are 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?

Gives one precondition ('id needs exactly two segments (map/concept)') that constrains when it can be used, which is real usage guidance. However, it never says when to prefer this over concept_new, concept_move, or concept_write, so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds ordering (newest first), rename-following, and truncation behavior when more results exist. It omits how to retrieve the untruncated remainder and any error behavior when the concept has no history. 'No git history: no revisions' usefully warns of an empty-result case.

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 terse clauses with zero filler: the payload contract is front-loaded, then the cross-tool hint, then the limitation. The compact field notation is dense but unambiguous.

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

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

With no output schema, the description carries the return-value burden and discharges it well by enumerating fields and noting truncation. It is only short on parameter documentation (limit) and on how to page past the truncation point.

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 never mentions either parameter by name. 'id' is inferable from the tool name, but 'limit' is only vaguely gestured at by 'truncated if more exist' with no statement of its meaning, default, or range. With zero schema documentation, the description needed to compensate and does not.

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 precisely what it returns — commits that changed a concept, ordered newest first, with renames followed. An agent can distinguish it from concept_read, concept_list, and concept_patch without opening any schema, and the inline result shape removes ambiguity about the payload.

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 real routing guidance: 'A sha passed as rev to concept_read shows the concept then,' which tells the agent the follow-up tool and the condition that selects it. Also sets a boundary with 'No git history: no revisions.' It does not, however, state when to prefer this over alternatives such as changes_since or snapshot.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=false, so safety is covered. The description adds real behavioral value beyond that: result ordering (sorted by id) and, critically, that where/timestamp filters apply before limit, which governs how limiting behaves. It does not describe pagination or output ordering stability across writes.

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?

Very dense but front-loaded: the core operation and return shape come first, then filter/limit ordering, then the sibling pointer. Semicolon-heavy phrasing is terse but every clause carries information; no wasted sentences.

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

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

With no output schema, the description correctly takes on return-shape disclosure (id, title, type, status; fields adds keys) plus sorting and filter-before-limit semantics. For a 6-param read tool this is nearly complete; only pagination/result-size limits are unaddressed.

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 50%, and the description compensates by explaining the three undocumented params: scope is a prefix with empty meaning the whole KB, fields adds keys on top of the default projection, and limit is applied after filtering. This adds meaning beyond the bare schema, though it gives no default/format detail for limit.

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

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

States a specific verb and scope: an exhaustive inventory of concepts under a scope prefix, returning id, title, type, status. It explicitly names the sibling it is not (index_get for curated navigation), so an agent can distinguish it 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?

"For curated navigation use index_get" gives one clear alternative with the condition that selects it, and "empty = whole KB" clarifies scope fallback. It lacks any explicit when-not-to-use guidance (e.g. cost on large KBs vs. paginated search), so it falls short of a full 5.

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

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

With no annotations, the description carries the full burden and does so richly: validation-first ordering, batch abort on any invalid entry, KB-wide link rewriting unless disabled, cross-map/services scope, asset/satellite handling for expanded concepts, and the notable failure mode of a mid-batch filesystem error naming both IDs with no rollback. This is exactly the behavioral context an agent needs before a destructive rename.

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?

Dense but front-loaded: the core action and input modes come first, followed by validation, link rewriting, scope, and failure behavior. Nearly every clause earns its place, though the single long paragraph packs several concerns together.

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

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

For a mutation tool with no annotations, no output schema, and only 40% schema coverage, the description is thorough: it covers atomicity/validation, the two input modes, link-rewrite side effects, scope, and failure semantics. An agent has everything needed to call it safely.

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 only 40%, so the description must compensate, and it does: it clarifies the exclusivity between the single source_id/target_id pair and the moves array, and states the default behavior of rewrite_links. It does not explain the 'reason' parameter (though the schema does) or the finding output shape, leaving minor gaps.

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

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

States a specific verb+resource+scope: 'Moves concepts to new IDs in one commit.' It clearly distinguishes itself from siblings like concept_patch or concept_write, which would edit in place rather than re-identify. An agent can tell what this does without opening the schema.

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

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

It explains the two mutually exclusive input modes and the rewrite_links default, which is operational guidance, but never says when to choose this tool over siblings such as concept_patch or concept_write. Usage is implied by the rename semantics rather than stated against alternatives.

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

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

With no annotations, the description carries the full burden and does disclose some behavior beyond the schema: it refuses duplicate ids, index_entry adds the concept to the map's curated index, and it returns findings. It still omits the mutation's side effects, whether index_entry defaults on or off, and what a refused id returns, which are meaningful gaps for a write 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?

Three short sentences, front-loaded with the core action and constraint, with no padding. The phrasing is compressed to the point of being cryptic ('records it as its shape', 'Returns findings'), which costs a little clarity but not length.

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

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

For a 5-parameter mutation tool with a nested vars object, no annotations and no output schema, the description covers the create/refuse/index behaviors but leaves vars semantics, index_entry defaulting, and the vague 'findings' return undefined. It is minimally adequate rather than complete.

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

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

Schema description coverage is only 20% (essentially just 'reason'), so the description must compensate. It explains template (comes from template_list), id (must not already exist), and index_entry (adds to the curated index), but says nothing about vars or how template variables are supplied, leaving half the parameters undocumented in both places.

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

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

States a specific verb and resource ('Creates a concept') plus the source of its content (a KB template from template_list) and a distinctive constraint (refuses an existing id), which separates it from the generic concept_write/concept_patch siblings. It stops short of explicitly naming the sibling it differs from, so an agent must infer the boundary.

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

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

Usage is implied: create a concept when you have a template and a new id, and the 'Refuses an existing id' clause gives a when-not condition. However no alternative is named (e.g. use concept_write to overwrite, concept_batch for bulk), so routing between the many concept_* siblings is left to inference.

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

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

With no annotations supplied, the description carries the burden and does so well: it flags optimistic concurrency ('if_match required (stale_write)'), atomic ordered application of edits, shallow-merge frontmatter semantics, and idempotency of append/remove. It omits failure/permission behavior, so not a full 5.

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

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

Front-loaded and dense; nearly every clause conveys a distinct behavior (concurrency, atomicity, merge semantics, return fields, batch alternative). The telegraphic fragment style trades some readability for compactness, but there is little wasted 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?

For a mutation tool with 11 parameters, no annotations, and no output schema, the description covers return values ('content_hash, findings'), concurrency, atomicity, and frontmatter behavior. Missing only error/permission details, so it is close to complete.

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

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

Schema coverage is only 55%, so the description must compensate. It does explain the important ones (if_match as a stale-write guard, frontmatter as shallow-merge with null deletion, frontmatter_append/remove as idempotent list edits), but leaves 'unset' and 'reason' unexplained and doesn't cover all 11 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?

States a specific verb and resource ('Edit-style patch of a concept body') and enumerates the patch modes (old_string/new_string/replace_all or an edits array). It also names the sibling concept_batch for the multi-concept case, so an agent can distinguish it without opening sibling schemas.

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

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

Explicitly routes the agent: 'Many concepts: concept_batch, up to 50 operations in one commit,' giving a condition and an alternative. It lacks an explicit when-not-to-use statement or a stated prerequisite beyond the if_match note, keeping it 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 declare readOnlyHint=true, so the safety profile is covered. The description adds genuine behavior beyond that: the exact return shape, that with_content returns exact bytes rather than parsed body, that outline yields only headings, and that match greps body lines with context. It omits not-found/error behavior and the interaction with the 60KB auto-outline rule (left to schema), keeping it short of a 5.

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

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

The purpose and return payload are front-loaded, and the semicolon-separated clause per mode is dense and earns its space. It is telegraphic to the point of slight terseness, but nothing is 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?

For an 8-parameter read-only tool with no output schema, the description covers the return shape and the non-obvious mode flags an agent must set, which is exactly what the schema cannot convey. Return values need no separate explanation, and nothing critical for correct invocation is missing.

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

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

With 63% schema coverage, the description meaningfully supplements the schema by explaining semantics for with_content (bytes vs body), section (single section), outline (headings only), and match/context (grep body lines with surrounding context). It does not clarify rev/full, but those are already documented in-prop, so this compensates well above the baseline.

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

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

States a specific verb and resource ('Reads a concept') and enumerates the return payload (content_hash, frontmatter parsed/_raw, body). This distinguishes it from concept_list (enumeration), concept_history (versions), and concept_expand (expansion), though it never names those siblings explicitly.

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

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

The mode flags (with_content, section, outline, match) imply when each retrieval variant applies, giving useful implied usage. However there is no explicit guidance on when to prefer this over concept_expand, concept_history, or concept_list, nor any prerequisites such as needed permissions.

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

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

With no annotations, the description carries the full burden and does so reasonably: it names the optimistic-concurrency mechanism (if_match on content hash), the failure mode ('stale_write if changed'), and what the call returns (content_hash plus structural findings). It omits auth/permission needs and whether unlisted frontmatter fields are dropped on update, so it falls short of a 5.

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

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

Three dense sentences, front-loaded with the create/update action and followed by the concurrency and return semantics. Every clause carries information; the only cost is a slightly telegraphic 'fix them.' that assumes the reader knows what the structural findings are.

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

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

With no output schema, the description correctly compensates by stating what is returned (content_hash and structural findings on links, orphan, index). Combined with the concurrency and required-field notes, an agent has enough to invoke it, though sibling differentiation and mutation-side effects remain unaddressed.

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 60%, and the description enriches the thin schema entry for if_match ('Optional content hash') into a semantic contract — optimistic concurrency yielding stale_write. It also confirms frontmatter is a YAML map with a required type field. It adds nothing for body, id, or reason, but the schema already labels reason as a commit trailer.

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

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

States a specific verb+resource ('Creates or updates a concept') and names the required input shape (frontmatter YAML map + markdown body). It does not, however, distinguish itself from close siblings like concept_new, concept_patch, or artifact_write, leaving the agent to infer which write path to use.

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 explicit when-to-use or when-not guidance. The description never routes the agent to concept_patch for partial edits, concept_new for creation, or concept_delete for removal, so the choice among several overlapping write tools is left to inference.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuine value by disclosing the return payload shape (concept, SHAs, branch, files), which matters since there is no output schema. idempotentHint=false is slightly unusual for a listing tool but nothing in the description contradicts it.

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

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

Two tight sentences: the first front-loads what is listed and what it returns, the second routes to the resolution tool. No filler and no redundancy with the name.

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?

Since no output schema exists, the description appropriately carries the return-field list and points at the follow-up tool. Minor gaps remain, such as scope (per-repo vs global) and whether an empty result is meaningful, but the essentials for correct invocation are present.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to document or omit. Nothing in the description misleads about inputs.

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

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

States a specific verb and resource ('Lists open git rebase conflicts') and enumerates the returned fields (concept, local/remote SHAs, branch, files). This clearly distinguishes it from the sibling write tool git_conflict_resolve, which is named in the same sentence.

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?

Provides an explicit next-step alternative: 'Resolve with git_conflict_resolve (kb-conflict-resolve skill).' This tells the agent which sibling to reach for once it has the conflict list, though it does not spell out prerequisites or when this tool is not appropriate.

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 readOnlyHint=true and idempotentHint=false, so the safety profile is covered. The description still adds real behavioral context: mode-dependent behavior (changed_ids alone skips whole-KB structure checks; empty changed_ids runs whole KB but skips the commit gate) and that severity_min is bypassed on a pass. It does not say what a failing gate returns, but that gap is minor.

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

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

Front-loads the identity ('Local gate: validate + lint + commit_gate') before the usage and parameter details, and every clause carries information. The telegraphic semicolon style is dense and slightly cryptic, but nothing is 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?

For a composite, mode-switching tool with four parameters, no output schema, and moderate annotation coverage, the description covers purpose, invocation moments, and per-parameter behavior adequately. What is missing is the meaning of a gate result (what failure blocks) and any note on cost or ordering of the three sub-checks.

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 only 50%, so the description must carry weight — and it does, defining changed_ids scoping (just those IDs vs whole KB when empty), scope as a path prefix, and severity_min's default of warning plus its interaction with 'pass'. scope_neighbors is left to its schema text, which is acceptable.

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

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

The description names the resource (a 'local gate') and immediately decomposes it into the three checks it composes: validate + lint + commit_gate. That distinguishes it from the sibling standalone 'validate' and 'lint' tools, though 'gate' itself is domain jargon and no plain verb (run/check) anchors the action.

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 concrete trigger conditions: 'Use at session end over the IDs you wrote, or before fast-forwarding to main.' That is clear context for selection, but it never explicitly contrasts this composite gate with calling validate or lint directly, so the agent must infer when the narrower siblings are preferable.

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

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

With no annotations, the description carries the full behavioral burden. It discloses important post-resolution behavior: Cartographer merges, commits, pushes, and clears degraded markers only after all open conflicts are resolved. However, it omits permissions, reversibility, error behavior, and whether pushes are remote, leaving meaningful gaps for a mutation 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 two tight sentences, front-loading the core action and then compactly explaining the strategy enum and lifecycle. No sentence is wasted, and the structure is easy to scan.

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 no annotations, no output schema, and only 33% schema description coverage, the description does some of the necessary work by covering strategies and post-resolution side effects. It remains incomplete because the required concept_id parameter is unexplained and no safety or error context is provided for a conflict-resolution mutation.

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 only 33%, so the description needs to compensate. It explains the strategy parameter well by defining ours, theirs, edit, and union. The required concept_id parameter is not described in either the schema or the description, leaving a significant 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 states a specific verb and resource: 'Resolves a git conflict.' It is clearly distinguishable from sibling tools and directly references conflicts_list, which is the relevant companion tool for identifying open conflicts.

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

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

The description gives clear context by stating that the tool is used once every open conflict from conflicts_list is resolved, and it explains the four strategy options. It does not explicitly state when not to use the tool or name alternative resolution paths, but the usage context is highly inferable.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds genuine behavioral context beyond that: bidirectional link traversal and that results include hop count and the concept each was reached through. It still omits traversal depth bounds and pagination 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?

A single front-loaded sentence with no filler, though the trailing 'with hop count and the concept each was reached through' is slightly clunky in phrasing.

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 3-parameter tool with no output schema and no annotation coverage of return shape, the description partially fills the gap by describing output metadata (hop count, path concept). But it leaves the limit parameter, traversal depth, and differentiation from graph_neighbors unaddressed.

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 must compensate and only partly does: 'a question or set of concepts' loosely maps to query and ids but never states this pairing explicitly, and 'limit' is entirely undocumented in both description and 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 explains the tool returns concepts related to a question or concept set by traversing links bidirectionally, and mentions hop count and path metadata. However, it's a noun phrase without an explicit verb ('Find'/'Retrieve'), and it never names or contrasts itself with the obvious sibling graph_neighbors, leaving the boundary between the two to inference.

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 implies a use case ('to a question or set of concepts') but gives no explicit when-to-use, when-not-to-use, or alternative. With graph_neighbors and concept_expand in the sibling list, the absence of any routing guidance is a real 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 readOnlyHint and idempotentHint annotations already establish the safety profile, so the description adds useful traversal semantics: default depth and the meaning of out, in, and both. It does not describe limits, pagination, or what shape the returned neighborhood takes, leaving some behavioral context unstated 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?

The description is a single, front-loaded sentence that introduces the tool before explaining the direction modes. Every clause earns its place, with no filler 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?

For a simple read-only traversal tool with no output schema, the description gives enough to call it correctly in most cases: it covers depth default and direction semantics. The main gap is the unstated meaning of the required id parameter, but the annotations already handle safety and the core behavior is otherwise clear.

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 must carry parameter meaning. It does well on direction, defining each enum value, and on depth by stating the default, but it says nothing about the required id parameter beyond its name, leaving one of three parameters semantically underspecified.

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 resource (graph neighbors) and the traversal scope (up to depth hops, with direction modes). It does not, however, distinguish this tool from a related sibling such as graph_context, so an agent still has to infer when this specific neighbor query is preferable.

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 defines the direction values and the default depth, which helps with invocation but is parameter guidance rather than tool-selection guidance. It provides no explicit when-to-use, when-not-to-use, or alternative-tool routing against siblings like graph_context or search.

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

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

Annotations already declare readOnlyHint=true, and the description adds real behavioral detail beyond them: the >60 KB outline downgrade, the override via full/with_hash, and the exact with_hash return shape {path, content, content_hash}. idempotentHint=false is unusual for a read but the description does not contradict it.

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

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

It is short and front-loads the core purpose, but the telegraphic fragments ('Over 60 KB: outline, unless full or with_hash; outline: true forces it') are dense and slightly ambiguous to parse in one read. Nothing is wasted, but structure could be clearer.

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?

Annotations cover the safety profile and there is no output schema, so the description needn't explain returns. It covers the default read, the large-file fallback, and the with_hash variant, but leaves the outline's return format and the plain (non-hash) return shape implicit.

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 0% schema coverage the description carries the burden and largely succeeds: path defaults to root, with_hash alters the return contract, outline forces outline mode, and full overrides the size-based downgrade. Only 'full' is left to light inference from its name and the 'unless full' clause.

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

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

States a specific verb and resource ('Reads a folder's index.md') and clarifies the root-default scope, which distinguishes it from the sibling index_patch and the broader concept/map readers. It's clear what is read, though it doesn't explicitly contrast with other read tools in the family.

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

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

It hints at usage via the tie-in to index_patch ('with_hash ... if_match for index_patch') and the outline fallback, so an agent can infer when to ask for the hash. However, there is no explicit when-to-use-this-vs-alternatives statement or exclusion 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?

With no annotations, the description carries the full burden and does reasonably well: it discloses the optimistic-concurrency requirement (if_match), a refusal condition with its error code, and the return payload (path, content_hash, replacements, findings). It omits permission/auth needs and whether edits are atomic, leaving some behavioral gaps.

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 compact sentences that front-load the analogous tool and the target resource, then cover prerequisites, exclusions, and return values. Dense but every clause earns its place; the 'Like concept_patch' dependency is the only minor cost.

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 mutation tool with no annotations, no output schema, and 29% schema coverage, the description covers routing, concurrency, error handling, and returns, but leaves several parameters (edits shape, reason, replace_all) under-explained. Adequate but with clear 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?

Schema coverage is only 29%, so the description must compensate. It documents if_match's origin and defers edit-form semantics to concept_patch ('same edit forms'), but says nothing about edits structure, replace_all, or reason beyond the schema's brief hints. Partial compensation only.

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 (patch) and resource (root or Map/Journal curated index.md) and explicitly distinguishes itself from concept_patch for expanded-concept indexes. The reliance on 'Like concept_patch' means the agent must know what that sibling does, so it is clear but not fully self-contained.

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

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

Names the prerequisite (if_match from index_get with_hash) and the exclusion case (an expanded concept's own index.md is refused with expanded_index), routing to concept_patch. Clear context and a named alternative, though it doesn't spell out the full when-to-use conditions for every index type.

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

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

With no annotations, the description carries the full burden and does well: it discloses that this is a mutation ('KB-wide in one commit'), that dry_run defaults to true as a plan-only mode, and that concepts changed since listing are skipped (staleness/concurrency handling). It omits any statement of required write permissions, but the safety-relevant behavior is otherwise unusually well covered.

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

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

Four tight sentences with no filler, front-loading the action before the dry-run default, staleness rule, and the routing note. Every clause conveys distinct 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 mutation tool with no annotations and no output schema, it covers the essential behaviors (atomic commit, safe default, staleness skip, alternative tool). The remaining gap is the undocumented `limit` and `scope` parameters, which leave the agent unable to reason about scoping.

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 only 40% (reason and dry_run are documented), so the description must compensate. It clarifies that `check` selects 'one check' and that the operation is 'KB-wide', which adds meaning. However, `limit` and `scope` are undocumented in both places, and 'KB-wide' arguably sits in tension with an unexplained `scope` parameter.

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

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

States a specific verb and resource: it 'applies the mechanical fix a lint finding carries' across the KB. It implicitly differentiates itself from the sibling `lint` (which surfaces findings) by being the actor that applies the carried `fix`. The parenthetical '(fix)' assumes the reader already knows lint findings expose a fix field, which is a mild dependency but not enough to obscure the 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?

Routes the agent away from judgement-type fixes with an explicit alternative: 'Judgement fixes: kb-doctor skill.' Combined with the implied workflow (this consumes a lint finding's mechanical fix), it gives clear when-to-use and when-not guidance. It stops short of stating whether `lint` must be run first or how to obtain the check identifier.

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 and idempotentHint=false, so the read-only nature is already covered. The description adds an item field list, but the 'Dismiss' clause is cryptic — it is unclear whether this tool performs the dismissal or merely documents the lint_ignore convention, which is exactly the kind of ambiguity an agent needs resolved. No pagination or ordering behavior is explained.

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?

Very short, but terse to the point of being cryptic: two sentence fragments with no subject, and 'kb-doctor' and the Dismiss clause are unexplained. Brevity here reflects under-specification rather than efficiency.

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

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

No output schema, no enum hints, and 0% schema coverage, so the description must carry the burden — yet it omits what the ranking means, how paging works, and what Dismiss actually does. For a four-parameter tool with no required fields this is inadequate.

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% for all four parameters (kind, limit, scope, offset). The description only loosely gestures at 'kind' (as an item field and inside lint_ignore) and never mentions limit, offset, or scope, so the parameters remain effectively undocumented.

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?

"Ranked kb-doctor work list" names a resource and a ranking behavior, and the item shape {kind, concepts, evidence, suggested_action} is disclosed. But it never states what this tool does in plain terms (return a prioritized list of kb issues?) and doesn't distinguish itself from siblings like work_list, lint, or kb_repair.

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?

No guidance on when to call this versus work_list, lint, or kb_repair. The only procedural note is about dismissing items, which is a downstream action rather than a use case for invoking this tool.

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

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

With readOnlyHint=true already in the annotations, the closing 'Read-only.' repeats structured data and earns no credit. The description does not disclose cost, output size, pagination, or whether a full-health scan is expensive, and idempotentHint=false is left unexplained.

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?

Content is dense but largely non-redundant, since every clause names a real output section, and 'KB health in one call' is front-loaded. However, it is delivered as one ~70-word comma-spliced run-on, and the trailing 'usage:' fragment reads like a stray header rather than prose.

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

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

No output schema exists, so the description carries the burden of describing returns, and it does so thoroughly: counts, staleness, contradictions/gaps, git state, per-KB capability gates, ledger counts, search misses, versions, and conformance findings. The main omission is any sense of cost or expected size for what is effectively a full-KB aggregate scan.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond the empty schema, and it does not mislead about inputs.

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 resource ('KB health') and enumerates its contents in detail, but never states an action verb such as 'get' or 'report'. It also never differentiates this tool from adjacent read tools like kb_repair, kb_review, conflicts_list, or validate. An agent can infer the intent, but the phrasing is a noun fragment rather than a crisp verb+resource statement.

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 only conditional guidance is 'When doctor_suggested is true, follow the kb-doctor skill', which governs what to do with the output rather than when to call kb_status at all. There is no statement of when to use this versus kb_repair, kb_review, conflicts_list, or validate, and no prerequisites are given.

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 readOnlyHint annotation, the description reveals the ranking logic: suggestions require at least two shared neighbours, exclude already-linked concepts, discount hub evidence, and fall back to title matching for unlinked concepts. That is genuinely useful behavioral context. It stops short of stating return shape or ordering, so not a 5.

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

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

It is a single, front-loaded sentence with no filler. However, the telegraphic, semicolon-joined heuristic is dense enough that it takes a second read to parse, which slightly undercuts readability.

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 no output schema and no parameter documentation, the description carries the heuristic well but leaves two important gaps: what the caller receives (a ranked list of concept suggestions) and what 'limit' bounds. Minimum viable, 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 neither parameter is documented in the schema. The description never mentions the required 'id' (only the vague 'this one') or the optional 'limit', so an agent must guess what each parameter controls. The description does not compensate for the coverage 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 states a concrete function: propose 'existing concepts this one probably should link to', which is a specific verb+resource for a link-recommendation tool. It implicitly separates itself from graph_neighbors (existing links) and concept_expand, but never names an alternative, so the differentiation is inferential rather than explicit.

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

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

It describes the selection criteria ('at least two shared neighbours, not yet linked, hub evidence discounted; for an unlinked concept, title matches'), which implies when suggestions will be produced. However, it gives no explicit when-to-use-this-vs-alternatives instruction and no prerequisites, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral note — that counts ignore the filter/page parameters — but says nothing about what checks run, what severity levels mean, or what the response contains (no output schema).

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

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

It is short, but telegraphic to the point of ambiguity — "Counts ignore them" leaves the referent of "them" to inference, and the opening sentence does no descriptive work. Brevity here reflects under-specification rather than disciplined concision.

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 6-parameter tool with no output schema and minimal annotations, the description leaves too much unstated: what is linted, what checks are available, what the counts refer to, and how scope interacts with check. It is not sufficient for an agent to invoke this confidently.

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

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

With only 33% schema description coverage, the description should compensate, and it partly does by naming check, severity_min, limit (max 200), and offset. However it omits `scope` and `scope_neighbors` entirely, and the "max 200" constraint is the only real value-add; "offset filter and page" is too vague to disambiguate the two paging 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?

"Deterministic checks." describes a property of the operation rather than stating what the tool actually lints or returns. There is no clear verb+resource pairing, and it does not distinguish itself from the sibling `validate`, which an agent would plausibly confuse it with.

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 no when-to-use context, no prerequisites, and no mention of alternatives such as `validate`. An agent gets no basis for choosing this tool over its obvious sibling.

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

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

No annotations are provided, so the description carries the full burden. It does disclose a genuinely non-obvious behavior: path does not create a per-directory log, it only prefixes the entry in the root log, and entries are ordered newest first. It does not cover failure modes, permissions, or whether entries are durable/atomic, which keeps it short of a 5.

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

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

Two dense sentences, zero filler, with the core action and target front-loaded and the path caveat and read-back pointer following immediately.

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

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

For a simple append tool with no output schema, the description covers what it does, where it writes, and how to read it back. It stops short of describing the return value or confirmation behavior, which an agent calling it blind might want to know.

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 67% and the required 'entry' parameter has no schema description at all. The description compensates for the most confusing parameter by explaining that path results in a '[<path>] ' prefix in the root log rather than a separate log, which is meaningfully more than the schema's 'Optional folder prefix'.

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 (appends) plus the exact target resource (root log.md) and its ordering convention (newest first). It also explicitly names the read counterpart, log_tail(path), so an agent can separate this write tool from the sibling that only reads.

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?

Tells the agent how to retrieve what it wrote ('read back with log_tail(path)'), which effectively routes the read case to the alternative. There is no explicit when-not-to-use statement (e.g. that this is root-level only, never per-directory), but the context 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 already establish readOnlyHint=true, but the description adds genuine behavioral context beyond them: the default of 20 entries, that empty path means root log, and the exact filtering rule for prefixed entries plus pre-existing <path>/log.md. It does not contradict the annotations.

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

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

Two dense clauses, front-loaded with the core behavior (last n entries, default 20) before the path-filter detail. Every clause earns its place with no filler.

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

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

For a read-only tool with no output schema, the description covers inputs and filtering behavior adequately, but it omits the return shape (e.g. formatting of entries) and any pagination or size limits that would help an agent use the result confidently.

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

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

With 0% schema description coverage, the description must carry the load and largely does: it defines n's default (20) and both the empty and non-empty semantics of path, including the '[<path>] ' prefix filter. The remaining gap is minor, e.g. bounds or type constraints on n.

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 gives a specific verb (tail/return last entries) and resource (log entries for a path), and clarifies the default count and the empty-path case. It is clear on its own, though it never names the obvious sibling log_append to differentiate read-vs-write.

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 explicit when-to-use or when-not-to-use guidance, and no mention of alternatives such as log_append. Usage is only implied by the read semantics, leaving the agent to infer 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?

With no annotations, the description carries the full burden. It does add genuinely useful disclosure: the set of files created, that ontology_mode strict 'enforces concept_types', and notably that contract options are 'lint only, not a write gate'. It still omits permissions, name-collision/reversibility behavior, and side 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?

Compact and front-loaded, leading with the core action before secondary options. The telegraphic phrasing ('templates (slugs) make every page follow one') is dense but wastes no sentences.

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 15-parameter creation tool with nested objects, no output schema, and no annotations, the description is too terse to be complete. Most parameters and the semantics of the contract/template system are left undocumented.

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 only 7% (just 'reason'), so the description must compensate. It explains kind (journal), ontology_mode (strict/flexible), and templates (slugs), but leaves the majority of the 15 parameters (field_values, concept_types, required_fields, forbidden_fields, machine_path_allow_prefixes, the *_by_type maps) 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?

Names a specific verb and resource ('Creates a Map or Journal') and defines what gets produced (_map.md, index.md, log.md), so an agent can distinguish it from map_delete/map_list/map_update. However, it doesn't clarify how a Map differs from a Journal beyond 'kind: journal', nor how it relates to concept_new.

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 explicit when-to-use or when-not guidance, and no routing to alternatives (map_update, concept_new). The kind and ontology_mode mentions imply some selection criteria but leave the agent to infer them.

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?

No annotations, so the description carries the load, and it does disclose the key traits: a precondition guard, a no-op outcome ('nothing changes') on failure, and an error that enumerates the blocking concepts. It omits recovery/permission or irreversibility details, but the failure-mode disclosure is strong for a mutation 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?

Two tight sentences, front-loaded with the precondition, then the failure behavior and the remedy. Every clause carries information and there is no filler.

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

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

For a no-annotation, no-output-schema mutation tool this covers the critical path: precondition, no-op failure semantics, and the follow-up tool. Minor gaps remain around the 'map' identifier and any auth requirements, but an agent can call it correctly as written.

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 50%: 'reason' is documented in the schema, 'map' is not. The description contextualizes what 'map' refers to but adds no format or identity details, and says nothing about 'reason' beyond what the schema holds, so it neither compensates for the gap nor falls below the boundary baseline.

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

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

States a specific verb (Deletes) and resource (Map or Journal) with an explicit scope qualifier (only if empty). It reads clearly against map_create/map_update/map_list siblings because it names the exact deletion guard.

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

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

Gives an explicit when: only invoke on an empty map (just the scaffold files). Gives the when-not and the alternative: if not empty, nothing changes and concept_move must be used first. Nothing is left to inference.

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

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

Annotations declare readOnlyHint=true, covering the safety profile, and the description adds the returned field set. It does not disclose volume, ordering, pagination, or whether results are cached, which is relevant for a listing 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?

One tight sentence, front-loaded with the verb and resource with zero filler. Every clause (fields returned) 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-param read-only lister, annotations and the schema cover most of it, and no output schema exists so the return field list is a useful addition. But with 40+ siblings and no output schema, a brief statement of result shape/pagination would make it 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?

Zero parameters, so baseline is 4. The description correctly signals the tool is parameterless by not claiming any filtering options.

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?

Clear verb (Lists) plus resource (Maps and Journals) and even enumerates returned fields. It distinguishes itself from map_create/map_delete/map_update by naming all of them via the map_ prefix, though it does not explicitly contrast with 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?

No when-to-use guidance, no exclusions, no mention of alternatives among the many siblings. The agent must infer that this is the discovery/listing entry point.

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

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

With no annotations, the description carries the full burden and does disclose genuinely useful mutation semantics: keys are 'replaced whole' and empty list/""/false/{} removes a key, plus the stale_after 0/-1 sentinel meaning. However, it is silent on permissions, reversibility, and how the remaining ~33 parameters behave, leaving significant behavioral gaps for a 35-parameter mutation.

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 with no filler. Content is efficient, though the jargon 'lint contract' borders on cryptic given no term definition.

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 35 parameters, 3% schema coverage, no output schema, and no annotations, the description is far too thin. It leaves the agent unable to infer what most configuration fields do or what the tool returns after a mutation.

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 only 3%, so the description must compensate, but it only explains the generic replacement/removal rule and the stale_after sentinel. The vast majority of the 35 parameters (ontology_mode enum, nested objects like field_values_by_type) are undocumented in both schema and description.

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

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

States a specific verb ('Changes') and resource ('a map's title or lint contract'), so an agent knows this mutates an existing map's configuration rather than creating or deleting one. It is clear but offers no explicit differentiation from sibling map tools like map_create or map_delete beyond the verb.

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?

No when-to-use, when-not-to-use, or alternative tooling guidance is given. The description explains some field semantics but never tells the agent under what conditions this tool should be selected over map_create or map_delete.

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

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

Annotations already cover the safety profile (readOnlyHint=true), and the description adds genuinely useful behavior beyond them: the backing engine (SQLite FTS5), the matching mode (substring), the ordering guarantee (ranked by relevance), and the fact that glossary aliases are searched via expanded_to. It stops short of noting pagination, result caps, or how the ranking is computed.

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 clauses with no filler, and the core purpose is front-loaded ahead of implementation detail. The parenthetical engine note is slightly incidental but still earns its place as a matching-behavior hint.

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

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

For a 5-parameter search tool with no output schema and 0% parameter coverage, the description should explain the scope/filter parameters and what limit and include_archived do. It explains only the query side, leaving an agent unable to safely use four of the five inputs.

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% for 5 parameters, so the description carries the full burden and largely fails it. It conveys only query semantics (keyword/substring, alias expansion); limit, scope, record_miss, and include_archived are left completely undefined in both schema and description.

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

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

States a specific verb and resource ('keyword search over concepts') plus the return type ('returns IDs ranked by relevance'), so the agent knows exactly what it gets back. It does not, however, differentiate itself from adjacent retrieval siblings like concept_list, concept_read, or graph_context, so an agent must infer which retrieval path to take.

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

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

Usage is only implied by 'keyword search' — no explicit when-to-use, no when-not-to-use, and no alternatives named. With siblings such as concept_list, concept_expand, and graph_context offering overlapping retrieval, the absence of routing guidance is a real 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?

With no annotations, the description carries the full behavioral burden, and it does disclose one meaningful trait: a git commit occurs only when auto-commit is enabled. However, it omits what the snapshot entry contains, where it is written, whether the operation is reversible, and what the response looks like, so key traits for a state-mutating tool remain undisclosed.

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 dense sentence with no filler, and the primary action is front-loaded before the conditional git behavior. It is lean without being a bare label.

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?

In a large sibling set with two parameters, no output schema, and no annotations, the description should explain when to snapshot and what is recorded. It leaves the agent guessing about scope, idempotency, and the effect of each optional parameter.

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

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

Schema coverage is only 50%: 'reason' is documented as a commit trailer while 'message' has no description at all. The description adds nothing about either parameter (it never explains how 'reason' or 'message' shape the snapshot), so it fails to compensate for the coverage 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?

States a specific verb and resource ('Logs a KB snapshot entry') plus a conditional side effect (a git commit), so an agent knows exactly what operation this is. It does not distinguish itself from nearby siblings such as log_append or kb_repair, which is the only gap.

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?

Nothing tells the agent when to call snapshot rather than log_append, kb_repair, or kb_status, nor what prerequisites (a KB, git auto-commit config) must be in place. Usage must be inferred entirely from the tool name.

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

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

Annotations already cover readOnlyHint=true, and the description repeats 'Read-only', which adds nothing new. However, since there is no output schema, the description carries real weight by disclosing the returned field set including cited_by counts and cited_by_ids provenance links, plus the default status filter 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?

A single dense sentence front-loads the resource and ordering before the field list, and the status default follows immediately. No wasted prose, though the parenthetical asides make it slightly hard to scan.

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 list tool with no output schema, describing the returned fields is the right instinct and mostly done. Gaps remain around the meaning of scope, any limit/pagination semantics, and what happens beyond the pending default, which the description leaves to the agent to guess.

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 one of three parameters is explained: status, with its default and the '*' wildcard clearly stated. Neither limit nor the vague scope parameter is described in the description despite only 33% schema coverage, so the compensation is partial.

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

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

The description names the resource (source ledger / Source concepts) and implies listing via the field shape and 'oldest first' ordering, so the agent knows this enumerates sources in order. It never explicitly contrasts with siblings like source_register or search, so differentiation relies on inference.

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

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

It gives one useful operational rule, that status defaults to pending and '*' returns all, which implies how to widen a query. There is no statement of when to prefer this over alternatives such as search or concept_list, and no 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?

With no annotations, the description carries the full burden and delivers: dedup order (sha256, else locator), the exact duplicate return shape ({id, duplicate: true, ingest_status}), that nothing is written, that locator_mismatch + existing_locator are added on divergence, and 'Never fetches.' This is unusually rich side-effect and return disclosure.

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

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

Front-loaded with the core action ('Records a primary source BEFORE ingesting it') before the dense dedup/workflow detail. The sentences are information-packed with little waste, though the jargon-heavy clause structure is somewhat dense to parse.

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 9-param tool with no annotations and no output schema, the description covers dedup, duplicate-return shape, write behavior, and the downstream workflow. Minor gaps remain around the required title/source_kind params, but an agent has enough 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?

At 56% schema coverage, the description compensates for key params: it specifies map's default ('sources'), clarifies body ('your distillation'), and explains sha256/locator as the dedup keys with locator_mismatch behavior. It leaves the required title and source_kind undocumented anywhere, but adds genuine meaning beyond the schema for the parameters that drive behavior.

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

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

States a specific verb+resource: 'Records a primary source BEFORE ingesting it: a Source concept in a journal.' The dedup and workflow clauses reinforce exactly what the tool does. It doesn't explicitly name which sibling (e.g. concept_new) to avoid, but the source-specific purpose is clearly distinguishable.

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

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

Gives clear timing context ('BEFORE ingesting it') and orders the workflow ('Cite its ID in provenance, then concept_patch ingest_status'). It provides strong usage context but does not name when-not to use it or explicitly contrast with alternatives like concept_new.

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

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

Annotations are absent, so the description carries the burden. It discloses the state mutation (status=superseded) and the side effect of recording a successor, and notes it returns findings. It does not say whether the action is reversible, whether it requires the target to pre-exist, or the shape of 'findings'.

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 lean sentence covering the action, the state change, and the return. No wasted words, though the terse 'Returns findings on it' is slightly vague.

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?

Adequate for a 3-parameter mutation tool but thin: no annotations, no output schema, and no detail on irreversibility, target existence requirements, or the returned findings. It leaves real gaps an agent would want filled.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description confirms the roles (source superseded, successor recorded) but adds no syntax, format, or constraint 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?

Clear specific verb+resource ('marks a concept as superseded'), and it explains the mechanic (sets status=superseded, records successor). It does not explicitly differentiate itself from close siblings like concept_patch, which could plausibly achieve the same status change, so it stays at 4 rather than 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?

No when-to-use or when-not-to-use guidance. It does not state whether this is preferable to concept_patch or concept_delete, nor any prerequisites (e.g. does the successor need to exist already).

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful behavioral context beyond that: it discloses what the call returns (the four fields) and that bodies are not included, routing the agent to artifact_read instead. Minor omission is whether the list is ordered or filtered.

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 short sentences, no filler, with the primary purpose front-loaded before the pointer to the sibling tool. Every clause carries information.

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

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

With no output schema, the description does the necessary work of naming the returned fields and clarifying the metadata/body split. Adequate for a zero-arg listing tool; only ordering or scope-of-list details are absent.

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

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

Zero parameters, so per the rubric the baseline is 4. The description correctly implies no filtering or paging inputs are available, matching the empty schema.

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

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

Specific verb ("Lists") plus a scoped resource ("KB-only concept templates") and an enumeration of returned fields (slug, type, title, variables). The "KB-only" qualifier separates it from the generic concept_list sibling, though it never names that sibling directly.

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?

"Read a template body with artifact_read" implicitly defines the boundary: this tool returns metadata only, and body retrieval goes elsewhere. Clear context for follow-up, but no explicit guidance on choosing between this and concept_list/map_list for other listing needs.

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

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

Annotations declare readOnlyHint=true, so the agent knows it is a safe read, and the description adds that it checks three specific categories and returns errors. However, it doesn't explain what 'strict ontology' entails, whether it aborts early, or error format/severity. The idempotentHint=false annotation is somewhat surprising for a pure validation read and the description doesn't clarify why.

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?

Single concise sentence with the checked resources front-loaded and the return behavior appended. Minimal and readable, though it could better front-load the primary subject.

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 sitting among many related validation/inspection siblings, with one undocumented parameter and no output schema, the description should clarify scope semantics and where it fits. As written, an agent cannot confidently know what scope to pass or how this differs from lint/gate_check.

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?

One parameter ('scope') with 0% schema description coverage and no mention in the description. The description says nothing about what scope is, its allowed values, or what happens if omitted (it is not required). With no schema documentation to lean on, 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?

States a specific verb ('validates') and the resources it checks (frontmatter, reserved files, strict ontology), and mentions a return ('returns the errors'). It stands apart from siblings like lint or kb_review, though 'validate' is generic and it doesn't explicitly disambiguate what 'validate' means versus 'lint'/'gate_check' in the sibling set.

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?

No indication of when to use this tool versus lint, kb_review, kb_status, or gate_check, which all occupy a similar validation/inspection space. The description neither names alternatives nor states preconditions or when-not-to-use.

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?

Reinforces the readOnlyHint annotation ('Read-only') and adds useful context beyond it: identifies concept_patch as the mutation path and discloses that results include section and line info. Since there is no output schema, this output-content detail is valuable, though pagination/error behavior is untouched.

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?

Compact and front-loaded, leading with the definition of open work before the operational notes. The 'where as in concept_list' shorthand is efficient but slightly cryptic.

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?

Covers the read-only nature and the shape of returned work items, which matters given no output schema, but with 8 undocumented parameters and no annotations explanation of scope/pagination, an agent still lacks enough to invoke it precisely.

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 0% schema coverage across 8 parameters, the description must carry the load, but it only touches where, fields, and order_by (noting they follow frontmatter keys as in concept_list). limit, offset, scope, stale, and the include enum are entirely 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?

States a specific verb (list) and resource (open work), then defines what 'open work' means concretely: concepts in an open status and unchecked '- [ ]' items with section and line. It distinguishes itself from concept_list by scoping to open status/unchecked items, though the phrasing is dense.

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?

Implies the use case (finding open work) and routes mutations elsewhere via 'change work with concept_patch', but never explicitly contrasts when to call work_list versus concept_list, which it references for parameter semantics. Usage is inferable but not spelled out.

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