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

Beyond the destructiveHint/readOnlyHint annotations, it discloses a lot: links are rewritten to warn afterwards (archived_link), status is untouched, a whole bundle keeps its log.md and its index.md stops declaring a bundle, the archive bundle is auto-created, and the archive is read-only to editing tools. That is exactly the kind of side-effect disclosure an agent needs before a destructive 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?

The verb and scope are front-loaded and no sentence is purely filler, but the text is a dense run-on punctuated with spec-section markers (§8) and stray notation that add noise rather than agent-relevant meaning. It could be split into a purpose sentence plus discrete behavior bullets.

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

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

For a destructive, non-idempotent, no-output-schema tool with three undocumented parameters, the description covers the important ground: what moves, where it lands, what happens to links and indexes, and the dry-run mode. It lacks conflict/error behavior and the exact shape of the plan/diff, which keeps it short of 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%, so the description carries the full burden, and it does explain all three: `file` selects a concept, omitting it archives the named bundle, and `apply=False` previews versus executing. The garbled "(no file) the whole bundle= named" phrasing and the unexplained empty-string defaults keep this from being fully clear.

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 concrete operation (moving a concept or a whole bundle into the `archive/` bundle) and explicitly references the inverse sibling `unarchive`, so the agent can distinguish the two. The opening clause is garbled ("or (no file) the whole bundle= named"), which slightly obscures the subject but the intent is still recoverable.

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 workflow hint — `apply=False` shows the plan and diff — and points to `unarchive` for reversal, implying a preview-then-commit pattern. However, it never states when to prefer `archive` over siblings like `move`, nor any preconditions or exclusions, so the guidance is implied rather than explicit.

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

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

Annotations declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is already given. The description adds real value by explaining that a snapshot file is written, that its path is relative to the knowledgebase, and that `apply=False` only counts rather than writes. It does not say whether an existing snapshot is overwritten or how the file is consumed later.

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 is front-loaded in the first clause, which is good. However, the middle sentence is compressed into near-unparseable shorthand ('same bundle and `all`, and like lint it defaults to where the user is'), trading clarity for brevity and forcing the agent to unpack it.

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

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

With four undocumented parameters, no output schema, and only generic annotations, the description needs to be self-sufficient. It covers the write behavior and two parameters reasonably but leaves `all`/`bundle` semantics and the snapshot lifecycle (overwrite behavior, how CI consumes the file) unspecified.

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

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

Schema description coverage is 0%, so the description carries the burden and only partially discharges it: `path` is explained as relative to the knowledgebase and `apply=False` as count-only, which is genuinely useful. But `all` and `bundle` are explained only by analogy ('same bundle and `all`... like lint it defaults to where the user is'), which is opaque without knowing `lint`'s semantics.

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

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

The first clause gives a concrete verb and resource: 'Snapshot today's lint findings so CI fails only on new ones.' It also distinguishes the tool from the sibling `lint` by naming the invocation form `lint baseline=<path>`. The parenthetical is dense and the relationship to `lint` (separate tool vs. flag) is slightly ambiguous, which keeps it from a 5.

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

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

'For adopting OKF on a large existing collection' gives a clear adoption scenario for when to reach for this tool, and pointing at `lint baseline=<path>` implies the alternative (running plain `lint`). It stops short of explicit when-not-to-use guidance or naming other siblings like `verify` or `fix`.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description does add one genuinely useful behavioral trait beyond that: detection silently misses bundles lacking the okf_version declaration, plus a workaround. However, it says nothing about scan scope (cwd? recursive? depth), what is returned, or why §12 matters.

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-loaded, but dense with unexplained jargon ("okf_version", "§12") and written in fragments rather than complete clauses. No sentence is wasted in length, yet the first sentence earns little because it describes the domain object instead of the action.

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

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

With no output schema, the description must explain what the agent gets back — a list of bundle root paths? — and it does not. For a discovery tool with an optional parameter defaulting to empty, the agent can't predict behavior at the default, and the §12 citation points at documentation the agent cannot see.

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

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

Schema description coverage is 0%, so the description carries the burden for the single optional 'bundle' parameter. "Pass it as bundle= directly" conveys that the param takes a path to a bundle root that bypasses detection, which is real added meaning, but the default empty string and its semantics (cwd? all?) remain unexplained.

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

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

The description is a noun fragment ("Bundle roots under a directory") with no verb, so it never states whether the tool lists, validates, or creates bundles. It spends more words defining what a bundle is (an index.md declaring okf_version) than saying what the tool does, and it doesn't distinguish itself from siblings like list, index, or search.

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

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

The only guidance is the cryptic note that an undeclared bundle "looks like any folder; pass it as bundle= directly," which hints at a fallback path but never says when to call this tool versus list/search/index. There are no exclusions or preconditions an agent can act on.

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?

Adds real behaviour beyond the annotations: the call mutates the document body ('its definition is appended to the body') and is upsert-like ('Reusing an id replaces that entry'), and it explains what the call returns. The replace-on-same-id semantics sits in mild tension with idempotentHint=false, but this is a nuance rather than an outright contradiction.

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?

Purpose and return value are front-loaded, and most clauses carry unique information (how to build `resource`, credibility signals, stale window). The unusual line-wrapping and undefined '§5.1' / 'via' jargon cost some clarity without adding filler, so it is dense but not padded.

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

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

For a 12-parameter mutation tool with no output schema, it does well to state the return value and the body-append side effect. The gap is coverage completeness: the required `file` target and a few optional fields go unexplained, so an agent still has to infer what identifies the destination document.

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% across 12 parameters, so the description carries the load: it explains server, tool, args, resource, author, usage_count, last_modified and stale_days>0. However the sole required parameter `file` is never mentioned, nor are `title` or `bundle`, and it references a `via` field that does not exist in the schema, which can mislead.

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

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

