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

Annotations already mark it destructive, but the description goes well beyond that by disclosing the two-stage confirm/dry-run flow, backup creation, slim-pointer rewrite, throw-on-existing-backup behavior, never-destroys-content guarantee, and outside-repo restrictions. There is no contradiction with the annotations.

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

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

The description is long but densely packed: the primary purpose is front-loaded, and each subsequent sentence covers a distinct safety or classification rule essential to correct invocation. No filler or repetition of schema boilerplate.

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 complex mutation tool with an output schema and annotations, the description covers the full decision surface: classification, dry-run vs confirmed execution, backup/replacement behavior, injection-suspect handling, and path-safety constraints. An agent has enough to invoke it correctly and predict side effects.

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?

Although the schema documents the three parameters at 100% coverage, the description adds substantive semantics: confirm's dry-run vs write behavior, the review requirement and allowOutsideRepo for outside paths, and the canonical-path-inside-repoRoot constraint. This meaningfully helps an agent set parameters correctly.

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

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

The opening sentence identifies a specific verb ('converts') and resource ('CLAUDE.md/AGENTS.md-style markdown file') with a concrete output ('typed vault nodes'), and the classification rules further distinguish it from related tools like add_concept. It is not a tautology and gives an agent a precise job description.

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

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

The intended input is explicit and the description tells the agent how to route suggestions ('review and land with add_concept if useful') and which sections to exclude. It falls short of a 5 because it does not explicitly state when to prefer this over other conversion/indexing tools or list negative conditions beyond injection-suspect sections.

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 convey readOnly=false, openWorld=false, idempotent=false, destructive=false. The description adds substantial context beyond those: 'Throws if the slug already exists', missing extras return as warnings not errors, frontmatter normalization per kind, path-style slug rejection and silent graph-merging risk, and the postWriteMaintenance response shape. All consistent with annotations (idempotent=false matches the throw-on-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?

Every sentence carries real information and the first sentence front-loads the core purpose, but the body is a single dense wall of text with no paragraph breaks or bullet structure. Given the 9-parameter complexity some length is justified, yet it would benefit from scannable structure for a tool this rich.

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?

Exceptionally complete for a complex tool: covers when to call, alternatives, error semantics, normalization per kind, bulk path, slug/title constraints, and the response's postWriteMaintenance queue fields. The output schema exists so return values are covered structurally. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% so baseline is 3, but the description adds genuine semantic value beyond the schema: the title-vs-path rule ('a bare path or ends in a source extension' = evidence, rename to role), the slug flat-folder rule ('elements/src/views/home' rejected), and kind-specific element meaning ('names a CONCEPT a capability uses, not a file'). This materially helps correct parameter selection.

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: 'Create a new ontology node (.md file).' Immediately distinguishes from siblings by naming patch_concept (for existing slugs) and add_concepts (for bulk). An agent can tell what this does and how it differs from the surrounding tools without opening schemas.

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

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

Gives explicit when-to-use ('Call when an AI agent finds a new capability / element / project from code analysis'), explicit exclusions ('use patch_concept' if slug exists, 'use add_concepts' for 5+ nodes), and even a near-duplicate rule (prefer patch_concept over forking a duplicate). No inference needed.

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

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

The description discloses an exhaustive set of behaviors beyond what annotations provide: per-row independent processing, detailed error formats with row labels, duplicate-slug handling with `rowName`/`firstSeenAt`, near-duplicate warnings, non-atomicity, cap of 50, response ordering, postWriteMaintenance semantics, and the bare-file-path rule. None of this is implied by the annotations (`readOnlyHint: false`, etc.), and there is no 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?

The description is long but densely packed with necessary operational detail; every sentence earns its place. It is front-loaded with purpose and usage before diving into error handling and edge cases. Slightly verbose, but justified given the complexity of the batch operation.

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 complex mutation tool with 1 parameter but many edge cases, the description covers everything an agent needs to invoke correctly: accepted input shape, error propagation, duplicate handling, caps, atomicity, response contents, and best-practice guidance (prefer capability nodes). The presence of an output schema further reduces the burden, but the description still exceeds what is structurally implied.

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

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

The schema already provides 100% coverage: the `concepts` parameter is fully described with an array of objects, each field documented (slug, kind, title, body, path, labels, elements, capabilities) including patterns and max items. The description's 'same per-row shape as add_concept' adds marginal value, but the schema carries the semantic load. Baseline 3 is appropriate for this schema-rich situation.

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

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

The description opens with a specific verb+resource ('Batch-create multiple nodes') and explicitly contrasts with its singular sibling `add_concept`, making its scope and distinction unmistakable. It also states the input shape mirrors `add_concept`, so an agent understands exactly what this tool does without opening the schema.

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

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

The description specifies exactly when to use it ('Use after `analyze_repo_structure` or another reviewed proposal flow... when the agent has K accepted candidates'), when to prefer the alternative ('if you need all-or-nothing semantics use single `add_concept` calls'), and even provides batching guidance for >50 items. This fully disambiguates usage from 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?

It goes well beyond the idempotentHint annotation by stating specifically that an existing edge remains an idempotent read even when legacy data lacks a rationale. It also discloses expected_mtime conflict behavior, VaultConflictError, rejection-before-endpoint-resolution, and rich postWriteMaintenance return behavior, while not contradicting the annotations.

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

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

This is a long, dense paragraph, and it would benefit from stronger visual structure, but every sentence adds a distinct and relevant behavior. The purpose is front-loaded and the sibling routing appears near the end, after the important technical details.

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

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

Given the tool's high complexity, an explicit output schema, and many sibling tools, the description covers the operation, conflict handling, failure-mode details, and batch alternatives. It even explains behavior that the output schema might not, such as the contents of `postWriteMaintenance` and the conditions for using the batch endpoint.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: `depends_on` requires a nonblank `why`, `domain` sets the source node's inline parent domain, `type` determines the frontmatter key, and `expected_mtime` comes from a prior `get_concept` and acts as a concurrent write guard.

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

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

The first sentence names a specific operation, 'Add a semantic relation between two nodes', and the description spells out the frontmatter keys it writes to. It also distinguishes itself from the sibling `add_relations` by naming the batch variant as the preferred tool for multiple edges.

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

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

The description explicitly says to use `add_relations` for multiple already-approved edges and that `infer_imports.moduleEdges` require human approval first, giving clear when-to and when-not-to guidance. This directly orients the agent toward the correct tool 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 idempotentHint=true, readOnlyHint=false, destructiveHint=false, and the description adds substantial context beyond these: idempotency detail (alreadyExists responses), non-atomicity with no rollback, the 50-call cap, response ordering, the expected_mtime staleness pitfall, and detailed error-shape semantics. No contradiction with annotations — idempotentHint matches the 'processed ... idempotently' claim.

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 purpose and usage, and every sentence carries real information. However, it is very long and dense — the error-handling enumeration (unknown type, single/multi unknown-field rows, receivedValue/suggestion/allowedValues) is verbose and partly duplicates what an output schema should convey. It is information-dense but less scannable than it could be with a more structured layout.

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 complex batch tool with idempotency, non-atomicity, varied error shapes, and a maintenance-plan output, the description is remarkably complete: use context, exclusions, limits, error semantics, ordering guarantee, and postWriteMaintenance structure are all covered. An output schema exists, yet the description still clarifies return behavior beyond it. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value beyond the schema: the 'required nonblank why for every new depends_on' emphasis (schema has this too, so partly redundant), the per-row shape reference to add_relation, and the expected_mtime tip about same-from-slug staleness. The added context justifies one point above baseline.

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

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

States a specific verb+resource ('Batch-add multiple relations') and immediately distinguishes from the sibling add_relation by noting the 'same per-row shape' but batch semantics. An agent can clearly tell this from add_relation 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 says when to use it ('after analyze_repo_structure or another review flow when the agent has K semantic edges accepted by the user') and when NOT to use it ('NO atomic rollback — for all-or-nothing semantics use single add_relation calls'). Names the exact alternatives (add_relation, analyze_repo_structure) with selection conditions. Nothing is left to inference.

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

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

Discloses side-effect-free behavior ('side effect 0 (vault frontmatter NOT modified)') and deterministic output semantics. It also reveals server-side validation behavior (verifies only named current files, rejects missing/ambiguous/unsafe coordinates) and the requirement to convert candidates into an evidence-backed proposal before any write. These traits go beyond the readOnlyHint/destructiveHint annotations and add significant operational context.

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

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

The description is an enormous, unstructured wall of text lacking paragraph breaks or coherent organization. It mixes the tool's core purpose, detailed detection heuristics, validation policy, and agent workflow instructions into one dense block. Many sentences are tangential (e.g., about 'declared approval provenance' and 'identity authentication'), making it poorly scannable and not appropriately sized for an MCP description.

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

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

For a tool of this complexity, the description covers the key aspects: what the tool does, the optional inputs (proposal, qualification), the return values (deterministic candidates, reviewPlan, planDigest, sourceDigest), and the critical constraint that writes must not occur until a writePlan is present. No obvious information needed for correct invocation is missing, though the verbosity dilutes 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?

The description adds meaning for the complex parameters by explaining that a 'proposal' can be passed to validate definitions and that a 'constructionQualification:v1' packet is passed as 'qualification'. It also explains the effect of proposal validation. Since schema coverage is 100%, the baseline is 3; the added guidance for these two parameters lifts it to 4.

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

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

The description opens with a clear action: 'analyze a code repository and propose ontology node candidates.' It also states the output is 'deterministic candidates' and clarifies the tool has no side effect on vault frontmatter. It does not explicitly contrast with sibling tools like infer_imports or inspect_architecture, but the core purpose is unambiguous.

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

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

Provides an explicit trigger: 'Use this once when a user asks "이 codebase 분석해줘" / "bootstrap the ontology".' It also gives a strong negative condition: 'Do not call write tools unless proposalValidation.canWrite is true and a writePlan is present.' This clearly tells the agent when to invoke the tool and what to avoid.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description correctly adds 'side effect 0' and explains determinism and the stable graphHash/maxMtime for cache invalidation. It also warns about token cap and explains pagination behavior, which are useful beyond the annotations. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose, then provides usage details on pagination and summary. Every sentence contributes new information; there is no fluff. It's a bit long but justified given the tool's complexity.

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 complex tool with 6 parameters and an output schema, the description covers all critical aspects: purpose, usage timing, token cap mitigation, pagination, summary mode, and side effects. It explains the response meta and cache invalidation, so an agent has enough context to call it correctly without missing critical details.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds value by explaining usage patterns such as 'use summary: true for cheap polling' and how to slice arrays with nodesLimit/nodesOffset. It also mentions the pagination meta in the response, which is not in the schema. This goes beyond the schema and helps the agent choose parameters appropriately.

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 ('Compile'), a resource ('whole markdown vault'), and the resulting artifact ('deterministic graph artifact' with nodes, edges, aliases, etc.). It clearly distinguishes itself from sibling tools by calling itself 'the compiler-style read path' and describing its intended use case, so an agent can easily tell it apart from query or get tools.

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

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

The description provides explicit context for when to use the tool: 'call it before advanced reasoning, indexing, export, or non-developer-friendly graph views.' It also explains how to handle large vaults with summary and pagination options, giving practical guidance. It doesn't explicitly name alternatives or exclusions, but the context is clear enough to guide an agent.

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

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

Annotations already mark this readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns the active process-level roots, explains how each was resolved, and warns that root changes require restarting the MCP process. This goes beyond the annotations without contradicting them.

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

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

Two sentences, each earning its place: the first defines the exact output, and the second gives actionable usage context plus an operational caveat. No filler or redundancy.

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

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

For a parameterless, read-only diagnostic tool with an output schema, this description is complete. It tells the agent what the tool returns, when to call it, and an important limitation (root changes need a restart). Nothing needed to invoke it correctly is missing.

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

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

The tool has zero parameters and the schema is fully self-explanatory with 100% coverage. The description does not need to elaborate on parameter semantics, and the baseline 4 for a parameterless tool is appropriate.

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

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

The description states a specific verb and resource: 'Return the exact active vault root and code-repository root used by this MCP process, including how each root was resolved.' This clearly identifies the tool's purpose and differentiates it from siblings like git_history or list_concepts, which serve different diagnostic or data operations.

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

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

The description gives explicit guidance: 'Call first when a client may have stale configuration or multiple workspaces.' It also explains the restart constraint. It lacks an explicit when-not-to-use or named alternatives, but the provided context is specific enough to guide tool 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 readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the description's job is to add context beyond those flags. It does so richly: nothing is written without confirm:true, re-running replaces the binding, the absolute root is stored in a gitignored sidecar and never enters the receipt or graph markdown, and repair discards a malformed sidecar. This is exactly the kind of behavioral context an agent needs.

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

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

The description is dense but every sentence earns its place: purpose, trigger context, inference rule, dry-run behavior, replacement semantics, and sidecar storage are each covered in one or two clauses. It is front-loaded with the core action and routes to alternatives early. No filler or repetition of schema text.

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

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

For a tool with 4 parameters, an output schema, and annotations, the description covers all the non-obvious context: the dry-run default, the inference fallback, the replacement behavior, the sidecar location, and the privacy boundary (absolute root never enters receipt/graph/handoff). An agent has everything needed to call it correctly and to interpret the proposal response.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains that omitting rootPath triggers auto-inference (git repo enclosing the vault, else nearest ancestor with a project manifest), that confirm:true is required to write, and that repair handles a malformed sidecar. It doesn't add detail on projectSlug beyond the schema, but the added rootPath and confirm semantics justify a 4.

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

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

The description opens with a specific verb phrase — 'Bind a project node to the local code folder it describes, measure it, and write the source receipt' — and immediately distinguishes the tool from siblings by naming the exact nextAction values and related tools it fulfills. It also contrasts with disconnect_project_source, so an agent can tell them apart without opening schemas.

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

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

The description explicitly states when to use this tool ('This is what nextAction: connect_source ... asks for'), what happens when confirm is omitted, how rootPath inference works, and how re-running with a different rootPath behaves. It also names the sibling that removes the binding, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations only supply destructiveHint=true, but the description adds substantial behavioral detail: permanent file deletion, dry-run without confirm, refusal when backlinks exist, dangling referrers with force, exception on mtime mismatch, directories left untouched, and a return payload that enables recovery. Nothing in the description contradicts the annotations.

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

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

The description is front-loaded with an explicit danger warning and organized into a numbered two-stage safety flow. It is dense and scannable; however, the lengthy postWriteMaintenance detail is likely redundant given that an output schema exists, so it could be trimmed without losing essential guidance.

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

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

For a destructive, multi-conditional delete operation, the description covers the full call flow: prerequisites, dry-run vs. confirmed behavior, failure modes, force escalation, concurrency protection, side effects, and recovery. The output schema provides the structured return contract, so the description is complete enough for an agent to invoke the tool correctly.

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

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

Although the schema already documents all parameters, the description enriches them with conditional semantics: confirm controls whether deletion actually happens, force deliberately overrides the backlink safety check, and expected_mtime throws if the file changed. It also clarifies the dry-run default, which is not obvious from the schema alone.

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

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

The description opens with 'DESTRUCTIVE — permanently deletes the vault .md file', giving a specific verb, resource, and consequence. It clearly distinguishes deletion from sibling mutation tools like patch_concept or rename_concept by detailing the two-stage dry-run/confirm flow and the effect on backlinks.

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

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

The description provides strong usage context: omit confirm for a dry-run, pass force to override backlink refusals, and pass expected_mtime to guard against concurrent edits. It even points to add_concept as a recovery path)Skip does not explicitly contrast when to choose delete_concept over related siblings such as patch_concept or reclassify_concept, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, and the description adds meaningful behavioral context: it removes both the binding and its receipt, requires confirm:true to write, defaults to a dry-run report, and explicitly scopes the blast radius to the single project. The only minor gap is that it doesn't describe the output schema's contents, but the output schema exists and the description covers the key behavioral traits.

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

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