Opens with a specific verb+resource: 'Record where a fact came from as a §5.1 sources entry', and adds the return value (a footnote marker to place after the claim). It is clearly distinguishable from siblings like `search` or `lint`, though it never explicitly contrasts with near-neighbours such as `provenance` or `record`, and the §5.1 spec reference is opaque without external context.

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

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

Gives conditional routing: 'When an MCP tool produced it, pass server, tool and args' and 'resource: a real URL when the result has one, else mcp://server/tool?args'. It also ties itself to the sibling `recheck_plan` ('it is the re-check recipe'). It lacks explicit when-not-to-use guidance or a comparison to other provenance-style siblings.

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

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

Annotations already declare a non-readonly, non-destructive, non-idempotent, closed-world write, so the bar is lower. The description still adds genuine traits beyond them: refusal on existing files (so no upsert), refusal of reserved names (index.md, log.md), an automatic `# title` heading unless the body already opens with one, and a `generated {by, at}` block injected when `by` is supplied.

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, then field enumeration, then behavioral caveats. Dense but every clause carries information; the '§4.1' spec reference is the one piece that adds little for an agent without the document.

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 10-parameter mutation with no output schema and no per-parameter schema documentation, the description covers the frontmatter contract well but leaves gaps: `bundle` is entirely unaddressed, `file` path handling is unstated, and nothing indicates what is returned (path, content, or confirmation) so the agent cannot plan follow-up calls.

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% across 10 parameters, so the description must carry the load, and it does for most: type, title, description, resource, tags, status, body, and by are all given meaning in the frontmatter model. Two parameters remain opaque — `bundle` is never mentioned and `file` (path semantics, relation to bundle) is only implied by the refusal 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: 'Create a concept with valid OKF frontmatter (§4.1)'. That distinguishes it from sibling mutations like set, rename, archive, or ingest. The only weakness is domain jargon ('concept', 'OKF'), which an agent unfamiliar with the bundle model must infer.

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 rather than stated: 'Refuses an existing file or a reserved name' tells the agent this is create-only and cannot overwrite, which implicitly routes updates to siblings like set or fix, but no alternative is named. There is no explicit when-to-use/when-not guidance and no prerequisites (bundle initialization, required type values).

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 a non-read-only, non-destructive, idempotent mutation, and the description adds genuinely new behavior: apply=False is a diff-only dry run, apply=True writes, then re-lints and returns a `remaining` field, with CLI exit-code semantics in both modes. The default scope (current location plus every bundle there, narrowed by all=false) is also disclosed. It stops short of saying what happens to partially-fixed files when re-linting still reports errors.

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 scope statement ('nothing that needs judgment') followed by an enumerated list, then a second paragraph on modes and scope. Dense with zero filler, though the bare §8/§9 references are opaque to an agent without the spec, and the two paragraphs mix enumeration, mode semantics, and scope defaults without headings.

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 three-parameter mutation tool with no output schema and no annotation detail beyond hints, the description covers mode semantics, return field (`remaining`), exit-code behavior, and default scoping. Remaining gaps: an unclear `bundle` parameter and no statement about atomicity or what state files are left in if re-linting fails.

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%, so the description must carry all parameter meaning, and it largely does: `apply` is fully explained via the false/true contrast, and `all=false` is defined as keeping to a single bundle with the default being all bundles at the current location. `bundle` itself is only inferable from that sentence rather than defined, which keeps this below 5.

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

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

Opens with a specific verb framing ('Mechanical repairs, nothing that needs judgment') and then enumerates the exact operations: stripping frontmatter from index.md, rebuilding index lists, normalizing tag spellings, reordering log.md sections. This is far more specific than the bare name 'fix' and implicitly separates it from the detection-oriented 'lint' sibling, though it never names an alternative outright.

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 rather than stated: the mention 'after a merge (§9)' hints at when log reordering applies, and 'Like lint, it defaults to where the user is' borrows context from a sibling. But there is no explicit statement of when to run fix versus lint (detect vs repair), no prerequisite guidance, and no when-not-to-use clause.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description correctly spends its words elsewhere: it discloses that a missing index.md is synthesized from frontmatter and flagged with `synthesized: true`, which is behavior an agent could not predict. Paging semantics (offset/limit by line, limit=0 = all) add further non-obvious context. It stops short of stating what a missing non-index file 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?

Three short, front-loaded statements with no padding, which is good. But the compression tips into opacity: the '§8' cross-reference is meaningless to an agent and the parenthetical field lists read as notes for an internal reader rather than a tool contract.

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

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

No output schema exists, yet the description still conveys the key return shapes (one file, many files, synthesized index) and paging controls. The unexplained `bundle` parameter and the undefined behavior for a nonexistent requested file are the remaining gaps, but they are narrow for a simple 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 0%, so the description carries the full burden. It explains file, files (batch), offset/limit paging and the limit=0 sentinel, but the `bundle` parameter – arguably the most important one, since it scopes every lookup – is never mentioned anywhere in either the schema or the description.

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

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

The description states the resource precisely – one .md file of a bundle (concept, index.md, log.md), or several via files=[...] – which distinguishes retrieval from siblings like list and search. The verb itself is only implicit in the tool name 'get', but the scope and granularity 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?

It implicitly covers the single-vs-batch choice ('or several at once with files=[...]'), but never says when to use this over search, list, or links, nor what happens when the requested file is absent (other than the index.md case). Usage is inferable rather than stated.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context the annotations cannot provide: the data comes from git history via .mailmap names, index.md and log.md are always excluded because every write touches them, single_author uses all history rather than the window, and limit=0 means unlimited. This is additive, though pagination and result size remain unaddressed.

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?

There is no wasted concept, but the text is a dense block of semicolon-delimited fragments that reads like release notes rather than guidance. The main purpose is front-loaded, yet the output-section list and the scoping note are jumbled together, which slows comprehension for an agent parsing it once.

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 return shape (files, bundles, authors, single_author) and flags the bus-factor semantics of single_author. Combined with three optional parameters and a safe read-only annotation set, an agent has enough to invoke it correctly, with only the `bundle` parameter's scoping behavior left genuinely unresolved.

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 explain `days` (the window for commit changes) and `limit` (limit=0 lists all, with a listed default ordering of 'most first'), but `bundle` is only obliquely implied by 'like lint ... every bundle' and it is never stated whether passing a bundle narrows the output. Two of three parameters are clarified; one remains ambiguous.

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 (concepts and their authors derived from git history) and enumerates the output sections: files, bundles, authors, single_author. It is clearly not a search, lint, or status tool, though the verb is implied rather than stated (it 'reports' a heatmap). The telegraphic phrasing makes the agent work a bit to parse 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?

'Like lint, it covers where the user is (at the knowledgebase root, every bundle)' is a useful analogy for scoping and implies when the tool applies. However, there is no explicit statement of when to prefer this over `search`, `list`, or `provenance`, nor any exclusions beyond index.md/log.md being omitted. Usage is implied rather than prescribed.

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

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

It discloses write behavior beyond the annotations: markdown files are created if missing, existing lists are rebuilt, and apply=False shows the diff (a dry-run preview). That is consistent with the idempotentHint=true and destructiveHint=false annotations rather than contradicting them. It omits what the diff output looks like and how the bundle param scopes the operation.

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 verb and resource come first, but the prose is packed with section cross-references ('§8', '§8 progressive disclosure') that mean nothing to an agent and interrupt otherwise-dense sentences. The parameter behavior is bolted onto the narrative rather than separated, making it harder 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?

With no output schema, an agent still lacks a picture of what the tool returns (the diff format, a list of files touched) and of the unexplained bundle parameter. The annotations plus description do cover write idempotency and creation semantics, so it is workable but incomplete for a mutation tool with three optional parameters.

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%, so the description must carry parameter meaning, and it does explain two of three: dirs=true gives every directory an index.md, and apply=False renders a diff. The bundle parameter is never mentioned, so a third of the surface is undocumented in both the schema and the description.

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

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

The description states a specific verb and resource: it rebuilds generated index.md lists from frontmatter, covering the bundle-root index and any index that already holds a list, plus knowledgebase-root and per-directory variants. It is clearly distinguishable from siblings such as list, fix, or lint. It loses a point only because it never names a sibling or scope boundary 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?

Usage is implied: you run it to regenerate synthesized indexes, with dirs=true for the progressive-disclosure per-directory variant. The description also signals 'added if missing' versus 'already has a list', which hints at when it writes versus skips. But there is no explicit when-to-use / when-not-to-use guidance against fix, init, or record, and no prerequisites stated.

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

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

Adds substantial context beyond the annotations: never overwrites, skips files that already own a `type` so re-runs are no-ops, keeps existing keys, renames reserved index.md/log.md to avoid collisions, and requires a clean git tree. The keep_okf merge path and its exceptions (source index/log left behind) are spelled out, which an agent could not infer from destructiveHint=true alone.

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?

Purpose is front-loaded and nearly every clause carries new information (frontmatter derivation, merge semantics, exclusions). It is a single dense block with heavy parenthetical nesting, so scanning for the keep_okf behavior mid-paragraph takes effort.

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?

Very complete for a complex, destructive, ten-parameter tool: frontmatter rules, skip logic, rename behavior and merge semantics are all covered, and the absence of an output schema is partly mitigated by the 'apply=False is the plan; sample files' guidance. The gap is the undocumented limit/offset/max_bytes behavior, which could cause an agent to under-ingest and assume completion.

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 must carry all ten parameters; it explains apply, rules ({glob: type}), bundle (source, adopt-in-place), keep_okf, status, stale_days/stale_after and source. But limit, offset and max_bytes — the pagination and size-cap controls that determine whether a single call ingests everything — are never mentioned.

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: bring markdown from a local directory or git clone into an OKF bundle, with a distinct 'adopt in place' mode. The closing exclusions (does not clone, convert other formats, scan for secrets, check licenses) carve out territory from migrate/index-style siblings, though no sibling is named 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?

'apply=False is the plan: run it first, sample files, set rules' gives an explicit recommended workflow and ordering. It also states the prerequisite (clean git tree) and the negative scope, but never routes the agent to a named alternative tool for the excluded cases.

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=false, destructiveHint=false and idempotentHint=true, and the description usefully adds the refusal precondition and the exact files provisioned, which explains why it is non-destructive. However it never discloses that `apply` defaults to false, i.e. that a default call is effectively a dry run and no files are written unless apply is set — a major behavioral trait for a scaffolding 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: the core action and artifacts come first, followed by the precondition and the next-step workflow. Every clause carries information; the only rough edge is the abrupt 'and lint' fragment.

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

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

No output schema exists, so the description must convey the result — and it does, by naming the exact files created. Combined with the refusal condition, the descriptions of a two-parameter, non-destructive write tool are essentially complete; the missing dry-run/apply semantics are already penalized under parameter semantics rather than being a separate completeness 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?