Three sentences with zero waste. The core action is front-loaded, the inverse relationship is stated, usage conditions are given, and safety scope is clarified. Every sentence earns its place.

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

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

For a destructive mutation tool, the description covers the action, the prerequisite (confirm:true), the dry-run behavior, the scope limitation, and the non-effect on ontology markdown. The output schema exists, so return values don't need to be described. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds the crucial semantic that confirm:true is required to write and defaults to listing what would be removed, which enriches the confirm parameter's meaning. However, it doesn't add much beyond that, so a baseline 3 is appropriate.

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

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

The description states a specific verb ('Remove'), a specific resource ('a project node's local source binding and its receipt'), and explicitly names its inverse sibling (connect_project_source). This clearly distinguishes it from siblings like delete_concept or remove_relation, and the 'reversal of connect_project_source' framing makes the tool's role unambiguous.

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

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

The description gives explicit when-to-use guidance: 'use it when the wrong folder was bound, or to stop measuring.' It also explains the safety behavior without confirm:true, and states what is never touched ('Other projects' bindings are never touched, and no ontology markdown changes'). This is strong usage guidance that an agent can act on directly.

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

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

The description discloses precise write behavior: it writes only a small provenance receipt to `.ontology-atlas/project-meaning.json` and explicitly lists what it never stores. It also explains the semantic meaning of `ok: true`, which prevents a common misinterpretation. These details complement the sparse annotations significantly.

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

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

The description is dense but every sentence contributes: sequencing, caller constraints, write scope, exclusions, and result interpretation are all covered without repetition. It is appropriately sized for a tool with subtle semantics.

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

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

For a tool with only two parameters and non-trivial side effects, the description fully covers when to call it, what it writes, what it refuses to write, what the result flag means, and where to get the actual assessment. Nothing essential is left to inference, and the output schema is referenced through `meaningAssessment`/`agent_brief`.

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

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

Schema coverage is 100%, so the schema already documents both parameters well. The description adds important semantic value by explaining that `expected_mtime` is a conflict guard and that callers cannot submit or restamp server-derived values, reinforcing the role of `projectSlug` and `expected_mtime`.

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 ('Finalize') and a specific resource ('current project competency Markdown'), and it distinguishes the action from related operations by specifying the exact sequence it must follow. It also clarifies the tool's narrow scope: writing a provenance receipt, not compiling or validating.

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

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

The description explicitly says to use this tool after concept/relation writes, vault validation, and a complete project compile, which gives clear contextual conditions. It also warns that `ok: true` does not verify source currentness and directs callers to `meaningAssessment` or `agent_brief` for the fail-closed result. It does not name alternative sibling tools, but the sequencing is specific enough to guide 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 readOnlyHint=true, and the description adds meaningful behavior beyond that: it discloses that scanning covers both frontmatter array keys and wikilinks/markdown links in the body. This helps an agent predict what counts as a backlink. No contradiction with annotations.

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

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

Three sentences with no filler: the core behavior, the scanning details, and the use case. Every sentence earns its place and the key return behavior is front-loaded.

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

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

For a single-parameter read-only tool with an output schema, the description fully covers what the tool does, what inputs it scans, and why an agent would use it. Nothing critical is missing.

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

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

Schema coverage is 100% and the schema already describes 'slug' as 'Target vault-relative slug (omit the .md extension).' The description refers to 'target slug' but adds no new parameter-level detail, so the baseline 3 applies.

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

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

The description uses a specific verb and resource: 'Return every node that points to the target slug.' It clearly defines the tool's output as backlinks and distinguishes it from forward-link or path-finding tools by explicitly scoping to nodes pointing toward the slug.

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 last sentence, 'Used by AI agents to walk the graph from a node to its dependents,' gives clear contextual use. It does not explicitly name alternatives or exclusions, so it stops short of a 5, but the intended scenario is evident.

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

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

Beyond the annotation's readOnlyHint: true, the description discloses substantial behavioral details: it produces ranked matches with a deterministic score formula (title match > frontmatter > body, plus tie-breakers), includes prose excerpts up to 200 chars avoiding certain blocks, distinguishes nodes vs non-nodes, and clarifies the growthHint on zero matches. This is genuinely useful behavioral context not present in any other structured field.

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 organized so the core purpose and use case lead, followed by the ranking rules, node semantics, and the limit/growthHint behaviors. The length is justified because of the tool's complexity, but it is dense and could lose agents scanning quickly. Still, every sentence earns its place.

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

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

The description, combined with the fully enumerated input schema and an existing output schema, leaves few important gaps. It covers purpose, use context, matching and ranking behavior, node/non-node semantics, the limit option, and the zero-result growthHint, so it is effectively complete for correct invocation and result interpretation.

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

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

Schema_description_coverage is 100%, so the baseline is 3. The description references limit, nodesOnly, and the title's substring semantics, but these largely duplicate what the schema already says (e.g., 'Return only the top-N highest-scoring matches' and the nodesOnly default flag). It adds no fundamentally new parameter-level meaning.

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

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

The description opens with 'Find vault docs that mention a given concept by title,' a specific verb+resource+scoping statement. It clearly positions the tool for the 'where is this capability realized' use case, and the emphasis on title-based mention matching differentiates it from sibling tools like find_backlinks, find_neighbors, and get_concept.

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

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

The description is explicit about when to use it: 'Useful when an AI agent asks where a capability is reified in code or docs.' It also explains it can avoid an extra get_concept call. However, it does not explicitly state exclusions (e.g., 'for backlink relationships use find_backlinks'), leaning on implied differentiation rather than naming alternative 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?

With readOnlyHint=true and destructiveHint=false, the safety profile is already covered. The description adds meaningful behavioral context beyond annotations: it specifies the graph-frontmatter-only scope, supports outgoing/incoming/both directions, and describes the return composition (canonical edges plus neighbor node summaries). This is useful and consistent with the annotations.

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

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

The description is two sentences with no filler. It front-loads the core purpose, distinguishes the tool from a sibling, and then describes the return value compactly. Every sentence earns its place.

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

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

Given the five-parameter schema and output schema, the description covers the important contextual pieces: graph scope, direction flexibility, and output composition. It could have added a bit more explicit guidance on when to choose this over find_backlinks, but the overall definition is sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the parameters are already documented in the schema. The narrative description adds a bit of related context around direction options and output shape, but it does not materially explain individual parameters beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses a precise verb ('Return') and identifies a specific resource ('the one-hop graph neighborhood around a node'). It also explicitly contrasts itself with find_backlinks, making the tool's role clear relative to a likely sibling.

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

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

The description explicitly names find_backlinks as an alternative and states the key distinguishing factor: this tool is graph-frontmatter only. This effectively tells an agent when this tool applies, but it stops short of giving an explicit 'when not to use' condition or direct guidance for other sibling tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral details beyond that: the default exclusion of root/sentinel kinds and the specific matching policy (full slug or final segment). This enriches the agent's understanding without contradicting the annotations.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds value: the definition, the use cases, and the matching policy plus default exclusions. There is zero waste or redundancy.

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

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

For a read-only list tool with a full output schema, the description covers the essential purpose, use cases, matching policy, and default exclusions. It doesn't describe the output format, but that is handled by the output schema. The only minor gap is that it doesn't explicitly mention pagination or performance, but these are not critical for a tool like this.

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

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

Schema description coverage is 100% – both 'kind' and 'excludeKinds' have descriptive text in the schema, including the default value for excludeKinds. The tool description reinforces the default exclusion but does not add new parameter-specific meaning beyond what the schema already provides. Given the high schema coverage, the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: 'List orphan nodes' and defines exactly what an orphan node is ('docs that no other node references via any frontmatter array key'). It also distinguishes itself from the sibling find_backlinks by referencing the same matching policy, so an agent can differentiate them without inspecting schemas.

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

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

The description gives a clear use case ('cleanup starting point' and 'which nodes are unused?') and explicitly notes that the matching policy is shared with find_backlinks, which implicitly tells an agent that find_backlinks is the counterpart for finding referenced nodes. However, it doesn't explicitly state when not to use this tool or name alternative tools for different scenarios, so it's slightly short of a 5.

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

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

The description goes far beyond the annotations (readOnlyHint=true, destructiveHint=false) by detailing the exact output structure: nodes with uid/slug/kind/title/domain, edges with from/to/via/rationale, the meaning of via as a frontmatter key, and the fallback { found: false } with a growthHint. It also discloses the undirected BFS algorithm, maxHops default (5) and cap (20). This is rich behavioral disclosure that fully informs the agent without contradicting annotations.

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

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

The description is dense but well-organized: it leads with the core purpose, then details the output shape, then explains the fallback and maxHops. Every sentence carries useful information; there is no filler. It is slightly long, but the complexity of the output justifies the length. It is front-loaded with the essential 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?

Given that an output schema exists and the annotations already cover read-only safety, the description is complete. It explains the return structure in detail, the failure mode with growthHint, and the algorithm constraints. There is nothing an agent needs to know about invoking this tool that is missing.

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

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

The input schema already provides descriptions for all three parameters (from, to, maxHops) with 100% coverage. The description adds the default (5) and cap (20) for maxHops, which is also stated in the schema, and clarifies that from/to are slugs (already in schema). It does not introduce new meaning beyond what the schema provides, so it sits at the baseline of 3.

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

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

The description opens with a clear, specific statement of what the tool does: 'Shortest path between two nodes (undirected BFS).' This unambiguously names the verb (find path) and resource (nodes in a graph). However, it does not explicitly differentiate from sibling tools like find_neighbors or find_backlinks, though the purpose itself is distinct enough that an agent could infer when to use it.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It describes behavior and output in detail but never states conditions like 'Use this when you need the shortest path' or 'For direct neighbors, use find_neighbors instead.' The mention of growthHint implies a use case for exploring gaps, but that is implicit and not framed as selection criteria.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses critical behaviors: successful responses always include both uid and slug, graph relations are slug-based, and the default excerpt truncation is always accompanied by bodyInfo metrics so partial reads are never silent. This is rich context that the annotations alone do not convey, and it does not contradict them.

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

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

The description is dense and front-loaded with the core selector logic, then builds to return details and usage notes. The bold key phrases help scanning, and every sentence carries information; however, it is on the longer side for a single-tool definition, so a 4 reflects the trade-off between completeness and brevity.

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

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

Even though an output schema exists, the description still enumerates the return fields (frontmatter, body, neighbors, edges, mtime) and explains the excerpt/bodyInfo mechanism, making the tool fully understandable without opening the schema. It also covers the error case and points to the plural variant, so an agent has everything needed to invoke it correctly.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds value by stating the exclusivity rule between uid and slug (which the schema implies but does not state globally) and reinforcing the body parameter's usage semantics, though it largely repeats the schema's own guidance. This pushes it above baseline but not to 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 opens with a specific verb-resource pair ('Fetch one node') and immediately clarifies the two selectors (slug or uid), making the tool's purpose unmistakable. It also distinguishes itself from the sibling get_concepts by explicitly routing bulk lookups there, so an agent can tell them apart without reading schemas.

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

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

The description gives explicit when-to-use guidance for the body parameter ('use full when you are reading a node to answer a question rather than just to identify it') and names the alternative for multi-selector calls ('For K specific selectors in one call use get_concepts'). It also hints at error behavior ('When a slug does not resolve, structured growth guidance remains available'), leaving little to inference.

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

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

The description adds significant behavioral detail beyond the readOnlyHint annotation: it explains partial failure handling (missing rows return {ok:false, error, ...repairFields} without aborting the batch), guarantees successful rows always return permanent uid and current canonical slug, and states ordering matches input. It also clarifies that graph relations remain slug-based. This thoroughly discloses error behavior and output guarantees, exceeding annotation coverage.

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

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

The description is four sentences, front-loaded with the main purpose, then error handling, and a note about graph operations. It is dense with useful information but could be slightly more concise; each sentence adds value, and the structure is logical.

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 batch-fetch tool with partial failures, the description covers all essential aspects: selector choice, per-row shape, ordering, error behavior, and graph-operation implications. It also references get_concept for output consistency. The batch limits and body effect are in the schema, so the description is complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters including the mutual exclusivity of slugs and uids ('never together') and the batch limits. The description reinforces 'exactly one selector array' and 'immutable uids' but adds no new parameter-specific meaning beyond what the schema provides. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool fetches multiple nodes by exactly one selector array (slugs or uids), with a specific verb ('Fetch') and resource ('nodes'). It distinguishes from the sibling get_concept by noting 'Same per-row shape as get_concept', implying a batch vs single-node usage. The purpose is unambiguous and differentiates well.

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

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

The description implies usage for fetching multiple nodes at once, contrasting with get_concept for single nodes, and explicitly notes 'exactly one selector array' to avoid mixing slugs and uids. It also explains the order matches the input array and that graph operations remain slug-based, giving context for when to use this tool. However, it doesn't explicitly state 'use get_concept for a single node' or enumerate alternatives, leaving some inference to the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes well beyond that by detailing behavioral nuances: it returns bounded newest-first results, includes limited/hasMore, exposes shallow-repository state, and provides historyComplete so agents don't mistake truncated or shallow views for complete evidence. It also explicitly states it never performs mutation actions. This is rich, additive behavioral disclosure that significantly aids correct agent reasoning.

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

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

The description is two sentences that are dense with information yet free of filler. It front-loads the core purpose in the first sentence, then packs behavioral and scoping details into the second. Every clause adds value, with no wasted words.

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

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

Given that the tool has an output schema (implied by context signals) and a single documented parameter, the description covers all critical aspects: the scope, the return semantics (hashes, subjects, timestamps, limited/hasMore, shallow state, historyComplete), the exclusion rule, and the read-only guarantee. An agent would have everything needed to call and interpret the tool correctly without missing crucial information.

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

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

The input schema fully documents the single optional 'limit' parameter with its default and maximum, achieving 100% schema coverage. The description does not add any additional meaning or nuance about the parameter itself; it focuses on the return format and behavior. Since the schema already does the heavy lifting, a baseline of 3 is appropriate.

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

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

The description states a specific verb ('Read'), resource ('commit history'), and scope ('scoped to the active vault path only'). It also adds the exclusion of commits touching files outside the vault, which clearly delineates what the tool provides. This is a crisp purpose statement that distinguishes it from other Git-related tools like git_snapshot or git_status without naming them, but the specificity is sufficient.

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

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

The description gives clear context for when this tool is appropriate: only vault-scoped history, and explicitly states what it does NOT do ('never initializes, fetches, pulls, commits, or pushes'), which helps an agent avoid misuse. However, it does not name sibling alternatives or provide explicit 'use X instead' conditions, which would make the routing guidance even stronger.

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?

Even though annotations already mark destructiveHint:true, the description adds valuable behavioral detail: confirm commits only the vault pathspec, leaves outside files untouched, never pushes, and blocks on validation errors or Git operations in progress. It also explains the dry-run return contract and expectedHead requirement, giving the agent meaningful insight beyond the annotation flags.

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

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

The description is compact and front-loaded, with the core purpose in the first sentence. The second sentence packs many safety clauses, but its run-on grammar and list-like structure ('requires that expectedHead, blocks validator errors...') make it slightly harder to parse. Still, no filler is present and every clause earns its place.

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

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

Given the tool complexity, an output schema exists, and annotations already flags destructive behavior, the description provides enough context for safe invocation: dry-run flow, confirm semantics, expectedHead, vault-only commits, and no push. It doesn't describe exact return structure, but that is covered by the output schema, and it omits no critical invocation step.

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

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

Schema description coverage is 100%, so the baseline is 3. The description clarifies the interaction between confirm and expectedHead and mentions the deterministic auto-generated message, adding some cross-parameter meaning. However, it does not go deeply beyond what the schema already says; the schema itself already documents the dry-run-first confirm requirement and the expectedHead copy instruction.

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

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

The description states a specific action ('Create a local, vault-scoped Git checkpoint') and clearly distinguishes it from sibling tools by emphasizing local, vault-scoped, and 'never pushes.' An agent can tell git_snapshot apart from git_status or git_history because the purpose includes scope, local-only behavior, and checkpoint creation.

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

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

The description gives clear workflow guidance: dry-run by default, review the returned preview/risk fields, then set confirm:true. It also states behavioral preconditions such as blocking on validator errors and active Git operations. It does not explicitly name alternative tools or say 'use X instead', which keeps this from a 5, but the usage context is unmistakable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description goes further by enumerating specific non-actions ('never initializes, stages, commits, or pushes') and flagging 'in-progress operation risk', which is valuable behavioral context not present in the structured metadata.

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

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

Two sentences with no filler. The core purpose and return contents are front-loaded, followed by explicit non-behaviors. Every clause earns its place.

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

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

The output schema documents the return shape, so the description only needs to convey invocation-relevant details. It covers scope ('active vault only'), key return categories, and behavioral constraints. Nothing an agent needs to call it correctly is missing.

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

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

The tool has zero parameters, so there is nothing to document; schema coverage is trivially 100%. The description correctly avoids inventing parameters, satisfying the baseline for parameterless tools.

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

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

The description uses a specific verb ('Inspect') and names the exact resource ('local Git state for the active vault'). It enumerates distinct return items (HEAD/branch, change counts, staged-outside-vault warnings, risk) that clearly differentiate it from sibling tools like git_history and git_snapshot.

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 scope is clearly stated ('active vault only') and the read-only nature is explicit, giving an agent solid context for when this tool is safe to invoke. However, it does not explicitly name sibling alternatives or state when to prefer this over git_history/git_snapshot, so it stops short of full exclusion guidance.

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

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

Goes well beyond the readOnlyHint annotation by detailing the extraction contract (source facts as evidence, README meanings as proposals), categorization of candidates into existing/ambiguous/new buckets, return of reviewCalls, and explicit 'side effect 0: this tool never writes markdown.' It also explains that inferred imports are never auto-promoted, adding behavioral nuance not captured by annotations. No 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?

The description is long but well-structured: the first sentence gives purpose, the second usage, then behavioral details. Every sentence conveys necessary information for a complex orchestration tool, though some phrasing could be tightened. It is front-loaded with the most critical usage guidance.

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

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

Given the tool's complexity and the presence of a full output schema, the description covers purpose, usage, side effects, and key return categories (competency questions, uncertainty, approval gates, reviewCalls). It even clarifies when active-vault validation may not apply, so nothing essential for correct invocation appears missing.

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

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

Schema coverage for all parameters is 100%, so the baseline is 3. The description does not add extra meaning to individual parameters beyond what the schema already provides; it only mentions them in passing (e.g., 'forwarded to'), so it doesn't compensate beyond baseline.

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

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

The description clearly states the tool orchestrates three specific analyzer tools (analyze_repo_structure, infer_imports, validate_vault) into a single read-only indexing plan. It distinguishes itself from those underlying tools by being a composite and from the CLI write variant by explicitly being read-only and never writing markdown.

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

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

The description explicitly states when to use: 'for large or already-existing projects where the agent needs a resumable ontology indexing checkpoint before writing.' It also contrasts with the CLI `index --apply` which may write, positioning this tool as the read-only alternative with the note that inferred imports remain review-only.

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

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

Beyond the readOnlyHint=true and destructiveHint=false annotations, the description explicitly states side effect 0 (vault frontmatter NOT modified), that it never performs write actions, never self-approves semantic depends_on relations, never executes source code, and does not expand macros or evaluate cfg for Rust. It also discloses failure behavior for oversized scans without a reconciliation vault, which is valuable behavioral context not present in annotations.

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

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

The description is an extremely long, dense wall of text that repeats several key ideas multiple times (never self-approving, never a write action, source-backed review candidates). It contains a useful bulleted list of detected import types, but overall the structure is not front-loaded and would be hard for an agent to parse quickly. Significant trimming and sectioning could preserve the same information with much less noise.

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

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

Given the tool's complexity, the description is remarkably complete. It covers supported languages, import detection variants, mode behavior, response size limits, reconciliation semantics, missing-edge handling, and write-safety guarantees. An output schema exists, and even though the description explains return details more than necessary, it does not leave critical gaps for an agent attempting to select or invoke the tool correctly.

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

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

The input schema already covers all 12 parameters at 100% coverage, so the baseline is 3. The description adds meaningful semantic context beyond the schema: it explains the automatic vs. focus vs. next delivery model, when allowLargeResponse is required, how focusPath interacts with reviewMode, and what reconcile:false skips. This is more than the schema alone provides, though some per-parameter semantics are still left to the schema.

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

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

The description states a specific verb and resource: walk TS/JS files and infer file-level and module-level import edges, plus Python/Rust/Go variants. It clearly distinguishes itself from analyze_repo_structure by calling out that it produces real dependency edges rather than suggestedRelations heuristics, and it names related tools like add_relation and get_concepts to clarify what it is not.

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

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

The description explicitly says to use this tool after analyze_repo_structurecreates a clear workflow position. It also explains when to set focusPath, when to omit reviewMode, when to use reviewMode:"next" or "full", and what to do when vault edges are missing (inspect concepts, ask user, then call add_relation). It does not exhaustively enumerate all sibling alternatives, but provides strong practical guidance for the main decision points.

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

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

Annotations already mark readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral nuance beyond that: it never treats unsupported languages, unclassified import usage, empty role mappings, or unmapped edges as compliance, and clarifies that pattern labels come from human/document declarations, not folder-name inference. This directly informs the agent of the tool's conservative, evidence-based behavior, which is highly valuable for correct invocation and interpretation of results.

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

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

Four sentences, each adding distinct value: the core action, the profile's role, the output categories, and the caveat about pattern labels. The description is front-loaded with the primary purpose and ends with a succinct 'side effect 0' note. No filler or redundant information.

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

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

Given the tool's complexity and the presence of an output schema, the description covers the essential context: input requirements (reviewed profile, active vault, connected repo), the scanning mechanism, the output type (architectureBrief:v1), the three result categories (conforms, violated, unknown), and explicit exclusions. The agent has enough information to decide when to invoke it and what to expect.

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

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

Schema coverage is 100% – every parameter (maxFiles, rootPath, profileSlug) has a description with constraints. The tool description adds no additional meaning about parameters, so it does not go beyond the schema. A baseline of 3 is appropriate since the schema fully documents the 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 opens with a precise verb-resource-outcome chain: 'Read one reviewed architecture-profile/v1 document, scan the connected repository with the existing bounded static import analyzer, and return an architectureBrief:v1.' It clearly distinguishes itself from sibling repo-analysis tools (e.g., index_project, analyze_repo_structure) by specifying the profile-based, compliance-focused output. The mention of 'reviewed' and 'bounded' narrows its scope further, so an agent can differentiate it without opening the schema.

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

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

The description implicitly conveys when to use it: when a reviewed architecture profile exists in the active vault and a repository is connected. It does not explicitly list alternatives or state when not to use it, but the context is clear enough to guide an agent toward this tool for architecture compliance checks rather than, say, indexing or repository structure analysis. No exclusions are mentioned, so a 4 is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations: pagination semantics ('always follow pagination.nextOffset while hasMore is true'), incremental sync via mtime, and resumability for large vaults. This gives the agent practical execution guidance without contradicting any annotation.

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

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

The description is three sentences with zero filler. It front-loads the core purpose, then packs filter, pagination, and intended usage into compact, high-value clauses. Every sentence earns its place.

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

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

Given the rich input schema, output schema, and annotations, the description covers everything an agent needs: what the tool returns, how to filter, how to paginate, and when to call it. The incremental sync and pagination protocol are both stated clearly, so no critical behavioral gap remains for this list-style 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 description coverage is 100%, so the input schema already documents every parameter thoroughly, including enums, defaults, and filter behavior. The description adds a high-level summary of filtering ('Filter by kind, domain, and/or since') and pagination, but does not need to repeat schema details. Baseline 3 is appropriate because the schema carries the semantic load.

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

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

The description names a specific verb and resource: 'List every ontology node in the vault', with a precise definition ('each .md file with a frontmatter kind:'). This clearly distinguishes it from sibling tools like list_kinds (which lists kinds) and get_concepts (which fetches specific concepts). The scope is unambiguous and immediately actionable.

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

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

The description explicitly states a primary usage context: 'AI agents call this first to grasp the codebase's mental model.' It also explains when to use pagination and incremental sync. However, it does not explicitly say when to prefer alternatives such as list_kinds or get_concepts, so usage guidance is strong but not fully exclusionary.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the behavioral trait that it returns aggregated counts rather than a full list, and that it's a quick operation. However, it doesn't disclose details like whether the byKind map is sorted, whether zero-count kinds are omitted, or whether the total includes all concepts. With annotations covering safety, a 3 is appropriate.

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

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

Two sentences with no waste. The return shape is front-loaded, and the usage context is given in the second sentence. Every word earns its place.

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

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

The tool is simple (zero params, no nested objects) and has an output schema, so the description doesn't need to explain return values in depth. It covers the purpose, the return shape, and the use case. Minor gap: it doesn't mention whether the distribution is limited to certain concept types or if it includes all vault concepts, but the output schema likely covers that.

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

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

The tool has zero parameters, so the schema is trivially complete. The description adds meaning by explaining the return shape ({ total, byKind: { capability: N, ... } }), which is more than the empty schema provides. Baseline 4 for zero params is appropriate.

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

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

The description clearly states the tool's purpose: it provides a vault kind distribution with a total count and per-kind breakdown. It uses a specific verb ('list'/'census') and resource ('vault kind distribution'), and distinguishes itself from the sibling list_concepts by noting it's a quick census without paging.

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

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

The description implies when to use it: to size up the vault without paging through list_concepts. It names the alternative (list_concepts) and the context (quick census), though it doesn't explicitly state when not to use it or mention other alternatives like query_ontology.

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

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

The description goes far beyond the annotations. While annotations already indicate destructiveHint, the description details exactly what is destroyed (fromSlug deleted after redirecting), what is preserved (intoSlug prose and non-identity frontmatter), and the two-stage execution model (dry-run vs confirm). It also discloses failure conditions (throws if slug missing), conflict guards, and the structure of the output (postWriteMaintenance with byPhase/bySeverity/byKind). This is exemplary behavioral transparency.

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

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

The description is long but information-dense. It front-loads the critical destructive warning and organizes the two-stage safety into a numbered list. Each sentence contributes useful details (redirects, preserved fields, conflict guards, output structure). While some output details might duplicate what's in the output schema, the description is still tightly written and avoids fluff. The length is justified given the tool's complexity.

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

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

For a destructive, multi-file mutation tool, the description covers all essential context: preconditions (slugs exist), side effects (redirects, deletion), safety mechanisms (dry-run, confirm), conflict guards, and output expectations. It also mentions exception behavior and the preservation of the survivor's identity. Given the output schema exists, the tool is complete enough for an agent to invoke correctly without additional information.

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

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

The schema already has 100% description coverage for all parameters, with clear descriptions for confirm, fromSlug, intoSlug, expected_mtime, and expected_into_mtime. The description adds valuable context beyond the schema, particularly the dry-run/confirm behavior and the conflict-guard purpose of the mtime parameters ('so a concurrent edit or identity-history change is never overwritten'). This enriches the agent's understanding without repeating the schema verbatim.

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 ('fold one node into another') and explicitly lists the core actions: redirecting all backlinks and deleting fromSlug. This clearly distinguishes it from siblings like rename_concept (which renames a node) and delete_concept (which removes without redirecting). The use of 'DESTRUCTIVE MULTI-FILE WRITE' upfront also signals its unique purpose.

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

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

The description provides clear guidance on when to use the tool: to merge concepts, with a two-stage safety mechanism (dry-run vs confirmed). It also mentions using patch_concept after if combining descriptions is desired, which routes the agent to an alternative action. However, it doesn't explicitly state when to choose a different tool (e.g., rename_concept for simple renaming) or list exclusions. The context 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 only declare readOnlyHint=false and destructiveHint=false, leaving significant behavioral detail to the description. The description fully transparently explains the patch semantics: 'Frontmatter patches are key-by-key — null deletes a key, omission preserves it. Body is fully replaced when provided, otherwise preserved.' It also discloses the conflict-detection error (VaultConflictError) and the structure of the returned postWriteMaintenance object, giving the agent a complete picture of the tool's runtime behavior.

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

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

The description is front-loaded with the core action, then systematically covers usage, patch semantics, conflict handling, and return value structure. Every sentence contributes operational or strategic information. While lengthy, the length is justified by the tool's complexity and the need to clearly explain non-obvious behavior (key-by-key patching, conflict detection, postWriteMaintenance). No filler or redundancy.

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

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

Given the tool's complexity (4 params, nested object, conflict behavior, response details) and the presence of an output schema, the description is exceptionally complete. It covers when to use, how parameters behave, what errors to expect, and what the response contains (maintenance_plan with byPhase/bySeverity/byKind queues and pointer fields). An agent has all necessary information to invoke the tool correctly and handle outcomes.

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?

Although schema description coverage is 100% (all parameters have schema-level descriptions), the tool description adds substantial semantic nuance beyond the schema. It explains the key-by-key frontmatter behavior (null deletes, omission preserves), the body replacement semantics, and the purpose of `expected_mtime` as a conflict guard. This enriches parameter understanding and guides correct values (e.g., per-locale display names in frontmatter).

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

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

The description opens with a specific verb and resource: 'Update the frontmatter and/or body of an existing ontology node.' It explicitly targets existing nodes, distinguishing it from creation (add_concept) and deletion (delete_concept) tools. It also signals the intended use case ('revises, deepens, or reclassifies'), which differentiates it from related siblings like rename_concept or reclassify_concept.

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

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

The description clearly states 'Use when an AI agent revises, deepens, or reclassifies a node.' This gives explicit context for when this tool is appropriate. It does not explicitly name alternative tools or list when-not-to-use conditions, but the scenario phrasing helps an agent decide. The addition of `expected_mtime` conflict guard also provides practical usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description goes further: it explains the grammar (case-insensitive, whitespace-tolerant), enum validation with nearest-value hints, and the special growthHint behavior when total=0. This adds rich behavioral context beyond what annotations provide, with no 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?

Though it is longer than typical descriptions, the length is fully earned: a DSL grammar cannot be conveyed in a sentence. The structure is logical — purpose, grammar, keys, example, special case — and front-loads the most critical scoping information. No filler or repetition.

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

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

For a 2-param tool with an output schema, the description covers everything needed to invoke correctly: it explains the DSL grammar, valid keys, the limit default (via schema), the growthHint edge case, and even gives query examples. The contrast with find_path removes selection ambiguity. Nothing an agent needs is missing.

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

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

Schema coverage is 100%, so both params are already documented. The description adds substantial meaning beyond the schema: it defines the full filter grammar, supported keys, and gives a working example. It also clarifies that kind and has(...) keys are enum-validated, which the schema does not mention. This far exceeds the baseline of 3.

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

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

The description opens with a specific verb+resource: 'search vault nodes by predicate' and immediately frames its niche as saved-filter/smart-list cases. It explicitly names the sibling (find_path) that it is not, making distinction trivial. Examples like 'which capabilities have zero elements?' ground the purpose concretely.

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

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

The description states when to use it ('saved-filter / smart-list cases') and when not to ('find_path (BFS) cannot answer'), and provides concrete example queries. It makes the selection rule explicit rather than implied, leaving no ambiguity about the target use case.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond that: 'side effect 0,' 'never writes the vault,' records are 'not approved ontology facts,' complement excludes unclear/unsupported claims, and missing depends_on preflight yields a 'non-writing approvalGate.' It also exposes operational caveats like cursors being stateless, unknown cursors returning empty pages, and 'truncatedByBudget=true ... zero cycles does NOT mean acyclic.' This is rich behavioral disclosure on its own and fully consistent with the annotations.

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

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

The description is a wall of text: a 39-operation enumeration with extensive cursor and contract details and no headings, lists, or clear front-loaded purpose. Useful guidance such as 'call detail:"compact" directly after connection_info' and even the closing 'Use this when...' is buried by the end of a giant paragraph. It is information-dense, but that density without structure makes it less scannable for an LLM performing a tool selection.

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 57-parameter, 39-operation tool, the description is almost everything but the schema: it explains pagination modes, completion (mutual for unfiltered pages), side-effect boundaries, auth/exclusions per operation, output slots ('content[0].text' vs 'structuredContent'), and operation-specific limits. An output schema is present and carries the return-type contract, so that omission is reasonable. The main shortfall is not missing subjects but a readability/structural deficit that reduces the practical completeness of 4 rather than 5.

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

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

Schema coverage is 100% and its parameter descriptions are already very detailed, so the baseline is 3. The description does add per-operation semantics, e.g., depth defaults varying by operation ('3 for reachability, 2 for impact/blast_radius/subgraph, 20 for lineage/containment_tree') and 'depends_on is normalized to dependencies' for pattern. But much of the body repeats schema content (e.g., searchBudget caveat, afterActionId cursor contract), and one operation-specific statement confuses the schema ('limit (1–100 scanned files ... default 30)' vs schema default 100 cap 500).

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 concrete resource and verb: query the freshly compiled ontology graph, with an explicit contrast against 'pulling the full compile_ontology payload' and a separate analysis archive mode. It also states 'side effect 0' and enumerates operations, so an agent can tell what the tool is for. However, it never differentiates itself from siblings like query_concepts, find_path, find_neighbors, or get_concept, leaving cross-tool discrimination to the agent.

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

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

There is explicit when-to-use guidance: use it when you need graph-database-like answers without compiling the full payload, and 'these archive operations do not support query_plan; run graph-engine queries on the freshly compiled artifact.' It also includes routing rules, e.g., impact/blast_radius only use declared depends_on while reachability/subgraph handle structure, and agent_brief compact should follow connection_info directly rather than workspace_brief. Alternatives are named (compile_ontology, workspace_brief), but sibling query tools are never exclusions, so some boundary work remains.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds 'side effect 0' and 'Nothing is converted and kept — the file is read on request and the text returned once.' It thoroughly discloses paging behavior, including `truncated` and `next`, and the PDF no-text behavior, which goes beyond the structured annotations.

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

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

The description is long but dense: it packs the unit grammar, special cases, paging, return shape, and usage guidance into a single cohesive block. It front-loads the core 'Read raw source into units' idea, though the later detailed listing of return fields could be trimmed since an output schema exists. No wasted words, but not extremely tight.

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

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

The tool has a complex unit model and the description explains the return shape in enough detail, especially since an output schema already exists. It covers format-specific anchor syntax, the no-text PDF behavior, paging semantics, and the relationship to the `sources/` directory, leaving no ambiguity for an agent deciding to call it and process results correctly.

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

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

The input schema already covers all 4 parameters, so the baseline is 3. The description adds meaning beyond the schema by explaining that `from`/`limit` are unit indices (not byte ranges), that `next` is a continuation pointer when `truncated` is true, and that `sheet` narrows a workbook. This connections between the parameters and the unit model is valuable.

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

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

The description states a clear action and target resource: 'Read the text of one raw source under `sources/`' and cuts it into citation units. It differentiates from any other read-style sibling by naming the exact formats and unit schemes (DOCX, XLSX, CSV, text/HTML) and by explaining what the PDF exception is. The 'Use it in place of a shell command' clause further separates it from non-shell, non-source tools.

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

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

The description gives an explicit when-to-use: a Compile, Check or ask turn that needs DOCX or XLSX content, in place of a shell command. It also gives an explicit when-not-to-use: PDFs, which the agent runtime reads natively. No alternative tool is named, but the usage context and exclusions are unambiguous.

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

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

Annotations already signal destructiveHint=true, but the description adds substantial behavioral detail: multi-file write, permanent UID preservation, backlink redirection, starter body replacement with custom prose preservation, and default dry-run. This goes well beyond the annotations and provides safety-relevant understanding for an agent invoking 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?

Two dense, front-loaded sentences with a clear warning, a concise statement of what changes, side effects, and the dry-run default. Every clause adds operational value and nothing repeats the schema or annotations.

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

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

For a destructive multi-file write with seven parameters, the description covers the transaction model, side effects, UID behavior, and body preservation, which is strong. Minor gaps remain around confirm as the commit trigger, expected_mtime concurrency, and the conditional requirement that domain is needed for capability/element, though some of that is present in the schema.

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

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

The description maps meaningfully onto parameters: newKind affects the concept kind, newSlug/domain cover the optional slug/domain changes, and body is reflected in the 'preserving custom prose' behavior. With schema coverage at 57%, the description partially compensates for undocumented params, though confirm and expected_mtime are still left to inference.

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

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

The description names a specific verb ('reclassify'), the resource ('concept'), and the exact scope: changing the concept kind and optionally its slug/domain. It also differentiates this from rename_concept by noting backlink redirection and from patch_concept by framing it as a multi-file write. The behavior is unambiguous and distinct from sibling tools.

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

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

The description gives actionable context by referencing rename_concept and by stating that it defaults to dry-run, which tells the agent that a preview step is expected. However, it never explicitly states when to prefer this over patch_concept, rename_concept, or delete_concept, nor does it state exclusions or prerequisites for reclassification.

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