Both parameters have 0% schema description coverage, so the description carries the full burden, yet neither `apply` (dry-run vs. commit) nor `bundle` (target path/identifier) is mentioned or explained. The only hint at semantics is contextually implied by 'Refuses if index.md exists'; an agent could easily call this expecting files to be created when apply defaults to false.

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 pair ('Start a bundle') and enumerates the concrete artifacts produced (root index.md with okf_version "0.2", generated document list, §9 log.md). That level of artifact detail reliably distinguishes it from siblings like create, index, and upgrade, even without naming them explicitly.

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

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

Gives a clear precondition ('Refuses if index.md exists') and a follow-on workflow ('Then add concepts... and lint') that routes the agent to the concept-creation and linting tools. It stops short of naming the sibling tools by name, so the routing is implied rather than explicit.

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

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

Annotations already declare readOnly, idempotent and non-destructive behavior, so the safety profile needs no restating. The description does add useful semantics not in annotations — `exists false` signals a broken link and `target` names the bundle and file — but says nothing about error cases (missing file, unknown concept) or result size.

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 front-loaded with the core idea ("Edges of one concept") and has no filler sentences, but the compressed §-cross-reference notation and sentence fragments make it slow to parse. Density here costs clarity rather than saving 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?

With no output schema, the description usefully documents the returned `out`/`in` structure and the `exists` flag, which is the most important missing piece. However, for a 2-parameter tool with 0% schema coverage, the input side (notably `file` and the empty `bundle` default) remains undefined.

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 parameter burden, yet it never explains what `file` means (path, concept id, relative location) or how the optional `bundle` default of "" resolves. The phrase "target names the bundle and file" describes output fields rather than the input parameters.

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

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

The description names a specific resource — the inbound/outbound edges of a single concept — and describes both directions (`out` = its links and §6.2 path fields, `in` = concepts linking to or citing it). It also disambiguates from lineage/provenance ("sources are lineage, §5.1"). It falls short of 5 because the §-section references and absence of an explicit verb make the purpose partly dependent on external spec knowledge.

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

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

It gives a concrete precondition for one direction: "Check `in` before moving, renaming or deprecating a concept," which ties directly to the move/rename/archive siblings. There is no explicit guidance on when to prefer `get` or `provenance` instead, so it lacks full 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?

Annotations already declare read-only, idempotent, non-destructive behavior; the description adds substantial behavioral detail beyond that, including finding structure, severity semantics, conformant/ok definitions, baseline filtering, git-ref scoping, and default directory behavior. This is unusually transparent for a read-only linting operation.

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

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

The description is dense and semicolon-heavy, with finding fields and parameter explanations packed into run-on fragments. It is not bloated, but the lack of front-loaded structure or grouping makes it harder to scan than necessary.

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-parameter tool with no schema descriptions and no output schema, the description is mostly complete: it explains purpose, usage, finding shape, and eight of nine parameters. It leaves `offset` unexplained and does not state the default `limit` value, but an agent can still call the tool correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it largely does: `all`, `bundle`, `file`/`files`, `limit=0`, `baseline`, `since`, and `scope` are all explained. The `offset` parameter is omitted, which is a meaningful gap given the pagination 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 and resource: "Check the bundle against OKF v0.2." It distinguishes the linting role from the sibling `fix` tool by noting that fixable findings can be cleared with `fix`, but it does not explicitly contrast with `verify` or `status`.

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

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

Gives clear timing guidance: "Run it before and after any change, and in CI." It also points to `fix` for fixable findings, but does not state when to prefer alternatives such as `verify` or `status`.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds real behavioral context the annotations cannot: the valid status and tier value sets and the important semantics that an absent status means 'stable' (while the schema default is an empty string). This prevents a real misinterpretation.

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, front-loaded with the resource and filter list, with the concrete example last. Minimal waste; the terse fragment style is dense without being 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?

For a read-only listing tool with no output schema, the description covers the main filter semantics well but omits bundle scoping and pagination (limit/offset), which matter for an agent that may need to page or scope results. 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 description coverage is 0% with 8 parameters, so the description carries the burden. It explains type, tag, status, tier and stale — including the critical 'absent = stable' default — but says nothing about bundle, limit or offset, leaving three parameters undocumented anywhere.

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 (Concepts) and enumerates the filter dimensions it applies, which is specific enough to picture the operation. It does not explicitly contrast with the sibling 'search' tool, so sibling differentiation is left 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 supplies one concrete usage scenario ('The review worklist after an ingest: status=draft tier=unverified') which implies when this tool is appropriate. However, it never states when to use 'list' versus 'search', nor any exclusions, so guidance is implied rather than explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world. The description adds real context beyond them: ordering (newest first), that results are drawn from every log.md over a concept that link to it, and that git commits that changed the file are included. It doesn't disclose return shape or pagination, but for a read tool this is useful extra context.

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

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

The ordering and mode split are front-loaded ('History, newest first. With file: ... Without: ...'), which is exactly the right structure. The trailing '`record` writes an entry' fragment is a minor aside, and the '§9' cross-reference is opaque without surrounding docs, but there is little waste.

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

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

With no output schema, the description should be richer about what entries look like and how `limit` behaves across the two modes. It covers the two-mode routing adequately but leaves `limit` undefined and gives no sense of result volume or truncation, which matters for a history-listing 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 0%, so the description must carry parameter meaning. It explains what `file` selects (a concept, matching link targets, plus git commits) and implies `bundle` via 'the bundle's recent entries,' but says nothing about `limit` (default 20) — a meaningful omission for a paginated history tool. 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?

The description states the resource is a history log returned newest-first and describes two distinct read modes (per-file concept log + git commits vs. bundle-wide recent entries). It clearly separates reading from the sibling `record` which writes entries. It never states an explicit verb like 'retrieve', but the two-mode behavior description makes the purpose recognizable.

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

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

Explicitly gives the branching condition: 'With file' vs 'Without,' so an agent knows which mode its input selects. It also names `record` as the write alternative, routing the user away from this read tool when they want to add an entry. No mention of `search`/`list`/`get` alternatives for adjacent retrieval 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 already declare destructive=true and non-idempotent, and the description adds real substance beyond them: inbound links in both bundles are rewritten, the concept's own `/` links become relative (with a lint warning for cross-bundle), links from unrelated bundles are untouched, and apply=False yields a diff preview. That is precisely the mutation semantics an agent needs before calling a destructive 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 sibling differentiation is front-loaded in the first clause, and the subsequent sentences on link rewriting and dry-run each add decision-relevant information. It is dense but not padded; the link-rewriting detail could be compressed slightly.

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

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

For a destructive five-parameter mutation with no output schema and no annotation-level parameter docs, the description covers consequences, side effects and the dry-run escape hatch well. The only real hole is the unexplained `file` and `bundle` 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%, so the description must carry the full burden. It documents `to_bundle` ('.' for root), `to` (default: same path) and `apply` (False shows diff), but leaves `file` and `bundle` entirely unexplained, which is a meaningful gap for two of five 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 — moving a concept into another bundle of the knowledgebase — and immediately contrasts it with the sibling `move`, which stays within one bundle. An agent can distinguish the two without opening either schema.

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

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

Explicitly routes the agent away from `move` when the destination is a different bundle, which is the key selection decision among siblings. It does not mention other adjacent tools such as `rename` or `archive`, so the routing is clear but not exhaustive.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false; the description goes beyond that by naming exactly what gets mutated (all links in concepts, index.md, log.md, plus the moved concept's own relative links) and by specifying the dry-run preview. It does not address whether a partially-applied move is atomic or what happens on link-rewrite failure, which is the main remaining gap for a destructive operation.

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 action and its mutations, then the scope boundary, then the safe-usage notes. No sentence is redundant with the others; even the inline "§6.1" reference adds targeting precision at zero 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 destructive, non-idempotent mutation with no output schema and zero schema descriptions, the description covers the essential risk surface: what is rewritten, the bundle boundary, and how to preview. What is missing is the shape of the diff returned under apply=False and any failure/rollback behavior, but nothing needed to call it correctly is 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?

Schema description coverage is 0%, so the description carries the burden: it explains `apply` concretely (False shows the diff) and implies `bundle` via the single-bundle scoping rule, and "move or rename a concept" hints at the file/to pairing. However the semantics of `to` and `file` (path format, relative vs /-absolute input, rename-vs-relocate distinction) are never spelled out, leaving half the parameters 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?

States a specific verb pair (move or rename) and the resource (a concept), plus the full side-effect set (rewriting relative and /-absolute links in concepts, index.md and log.md). It explicitly separates itself from the sibling `migrate`, which handles cross-bundle moves, so an agent can choose between them without reading 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?

Gives an explicit boundary condition ("Stays inside one bundle; `migrate` moves between bundles"), a stated prerequisite ("Check `links` first"), and a dry-run escape hatch ("apply=False shows the diff"). The when-to-use, when-to-use-something-else, and how-to-safely-preview are all present.

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 state readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description adds context those don't convey: the value is inferred so it is stamped `basis: git-history` and 'never raises' a trust tier, which tells the agent this mutation is safe-but-low-confidence. It doesn't say a git repository is required or what happens when history is absent.

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 tightly packed—nearly every clause adds information about derivation source or safety semantics. Density comes at the cost of readability, but there's little pure 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 3-param write tool with no output schema and 0% schema coverage, the description explains semantics and the dry-run path but omits `bundle`, does not identify which files it edits, and never states the git-repo prerequisite.

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%, so the description must carry the load: it does define `skip` ('paths to leave without it') and `apply` (dry-run vs write). The third parameter, `bundle`, is never mentioned anywhere in the description or schema, leaving a real 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?

Opens with a specific verb+resource: fill a missing `generated: {by, at}` field, and explicitly scopes it to concepts that lack that field ('Concepts that carry `generated` are left alone'). An agent can tell it apart from mutators like `set` or `fix`, though it never names a sibling directly and leans heavily on spec jargon (§5.2, 'AI trailer', 'verified').

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 the triggering condition (missing `generated`), an exclusion (already-populated concepts are untouched), and a preview path ('apply=False shows the diff'). It stops short of naming alternative tools for related repair tasks, so the agent must infer the boundary with `set`/`verify`/`fix`.

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

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

Annotations only give generic hints (mutation, non-idempotent, closed-world); the description adds the actual side effects: retrieved_at is set to now, git preserves the prior claims, `by` appends a §5.2 `verified` entry, and stale_days>0 advances stale_after. That is real disclosure beyond annotations and consistent with idempotentHint=false. It does not say what happens on partial/mismatched results or errors.

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

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

Every clause carries information, but the text is semicolon-fragmented and jargon-dense ('§5.2', '--attest', 'git keeps what they said before'), making it harder to parse than the content requires. The purpose is front-loaded, but the ordering of side-effect clauses is not.

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 mutation tool with no output schema and no schema descriptions, the definition explains the workflow prerequisite, the result shape, and each mutation's effect. Absent are return/error behavior and whether the write is scoped to a workspace or bundle by default, but these are modest for a tool whose annotations already flag it as non-destructive and non-idempotent.

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%, so the description must carry the load and largely does: results is described as a list of {bundle?, file, id?}, accepts a bare file=/id= form, omitting id means every source on the concept, `by` triggers the verified entry, and stale_days>0 advances stale_after. Only `bundle` scoping and the interaction between results and file/id are left thin.

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: 'Record a re-check' after comparing due sources with the claims citing them. It names the sibling that must run first (recheck_plan) and describes the artifact written. It stops short of distinguishing itself from adjacent verbs like 'verify' or 'record' in the sibling list, and key terms ('due source', 'concept', 'bundle') are left undefined.

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

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

Explicit precondition — use only after you have compared each due source against its citing claims via recheck_plan and corrected what changed. That sequencing is exactly the guidance an agent needs. No exclusion is stated for verify/record/status, which is the only 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?

Annotations already declare read-only, idempotent, closed-world and non-destructive; the description reinforces this with "Nothing is executed here" and adds real operational context the annotations lack — that the agent must supply its own tool permissions to replay calls, and that args come from the bundle. It also describes the result groupings (sources, cites, calls, manual). It leaves unclear what happens when a recorded call fails or is no longer permitted.

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?

Roughly five dense sentences, front-loaded with the selection criteria and then the action workflow. Every sentence carries information, though the 'one never retrieved is due once its concept is stale' parenthetical is convoluted enough to require a second read.

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 explaining the return shape (sources/cites/calls/manual) and the follow-up path. It still leaves gaps for a two-parameter tool: the unaddressed `bundle` argument and undefined domain terms like `stale_after` that the agent must guess at.

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%, so the description carries the full burden. It does decode `older_than_days` as the N-day retrieval threshold and ties staleness to `stale_after`, but the `bundle` parameter is never mentioned and remains opaque despite a sibling tool named `bundles`.

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

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

The description identifies a specific resource and scope: facts due for re-check, selected either by retrieval age (N days) or by concept staleness. It also implicitly distinguishes itself from recheck_apply, the tool that records the check. It never states a leading verb ("list"/"plan"), so the read-only planning nature must be inferred from the closing 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?

It gives concrete workflow direction: replay each `calls` entry yourself, read the recorded args first, open `manual` resources, correct stale claims, then record with recheck_apply. The handoff to recheck_apply is explicit. It does not say when recheck_plan should be skipped or how it relates to siblings like search/verify/lint.

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 a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds useful behavior: the entry is newest first, the log.md is created if absent, and the entry must link the relevant concept; it does not cover permissions or return behavior.

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

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

The description front-loads the action and is dense with useful instructions rather than filler. It is somewhat hard to parse due to nested parentheticals and specialized notation, but every sentence contributes operational detail.

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

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

For a 4-parameter mutation tool with no output schema and annotations covering safety, the description gives enough information to call it correctly: scope, file creation, entry format, kind conventions, and linking behavior. It leaves return values and permission requirements 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?

Schema description coverage is 0%, so the description must compensate. It explains `kind` conventions, the `note` format, and directory scoping, but the exact semantics of the `bundle` parameter and the interaction between `bundle` and `dir` remain 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 states a specific verb and concrete artifact: writing a §9 entry in log.md under today's date. It also distinguishes the tool from the `log` sibling by explaining that linked concepts are written so `log` can find 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?

It gives clear usage context: record entries go under today's date, use the bundle root or a directory scope, and link the concept. It also names conventional kinds (Update, Creation, Deprecation), though it does not explicitly state when not to use the tool or name alternatives beyond `log`.

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?

Well beyond the annotations: it discloses that inbound links, outbound links, and §6.2 paths are rewritten while the bundle's own `/` links survive, and that the index follows. Adding that `apply=False` only shows a plan and diff gives the agent a safe preview path for a tool annotated destructiveHint=true and idempotentHint=false. Missing: what happens if `to` already exists.

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

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

Three tight sentences that front-load the operation and then the side effects. The §-numbered references are domain jargon that assumes internal docs, which costs a little readability but 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?

For a destructive, non-idempotent mutation with three undocumented-in-schema parameters and no output schema, the description covers the operation, the dry-run escape hatch, all parameter meanings, and the link-rewriting consequences. An agent has what it needs to call this correctly and cautiously.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does: `bundle` is defaulted to the current location, `to` is a path in the knowledgebase, and `apply=False` previews the plan and diff. It does not spell out the required-vs-optional split or the path format, so a small gap remains.

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: 'Rename or move a bundle within the knowledgebase'. An agent immediately knows the operation. However, a sibling tool named `move` exists and the description never distinguishes the two, leaving real ambiguity about which 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?

Implies usage conditions through the `apply=False` dry-run note and the 'default: where the user is' bundle default, which tells the agent to omit `bundle` when operating in place. But there is no explicit when-to-use-this vs `move`, and no stated prerequisites or exclusions.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds two useful traits the annotations cannot: case-insensitive matching and the per-hit shape {bundle, file, line, text}. It says nothing about ordering of results, pagination behavior, or result cap.

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 front-loaded sentence with no filler; the matching semantics and return shape come first. It is arguably too terse for a four-parameter tool, but nothing in it 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?

With no output schema, the description does well to define the hit record, but it omits pagination (limit default 30, offset), bundle scoping, and match ordering — all decisions an agent must make to call this correctly. For a 4-param search tool at 0% schema coverage, this is under-specified.

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% across four parameters, so the description carries the full burden and largely fails: 'query' is only implied, and 'limit', 'offset', and especially 'bundle' (a domain concept) are never explained. Mentioning 'bundle' inside the hit shape hints it is a scoping dimension but does not state that it filters results.

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: 'Case-insensitive text search over concepts', which is concrete enough that an agent can distinguish it from list/get/link style siblings. It does not name any sibling alternative, so it stops short of a 5.

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

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

No guidance on when to use this over siblings like 'list', 'get', 'links', or 'web', and no mention of prerequisites such as indexing state. The agent must infer that this is the free-text lookup path.

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 idempotent=true and destructiveHint=false; the description meaningfully adds that every unmentioned key stays 'byte for byte,' that null drops a key, and that status/stale_after/tags get type validation. What's missing is what happens when validation fails (error vs partial write) and whether a bad field aborts the whole batch — material 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?

Purpose is front-loaded in the first clause and the whole thing is short. But spec cross-references ('§4.1', '§5.4', '§5.5') are unreadable noise to an agent without the document, and 'byte for byte' plus a compressed parenthetical make it denser than it needs to be.

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 output schema, no annotations beyond hints, and 0% schema coverage, the description does well on guarantees and dry-run behavior but leaves the file/files/bundle targeting model unexplained — the single biggest thing an agent needs before invoking a multi-file write.

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% across five parameters, so the description carries the full load. It explains 'fields' (key/value map, null drops) and 'apply' (dry-run diff), but leaves 'file', 'files' and 'bundle' completely undefined — an agent cannot tell whether file is a path or slug, how file/files interact, or what bundle scopes to.

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 frontmatter on one or many concepts.' It also carves out scope by naming which keys belong to other tools (provenance, verify, cite), so an agent can separate it from siblings. The 'by text' phrasing and 'concepts' wording are slightly opaque domain jargon but don't obscure the core 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?

Explicitly routes the agent to alternative tools for generated/verified/sources fields, and 'apply=False shows the diff' tells the agent how to preview before committing. It doesn't state hard preconditions (target must exist, required bundle/file resolution), so it's clear context rather than a full when/when-not guide.

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 this is a non-readOnly, non-destructive, non-idempotent mutation, and the description usefully adds what actually changes on disk: index.md created if missing (with a generated list), log.md started, links rewritten, cross-bundle links listed but left intact with a lint warning, and code-block links also rewritten. What it omits is the single most important behavioral fact – that apply defaults to false, so the call likely previews rather than mutates – and the description never says what the returned diff looks like or that repeated runs are unsafe (contradicting nothing, but leaving idempotency unaddressed).

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

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

The main action is front-loaded and the content is dense with real information, but the prose is a stack of parenthetical spec citations that interrupt the sentence flow, and the trailing 'shortcut: ... read the diff.' fragment is awkwardly telegraphed and leans on the reader already knowing what diff is being referenced.

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 filesystem-mutating tool with no output schema, three undocumented parameters, and no annotations covering permissions, the description does well on effects but leaves the preview/commit semantics and the `bundle` argument entirely unexplained. An agent could not confidently call this correctly on the first attempt without experimenting.

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 compensates for only one of three parameters: `dir` is implied by 'a directory'. Neither `apply` nor `bundle` appears anywhere in the text, so an agent has no idea what `bundle` names (the target bundle id? a name?) or that `apply` toggles the preview/commit mode the description hints at.

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

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

The opening clause names a concrete verb and resource – 'Make a directory its own bundle' – and enumerates the resulting effects (index.md with okf_version "0.2", a new log.md, rewritten `/` links and §6.2 paths). It is distinguishable from siblings like init/migrate/rename by describing bundle-root promotion. The spec cross-references (§3, §6.1) are opaque outside the tool's own doc set, and no sibling is named 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?

Usage is only implied: you split a directory when it should become an independent bundle. There is no statement of when to prefer split over migrate or init, nor when to set apply versus doing a preview – the 'read the diff' line gestures at a review step but never says the call is a dry run unless applied.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered; the description adds real value on top by defining default semantics ('absent = stable'), citing the spec sections governing each breakdown, and disclosing the result-shape branch: at a knowledgebase root without bundle=, per-bundle summaries are nested under `bundles`. It also states a concrete behavioral rule for the queues (five oldest or largest each), which the agent could not guess.

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?

No filler — every clause names a distinct output section — but it is delivered as one long run-on with semicolons and parenthetical §-references, making it hard to scan for the field that matters. Front-loading 'Bundle summary:' helps, yet the queue enumeration and the root-level nesting caveat are buried at the end.

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

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

There is no output schema, so the description must convey the return shape, and it does so in unusual detail — field groups, queue composition and cap, and the nested `bundles` variant. Combined with annotations covering safety, an agent has enough to call it correctly; only exact field names and empty-state behavior are left unspecified.

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 has to carry both parameters and it largely does: `due_days` is defined in terms of the `stale_after` window, and `bundle` is explained through its observable effect (omitting it at a knowledgebase root yields a per-bundle `bundles` map). It never states the empty-string default or the conflict behavior if an invalid bundle is passed, which keeps this short of a 5.

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

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

The description enumerates precisely what the report contains (concept counts by type/status/trust tier, stale counts, unparseable files, okf_version, conformance and lint totals, plus upkeep queues), which is well beyond a restatement of the name 'status'. It also implicitly separates itself from siblings by describing an aggregate overview rather than a list, search, or lint pass, and explains the relationship to `bundles` at a knowledgebase root. The only shortfall is that the operative verb ('report/summarize') has to be inferred rather than stated.

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

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

Usage is only implied: the mention of upkeep queues, stale counts, and conformance totals signals this is the health/overview check, but there is no explicit 'use this when…' clause and no 'use X instead when…' routing against `lint`, `list`, or `bundles`. The `due_days` explanation ('`stale_after` within due_days') does give a hint about the one configurable behavior. Adequate but leaves the agent to infer selection.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds meaningful context beyond them by revealing that the default is a dry-run that shows plan and diff, which substantially softens the destructive risk. It also discloses the side effect of rewriting index.md to re-declare okf_version. It does not say what happens on a path collision at the destination.

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?

Purpose is front-loaded in the first clause, and every clause carries real information about path syntax or dry-run behavior. The parenthetical asides make it a dense run-on that could be split for scanning, 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?

With two parameters, no output schema, and destructive annotations already present, the description covers the essentials: input formats, prerequisites, and the dry-run default. The remaining gap is destination-collision/overwrite behavior, notable for a destructive mutation but not fatal.

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%, so the description must carry the parameter meaning, and it does: `path` is defined as either `<bundle>/<path>` for a concept or `<bundle>` for a whole bundle, and `apply` is defined by its False behavior (plan plus diff). The True branch is only implied, so it falls short of fully documenting both values.

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

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

States a specific verb (unarchive) and resource (archived concept or bundle) plus the two accepted path shapes, so an agent knows exactly what operation is being performed. It is clearly the inverse of the sibling `archive`, though no sibling is named explicitly.

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

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

Gives concrete context for the operating parameters: `apply=False shows the plan and diff`, and states the prerequisite that a concept's bundle must exist and a bundle's index.md must re-declare okf_version. It never explicitly says 'use apply=True to commit', leaving the commit path implied rather than stated.

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

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

Annotations already cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds substantial value on top: it discloses concretely which fields are rewritten, that the `# Citations` list is removed after conversion, and the edge case where missing git history leaves `by` unset and reports it in needs_by. It stops short of saying whether a backup is taken or what a repeat run on an already-upgraded bundle does.

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 dense paragraph that opens with a bare spec reference ('OKF v0.1 to v0.2 (§13)') rather than a plain statement of what the tool does, then packs internal field names like needs_by and basis: git-history into the same breath. Every element is relevant, but readability suffers without a leading one-line summary.

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 output schema and zero schema descriptions, the definition covers the transformation rules and the dry-run mechanism but omits the working-target parameter, backup/rollback behavior, and how the resulting report (needs_by) is surfaced. Adequate, but an agent still has open questions before invoking it.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It explains `apply` well ('apply=False shows the diff', implying true performs the write), but never mentions `bundle` at all, leaving the most essential argument — which bundle gets upgraded — 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?

The description names a specific transformation (OKF bundle v0.1 to v0.2) and enumerates exactly what changes: timestamp field rewriting, citations list to sources, and okf_version in the root index.md. It does not differentiate itself from the sibling `migrate` tool, which an agent could easily confuse with a format-version upgrade.

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: 'apply=False shows the diff' signals a dry-run-first pattern, but there is no explicit statement of when to run this versus `migrate`, `fix`, or `lint`, nor any precondition (e.g., that the bundle must currently be at v0.1).

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false): it discloses that `at` is stamped as now/UTC, that the human path triggers a confirmation prompt and requires the human to type their own id, and that `promote=true` moves a draft to stable with the constraint that only a human review may do so. It does not say what happens on re-verification of an already-verified concept or how failures surface.

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, then cleanly structured as 'Two paths:' followed by the machine case and the human case. Dense but every clause carries information; the only friction is the unexplained §-references that assume spec familiarity.

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 non-idempotent mutation tool with no output schema and 0% schema coverage needs to explain its inputs and effects fully. The human/machine paths and the promote side-effect are covered, but the required `file` parameter (what identifies the concept) and `bundle` are left entirely 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 0%, so the description must carry the parameter burden. It does an excellent job on `by` (three accepted forms, which to omit) and explains `promote` as draft→stable, but never explains the required `file` parameter or the `bundle` parameter, leaving half the schema undocumented anywhere.

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

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

States a specific verb and resource: record a `verified` entry with `{by, at}` and an auto UTC timestamp. It is distinguishable in kind from siblings like `record` or `log`, but the '§5.2 verified entry' framing relies on spec knowledge and it never explicitly contrasts itself with `record`/`recheck_apply`.

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 genuinely explicit branch guidance: use the `by=<tool>/<version>` or `process:<id>` path when a machine checked the concept, omit `by` when a human checks it. Adds hard exclusions ('Never pass human:<id> yourself', 'Present the concept to them first') and the terminal `--attest` path. It stops short of saying when to call `verify` rather than sibling `record` or `recheck_apply`.

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 read-only, idempotent, non-destructive behavior. The description adds useful behavior beyond annotations: broken links are omitted, archived/deprecated nodes are marked, and the return shape or Mermaid alternative is described.

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 front-loaded with the core purpose and then adds scope, exclusions, and return behavior. It is dense and includes section references (§6, §6.2, §5.1) that may be noise to an agent, but it is not verbose.

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

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

For a read-only graph tool with no output schema, the description supplies the return shape, mermaid mode, scope behavior, and omission/marking rules. It is nearly complete, though it could explicitly name the `bundle` parameter rather than relying on inference.

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 carries the full burden and explains all three parameters meaningfully: `bundle` via location behavior, `concepts=true`, and `mermaid=true`. It could be slightly clearer about the bundle argument itself and its default, but the functional semantics are largely covered.

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

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

The description clearly identifies the resource as a link/citation graph, stating that it shows which concepts link to or cite which. It distinguishes itself from lint by noting that broken links are excluded and reported by lint, but it does not explicitly distinguish itself from the sibling `links` tool.

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

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

Usage is implied by the scope behavior: root level shows bundles with edge counts, while a bundle or `concepts=true` shows concepts. The only explicit alternative is lint for broken links, but there is no direct guidance on when to choose `web` over `links`, `search`, or other inspection tools.

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