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

The description richly discloses behavior beyond annotations: dry-run by default, backup creation, rewriting into a 'slim pointer,' throwing instead of overwriting an existing backup, and the rule that the file body is 'always treated as untrusted data.' These details align with destructiveHint:true while also clarifying exactly what is and isn't destroyed.

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 informative, with each clause carrying operational or safety meaning. It is front-loaded with the core purpose and then structures the two-stage safety flow clearly. The 'Slice 0 (PRODUCT-PLAN-2026-07.md §4/§9)' prefix is slightly extraneous for invocation, but it does not obscure the 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?

The description is complete for a tool of this complexity: it covers dry-run behavior, write behavior, backup and fallback semantics, content preservation, injection-suspect handling, and path restrictions. Since an output schema exists, it does not need to enumerate return fields, and it already states that the dry-run returns the 'classification plan per section.'

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 meaningful context beyond the schema by explaining that confirm controls dry-run vs write, that allowOutsideRepo requires a reviewed dry-run, and that outside paths are blocked without it. This makes the parameters' behavioral impact clearer than 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 states a specific verb and resource: it 'converts a CLAUDE.md/AGENTS.md-style markdown file into typed vault nodes' and explicitly distinguishes its classification behavior from related sibling tools like add_concept and delete_concept. It also clearly separates absorbed, suggested, and excluded sections, leaving no ambiguity about the tool's role.

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 explains the motivating use case ('stops needing dual maintenance') and gives explicit routing guidance: architecture/component sections become suggestions only and should be 'review and land with add_concept if useful.' It also states when behavior changes (dry-run vs confirm:true) and when allowOutsideRepo is required, so an agent knows exactly when to invoke this tool versus alternatives.

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

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

Annotations say readOnlyHint=false, but the description goes far beyond that: it discloses that duplicate slugs throw, frontmatter is normalized per kind, missing extras and near-duplicate titles come back as warnings rather than errors, and successful writes return a detailed postWriteMaintenance payload. This rich behavioral detail is independent of and complementary to 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 the tool is complex and the length is generally earned. It front-loads the core action and error condition, then proceeds through normalization, warnings, response shape, bulk usage, and naming constraints. There is some redundancy between the title-role rule and the slug rule, and the response details could be trimmed, but it remains logically organized and useful.

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

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

For a 9-parameter mutation tool with an output schema, the description is unusually complete: it covers when to use it, when not to, duplicate handling, warning behavior, response contents, bulk alternative, parent/domain expectations, and naming rejection rules. Nothing an agent needs to invoke the tool 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 baseline is 3, but the description adds meaningful context on top: slug must be flat under the kind folder and never a code path, capability/element should set domain, and title should name a role rather than a file path. This goes beyond the schema's field descriptions, though it does not deepen every parameter.

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

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

The description opens with a specific verb and resource: 'Create a new ontology node (.md file).' It immediately distinguishes add_concept from its siblings by naming patch_concept for existing slugs and add_concepts for bulk creation. This 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 explicitly states when to call the tool ('Call when an AI agent finds a new capability / element / project from code analysis') and gives concrete alternatives: use patch_concept when the slug already exists or when a near-duplicate title is found, and use add_concepts for batch creation. This is explicit when/when-not guidance.

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

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

The description goes far beyond the annotations (which are sparse: readOnlyHint=false etc.) by disclosing: per-row independent processing, error row shapes (including field-level details like `receivedField` and `unknownFields`), handling of duplicate slugs, near-duplicate detection with warnings, response order, the 50-cap, no atomic rollback, and the presence of `postWriteMaintenance` when at least one row changes the vault. It even provides domain-specific warnings (duplicates are the #1 failure mode). This level of disclosure is exceptional and far exceeds the annotations' minimal hints.

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 every sentence serves a purpose: it defines scope, usage, error handling, batch limit, atomicity, and maintenance output. It is front-loaded with the core purpose and alternates. However, it is arguably dense and could be trimmed, but for a complex batch operation, the length is justified and well-structured.

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

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

Given the tool's complexity, the output schema, and the 1-parameter schema that is fully documented, the description covers everything an agent needs: when to use, error handling, batch limits, post-write maintenance, and even best practices for grouping nodes. There is no significant missing guidance for correct invocation.

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

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

The schema already covers 100% of the parameter (`concepts` with nested objects) and includes a description for the array indicating it uses the same shape as `add_concept` input. The tool description doesn't re-describe the parameters but does add context about row-level error handling and warns about `elements` and `labels` (e.g., fill both locales). Since schema coverage is high, baseline is 3, which is appropriate here.

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

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

The description starts with a clear verb-resource pair: 'Batch-create multiple nodes in one call' and immediately contrasts with the single-node `add_concept`. It specifies the exact use case (after `analyze_repo_structure` or similar) and the interface (same per-row shape as `add_concept`), distinguishing it from siblings. This is specific and 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 explicitly states when to use it: 'Use after `analyze_repo_structure` or another reviewed proposal flow when the agent has K accepted candidates.' It also gives the alternative: 'replaces K×`add_concept` round-trips' and provides exclusions: 'if you need all-or-nothing semantics use single `add_concept` calls' and 'split into multiple batches for larger sets.' This is exemplary 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?

Goes well beyond the annotations (idempotentHint=true, readOnlyHint=false): it discloses idempotent-read behavior for existing edges, the VaultConflictError thrown by expected_mtime, rejection of invalid type before endpoint slug resolution, the structuredContent repair fields, and the postWriteMaintenance shape returned on changed writes. Consistent with 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?

Front-loaded with purpose, but the description is very long and reproduces a substantial amount of output-schema detail (structuredContent repair field names, maintenance_plan bucket names like byPhase/bySeverity/byKind, nextExecutableAction pointers) that an output schema already carries. Information-dense with no fluff, yet over-specified for a selection/invocation 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 5-param mutation tool with an output schema, the description is remarkably complete: it covers frontmatter write semantics, idempotency, conflict handling, error repair metadata, and the sibling batch alternative. It doesn't need to explain return values since output schema exists. Slight redundancy with the schema keeps it from a 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%, so baseline is 3, but the description adds real workflow meaning: it explains that the type parameter picks which frontmatter key receives the entry, that `domain` sets the inline parent domain, that depends_on requires a nonblank why, and that expected_mtime should carry the prior get_concept mtime. This is value beyond the schema's literal field definitions.

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 ('Add a semantic relation between two nodes') and immediately explains the mechanism (appending to the matching frontmatter graph key). It differentiates from the sibling add_relations by naming the batch alternative explicitly, and the semantics are clearly distinct from remove_relation/replace_relation.

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-not guidance: 'For multiple already-approved semantic edges use add_relations({relations: [...]})' and flags that infer_imports.moduleEdges require exact-evidence review, semantic rationale, and human approval first. The expected_mtime guidance (pass source-side mtime from a prior get_concept) tells agents exactly when and how to use the conflict guard.

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: it discloses non-atomicity, per-row independent/idempotent processing, exact error shapes, the 50-row cap, and the absence/presence of `postWriteMaintenance`. This complements the idempotentHint=true annotation without contradicting any annotation 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 long, but it is front-loaded with the core capability and use case, and each subsequent clause adds actionable behavioral or error-handling detail rather than filler. It could be trimmed slightly if the output schema already documents the response fields, but the density is justified by the batch operation'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 batch mutation tool with one parameter, the description covers input constraints, row-level error semantics, ordering, capacity, rollback behavior, a concurrency trap, and post-write maintenance response structure. Nothing an agent needs to invoke it correctly appears to be 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?

Although the schema already describes `relations` and its fields, the description adds meaningful runtime semantics: the `why` field is required nonblank for new `depends_on` rows, `expected_mtime` can become stale when multiple rows share a `from` slug, and rows are processed independently. This materially improves an agent's ability to construct valid batch payloads.

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: 'Batch-add multiple relations in one call.' It explicitly contrasts with the sibling `add_relation` by noting this replaces K×`add_relation` round-trips, so an agent can clearly distinguish the tool's purpose from the singular variant.

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

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

It gives an explicit use-after condition ('Use after `analyze_repo_structure` or another review flow when the agent has K semantic edges accepted by the user') and an explicit alternative ('for all-or-nothing semantics use single `add_relation` calls'). It also warns about `expected_mtime` in specific batch scenarios, which is 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, and the description adds substantial context beyond them: side effect 0, deterministic candidates, bounded read/edit budgets (1,200-char README budget, 8/16/32/64 KiB limits, ~200-line outline threshold), the full review/qualification lifecycle, and the rule that returned source is untrusted evidence that never grants write authority. None of this is recoverable from the annotations or schema.

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

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

The purpose is front-loaded, but the body is a ~1,500-word wall mixing bullet lists with dense jargon (reviewRequiredEvidence, sourceHiddenTask, constructionQualification:v1, axisResults). Several constraints are repeated verbatim (the expectedSha256 replay rule and the 'outline first for >200-line files' advice each appear twice), so not every sentence earns its place. Much of the lifecycle policy reads like documentation rather than selection 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?

An output schema exists, so return values need not be explained, yet the description still covers the critical output-side contract (reviewPlan, planDigest, sourceDigest, writePlan gating, eight-phase lifecycle, shadow-only admission tier). For a tool of this complexity with 6 params and nested proposal/qualification objects, the agent has enough to call it correctly and know what gates follow.

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 already 100%, so the schema carries baseline semantics for ignore, maxDepth, proposal, sourceReads, qualificitation. The description nonetheless adds real meaning: maxDepth is accepted but ignored, sourceReads mode 'outline' returns no source text or citation and must be replayed as line ranges, and expectedSha256 becomes mandatory whenever proposal or qualification is present.

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 states a specific verb+resource (analyze a code repository and propose ontology node candidates) and immediately scopes the side effect (vault frontmatter NOT modified). The enumerated detection rules (package.json, README H1/H2, FSD folders, Cargo/Python packages) make it unmistakable versus siblings like infer_imports or read_source, which it explicitly references.

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

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

It gives explicit trigger guidance ('Use the initial discovery call when a user asks ... / bootstrap the ontology') and constrains recurrence ('repeat the same analysis call only for explicit source continuations and digest-bound proposal or qualification replay'). It also states prerequisites for downstream writes (do not call write tools unless proposalValidation.canWrite and a writePlan exist). It stops short of naming alternative sibling tools to prefer for narrower cases.

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

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

Annotations already cover readOnly/destructive/openWorld, and the description adds substantial extra context: 'side effect 0,' the MCP token cap risk on large vaults, the precedence of `summary` over other args, the fallback bounded summary with a `delivery` field, and the pagination meta shape. This is well beyond what structured fields provide.

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

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

Front-loaded with the core purpose and usage trigger before diving into payload/pagination mechanics. It is dense and mostly earns its sentences, though the closing pagination-meta sentence overlaps with what the schema and output schema already convey.

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

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

For a zero-required-param, read-only compile tool with an output schema, the description covers everything an agent needs: token-cap behavior, caching via graphHash/maxMtime, summary vs full vs paged modes, and precedence rules. Nothing material 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, but the description adds interaction semantics the schema cannot express: that `summary` 'wins over every other argument,' that `full: true` returns every array while page args still slice, and how offsets/limits pair together. This is genuine added meaning over 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?

States a specific verb ('Compile') and resource ('the whole markdown vault') and enumerates the artifact contents (nodes, edges, aliases, issues, canonicalization actions, optional indexes). It also positions itself as 'the compiler-style read path,' which distinguishes it from siblings like query_ontology and validate_vault.

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 guidance: 'call it before advanced reasoning, indexing, export, or non-developer-friendly graph views.' It also explains when to use the cheap summary mode ('cheap polling'). It does not name specific alternative sibling tools for overlapping needs, so it falls 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 cover the safety profile (readOnly, not destructive), and the description adds real behavioral context beyond them: root changes require restarting the MCP process, the return shape is always guide.card plus guide.topics, and it explains the host-truncation rationale for the guideText path. This is information an agent could not get from 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?

Front-loaded with the core return values, then usage, then the optional parameter. Every sentence carries information, though it is dense and could be split slightly more cleanly. No filler.

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

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

With an output schema present the description needn't enumerate return values, yet it still summarizes the guaranteed fields (guide.card, guide.topics) and the optional guideText. Combined with the restart constraint and the stale-config call trigger, 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?

Schema coverage is 100% with a rich enum description, so the schema carries most of the load (baseline 3). The description adds genuine value by explaining why to pass `guide` – it returns guideText, the full topic text, because hosts may truncate the server instructions while tool results arrive whole. That is semantics beyond the schema.

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

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

States a specific verb ('Return') and resource ('the exact active vault root and code-repository root used by this MCP process'), with the added scope of 'how each root was resolved'. No sibling tool deals with connection roots, so it is clearly distinguishable from the 30+ other 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?

Gives explicit when-to-call guidance: 'Call first when a client may have stale configuration or multiple workspaces.' It also notes the restart prerequisite for root changes, which is a usage constraint. It does not name a direct alternative, but none is needed for a diagnostic tool.

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

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

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 already mark this as destructive, but the description adds substantial behavior: two-stage safety, backlink throw, dangling referrers after force, returned frontmatter/body for recovery, directory preservation, mtime conflict, and maintenance output. This goes well beyond what the annotations disclose.

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

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

Front-loads the destructive warning and numbered safety flow, so critical information appears early. The final sentence detailing postWriteMaintenance fields is long and partly redundant with the output schema, but the overall structure is efficient for a complex destructive 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 destructive tool with rich annotations and an output schema, the description closes the remaining gaps: safety staging, refusal/override conditions, recovery output, and concurrency guard. An agent has enough context to invoke it without surprise.

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 nevertheless adds semantic consequences for confirm, force, and expected_mtime (dry-run behavior, dangling referrers, conflict throw). It does not add new syntax for slug, but it deepens the operational meaning of 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?

States a specific destructive verb and resource ('permanently deletes the vault .md file') and scopes it to concept deletion. An agent can distinguish this from sibling read/list/relation tools 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?

Provides explicit operational guidance: dry-run without confirm, refusal when backlinks exist, force override with the dangling-referrer consequence, and expected_mtime as a concurrency guard. It lacks a direct comparison to sibling alternatives, but no other concept-deletion sibling exists.

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 destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral scope beyond them: it enumerates that frontmatter array keys (capabilities/elements/dependencies/etc.) AND body wikilinks/markdown links are scanned, which tells the agent exactly what counts as a backlink.

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

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

Three short sentences, front-loaded with the core behavior and followed by the scanning scope and use case. No filler, though the third sentence is closer to rationale than operational 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?

An output schema exists, so return-value explanation is unnecessary. The description covers the scan sources and directionality, leaving only explicit sibling routing unaddressed, which is a minor gap for a single-param read tool.

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

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

Schema coverage is 100% and the single 'slug' param is already documented in the schema (vault-relative, omit .md). The description adds no extra syntax or format detail beyond that, 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?

States a precise verb+resource+direction: 'Return every node that points to the target slug.' The inbound-edge semantics clearly distinguish it from siblings like find_neighbors (neighbors) and find_path (paths) without needing to name them.

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

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

'Used by AI agents to walk the graph from a node to its dependents' implies an intended use context, but it never states when to pick this over find_neighbors or find_path, nor any exclusion conditions. Usage is only inferred, not guided.

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 cover the safety profile (readOnly, non-destructive), so the bar is lower, yet the description still discloses substantial behavior: excerpt truncation at 200 chars with heading/table/code skipping, the deterministic ranking order (title > frontmatter > body, node-ness, slug), default 50 / max 500 with total and limited flags, and the growthHint on zero matches. This is far more than the annotations carry.

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

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

Front-loads the core purpose and is generally efficient, with the most actionable routing and ranking facts early. It is dense and long with heavy bold/caps formatting, and a few clauses (e.g. the full ranking tiebreaker chain) could be tightened, but every sentence carries information.

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

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

For a 3-param search tool with an output schema, the description supplies everything needed to call it correctly and interpret results: node vs non-node semantics, ranking, limit/truncation signals, and the empty-result growthHint path. No behavioral or usage gap an agent would need remains.

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 meaning beyond the schema: it explains that limit defaults to 50 and that total/limited signal truncation, and that nodesOnly filters ordinary markdown that would otherwise rank below nodes. It clarifies the intent of each parameter rather than restating types.

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

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

States a specific verb and resource ('Find vault docs that mention a given concept by title') and distinguishes itself from siblings like get_concept by providing the excerpt inline. An agent can tell instantly that this is a ranked text search over vault docs rather than a concept fetch.

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

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

Gives a concrete trigger ('when an AI agent asks where a capability is realized in code or docs') and a caution ('Do not cite a non-node as graph evidence without saying so'), which is a real usage constraint. It does not explicitly route against alternatives like get_concept or query_concepts beyond the passing mention, so it stops short of full when/when-not guidance.

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

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

With 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial context beyond them: default returns only the first prose paragraph, bodyInfo always reports totalChars/returnedChars/truncated so partial reads are never silent, and it explains that uid/slug are always both returned.

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

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

Front-loaded with the core operation and selector rule, and every sentence carries distinct information. It is dense and heavily bolded, which costs a little readability, but little is wasted.

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

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

Despite an output schema existing, the description still communicates the shape of the response (frontmatter, body, neighbors, outgoingEdges with rationale, mtime) and the truncation contract, so an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: the excerpt-vs-full tradeoff and that 'full' omits 'excerpt', plus the mutual exclusivity of slug and uid beyond what the schema's own text states.

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

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

Specific verb+resource ('Fetch one node') with an explicit uniqueness constraint on selectors (exactly one of slug or uid). It clearly differentiates itself from the sibling get_concepts, which it names for the multi-selector case.

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 guidance: default excerpt for identification, pass body:'full' when reading to answer a question, and use get_concepts for K selectors in one call. It even notes fallback behavior when a slug fails to resolve.

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 cover safety (readOnlyHint, destructiveHint=false), and the description goes well beyond them: partial-failure semantics for missing/invalid slugs and UIDs, ordering guarantees, permanent uid + canonical slug on success, and the batch cap implications. This is exactly the extra behavioral context that annotations cannot supply.

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

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

Front-loaded with the core action and selector rule, then failure semantics. Dense but every sentence carries information; the run-on clauses about partial rows are slightly heavy but justified by the batch failure model.

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

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

For a 3-param batch read tool with a full output schema, the description covers selection rules, ordering, per-row success/failure shape, and batching limits. An agent needs nothing more to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the cross-parameter constraint ('exactly one selector array') and links body=full to a reduced batch cap. That said, it does not fully document the repairFields shape beyond naming it.

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

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

States a specific verb and resource ('Fetch multiple nodes') and names the exact selector mechanism (slugs or uids). The plural form is implicitly contrasted with the sibling get_concept (singular), so an agent can distinguish batch from single fetch.

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?

Clearly states the constraint that exactly one selector array must be used and that slugs and uids are mutually exclusive ('Use instead of slugs, never together'). It does not explicitly route to alternatives like query_concepts or find_neighbors, but the usage conditions 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 carry readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'No writes or external sending.' It adds behavioral guarantees about identity source ('UID and merged-UID claims are the only identity source') and non-retargeting of display paths/titles, which go 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 front-loaded with the core action and keeps all content relevant. The second sentence is a dense enumeration of return categories, which packs information efficiently but relies on domain jargon such as 'review currentness' and 'bounded evidence starting points.'

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

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

For a read-only tool with an output schema and rich annotations, the description covers the essential behavioral context: what is read, what is returned at a category level, identity semantics, and absence of side effects. It is complete enough for an agent to invoke the tool correctly with id and optional limits.

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 every parameter already has a description. The description adds semantic mapping by tying pagination to 'saved membership,' relationLimit to 'real declared internal relations,' and dependencyLimit to 'direct outside-scope dependencies,' which enriches the raw schema fields.

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: 'Read one saved constellation by immutable ID from this configured vault.' This clearly differentiates it from list_constellations (listing) and get_concept (concept lookup), and highlights the immutable-ID scope.

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 context for when the tool applies—reading a single saved constellation by immutable ID—but it never explicitly names alternatives such as list_constellations for enumeration or states when not to use this tool. The usage is therefore implied rather than explicitly routed.

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?

Annotations only declare the safety profile (readOnlyHint=true, destructiveHint=false), yet the description goes well beyond them: it states "side effect 0: this tool never writes markdown," explains the extractionContract/evidence-versus-proposal semantics, and clarifies that only the CLI `--apply` path writes (analyzer-proposed concepts and containment) while inferred imports stay review-only and are never auto-promoted to depends_on. That is exactly the mutation/auth/side-effect detail structured fields cannot carry.

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

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

Purpose is front-loaded, but the description runs six-plus dense sentences heavy with internal jargon ("extractionContract," "genuinely new buckets," "competency questions") that is costly to parse. It is information-dense rather than padded, but the lack of shortening/structure keeps it from earning a 4.

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?

An output schema exists, so return values need not be explained, yet the description still summarizes the plan contents (candidate buckets, reviewCalls, competency questions, uncertainty, approval gates, validation applicability), giving the agent a complete mental model. Combined with the read-only annotations, 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?

Schema description coverage is 100%, so the schema already documents every parameter (maxDepth, maxFiles, rootPath, threshold, skipImports). The description adds a little routing context (which sub-tool each param forwards to, and the skipImports behavior), but does not add format or semantic detail beyond the schema, 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 opening states a specific verb+resource (index a project's ontology) and immediately names the three sibling tools it orchestrates (analyze_repo_structure, infer_imports, validate_vault), so an agent can distinguish it from those siblings without reading schemas. The read-only plan scope is explicit up front.

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?

"Use for large or already-existing projects where the agent needs a resumable ontology indexing checkpoint before writing" gives a clear triggering condition, and skipImports plus the CLI `index --apply` note sketch the alternative path. It stops short of explicit when-not guidance for smaller projects or a direct compare against calling the three sub-tools individually.

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

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

Annotations already declare readOnly/non-destructive/openWorld=false, and the description adds substantial extra behavior: side effect 0 (vault frontmatter untouched), never self-approving semantic relations, no get_concepts/relation_check calls on missing slugs, actionable errors on oversized raw scans, and the 128 KiB gated response contract. It adds real value beyond annotations, though the idempotentHint=false implication is never explained.

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

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

Front-loads purpose acceptably but then sprawls into a dense block with repeated claims (the 'never self-approves a semantic relation' idea appears several times, the 128 KiB limit is restated) and jargon like 'nextRelationReview:v1'. Much of the length is informational but not tightened, so it exceeds what a concise tool doc should be.

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

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

With an output schema present the description needn't explain return values, and annotations cover the safety profile; what remains — language coverage, review modes, reconciliation semantics, and failure behavior — is all addressed. An agent has enough 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 already 100%, so the baseline is 3; the description compensates further by explaining the 128 KiB delivery threshold, allowLargeResponse's second-confirmation role, reconcile's default/effect, and the focus paging cursors. This is beyond what the schema alone conveys.

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 concrete verb+resource: 'walk TS/JS files in a code repo and infer file-level + module-level import edges,' then extends to Python/Rust/Go modes. It also explicitly differentiates itself from the sibling analyze_repo_structure ('pull *real* dependency edges from the code, not just suggestedRelations heuristics').

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

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

States the sequencing rule ('Use after analyze_repo_structure'), gives explicit selection conditions for reviewMode focus/next/full, explains when focusPath should be set before considering full, and describes the reconcile:false opt-out. Alternatives and when-not conditions are covered.

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 read-only nature is covered. The description adds valuable behavioral context beyond annotations: it discloses that the tool returns 'honest unavailable status for missing/corrupt/unsupported data' and clarifies that membership is task scope rather than an ontology relation. This prevents misinterpretation of the data's meaning, which annotations do not convey.

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

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

The description is a single, dense paragraph of three sentences. It front-loads the primary purpose and includes essential qualifiers without excessive verbosity. The structure is clear and every sentence contributes meaning, though the density could be slightly briefer for maximum readability.

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

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

Given that an output schema exists, the description need not detail return values, yet it still specifies key output fields (names, timestamps, member counts, etc.) and the honest status handling. It also clarifies the important semantic boundary ('task scope, not ontology relation'), which is essential for correct tool selection. The tool's simplicity and the presence of an output schema mean the description is complete for an agent to call it correctly.

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

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

The input schema fully describes both parameters (limit and offset) with clear descriptions, achieving 100% schema description coverage. The description does not add additional parameter-level semantics, so the baseline of 3 is appropriate; it neither compensates for gaps nor adds extra value beyond the schema.

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

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

The description clearly states a specific action (list) and resource (saved constellation metadata from this configured vault only). It specifies the exact fields returned and distinguishes its scope from broader ontology concepts by clarifying that saved membership is task scope, not an ontology relation. This differentiates it from siblings like list_concepts and get_constellation.

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 context by stating 'from this configured vault only,' which suggests it is scoped to a specific vault, but it does not explicitly state when to use this tool versus alternatives like get_constellation or list_concepts. The semantic caveat about task scope provides some context but not direct usage guidance or exclusions.

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

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

Annotations already cover the read-only, non-destructive profile. The description adds that this is an aggregate census returning total and per-kind counts rather than a paged list, which is useful behavioral context beyond the annotations.

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

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

Two sentences with no filler: the first front-loads the output shape, the second adds the use case and sibling distinction. Every word contributes to understanding the tool.

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

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

For a zero-parameter, read-only census, the description gives the purpose, the return shape, and the relationship to list_concepts. An output schema exists for the return value, so the description does not need to document the response fields further.

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

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

The input schema has zero parameters, so there are no parameter semantics to describe. The baseline of 4 applies because the description correctly leaves the input side untouched and the schema already covers it entirely.

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

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

The description states that the tool returns vault kind distribution with total and byKind counts, and differentiates it from list_concepts by positioning it as a quick census. It is clear, though it uses a noun phrase ('Vault kind distribution') rather than an explicit verb like 'list' or 'summarize'.

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 says to use this tool for a quick census to size up the vault, and contrasts it with paging through list_concepts. It implies the alternative for item-level traversal but does not explicitly say 'use list_concepts when you need detailed concept listings.'

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it names exactly what is destroyed (fromSlug file), what is preserved (survivor UID, source UID/history in merged_uids), what is NOT merged automatically (prose and non-identity frontmatter), the dry-run safety stage, and the throw condition on missing slugs.

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 destructive warning and the core mechanic are front-loaded, and the numbered safety stages are scannable. It runs long, with the postWriteMaintenance detail bordering on redundant against the output schema, but nearly every sentence carries operational meaning.

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 with conflict-guard params, the description covers the write path, the dry-run path, identity preservation, failure modes, and follow-up routing. An output schema exists, so its added return-value prose is surplus rather than a gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic weight: it clarifies that confirm governs the dry-run-versus-write boundary and that omitting it preserves the redirect plan, which contextualizes how the required slugs are actually consumed.

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,' with the exact mechanical consequence spelled out (backlinks redirected, fromSlug deleted, survivor keeps its UID). It clearly differentiates from siblings like delete_concept and rename_concept, which perform single-file operations without the multi-file merge semantics.

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

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

It explicitly routes the agent to patch_concept for combining descriptions after the merge, and it explains the two-stage confirm flow (dry-run without confirm, single-pass write with it). It does not, however, contrast when to merge versus rename or delete, leaving one 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?

The description goes well beyond annotations, detailing the exact merge semantics (key-by-key frontmatter patching, null deletion, omission preservation, full body replacement vs. preservation). It discloses the VaultConflictError mechanism and describes the postWriteMaintenance return structure with actionable fields. Annotations only indicate it's a write and non-destructive, but the description adds rich behavioral context.

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

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

The description is relatively long but each clause earns its place: purpose, usage, merge semantics, conflict handling, and return maintenance details. It's front-loaded with the core action, and the density of useful information outweighs any verbosity. Could be trimmed slightly, but no redundancy.

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

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

With an output schema available, the description correctly focuses on behavior not return format. It covers the patching rules, conflict detection, and the maintenance plan hooks. Minor omissions like validation rules for frontmatter values are acceptable given the schema and sibling tools. For a complex mutating operation, this is nearly complete.

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

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

Despite 100% schema coverage, the description adds critical nuance not present in the schema: the frontmatter patch semantics (null deletes, omission preserves), body replacement rules, and the origin/usage of expected_mtime ('from the previous get_concept response'). This transforms bare parameter definitions into actionable contracts.

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.' This clearly distinguishes it from sibling tools like add_concept (creation) and delete_concept (removal). The scope is precise and 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?

Explicitly states when to use: 'Use when an AI agent revises, deepens, or reclassifies a node.' It does not list alternatives or exclusions (e.g., don't use for new nodes), but the context is clear enough. The mention of expected_mtime for conflict detection provides concrete guidance on safe use.

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

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

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?

With readOnlyHint=true and destructiveHint=false already in annotations, the description adds meaningful context beyond safety: archive records are immutable, 'not approved ontology facts,' reviews are joined to exact run/finding ids, pagination should be followed even when a page is empty, task text is never persisted, and several operations are side-effect-free. It does repeat 'side effect 0' from annotations, but the amount of non-redundant operational behavior disclosed is substantial.

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 sprawling block that opens with archive details rather than the primary purpose, then runs through a dense catalog of every operation. Many clauses are necessary for a 39-operation tool, but the total is poorly front-loaded and lacks structural markers, making it harder to scan than it needs to be.

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

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

For a high-complexity operation-based tool with an output schema, the description covers the full operation set, usage constraints, behavioral caveats, and write guards. Since output schema exists, return values need not be explained, and the description's remaining details are sufficient for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 57 parameters in detail. The description adds operation-level usage context (e.g. analysisMode/project/limit/analysisCursor for analysis_history, recordId for analysis_record, task limits for agent_brief compact), but does not meaningfully extend the per-parameter semantics beyond what the schema provides. Baseline 3 is appropriate when the structured schema carries the parameter documentation.

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

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

The description states a specific verb ('Run graph-engine queries') and resource ('freshly compiled ontology artifact') and enumerates all 39 operations. It explicitly distinguishes itself from compile_ontology by saying 'without pulling the full compile_ontology payload' and from non-graph read operations like read_source. An agent can tell what this tool is for and what it is not for without opening the schema.

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

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

It gives explicit when-to-use guidance: 'Use this when you need graph-database-like answers without pulling the full compile_ontology payload.' It names alternatives and constraints, e.g. 'For impact and blast_radius, only declared depends_on is allowed; use reachability/subgraph for structure' and 'do not precede it with workspace_brief or a full inventory unless the question needs whole-vault health.' Operation-level routing is also specified, such as relation_check as a preflight before add_relation.

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

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

The description goes well beyond the readOnlyHint/destructiveHint annotations, disclosing that nothing is converted and kept, that PDFs return no text, that the file is read on request and returned once, how paging/truncation works, and that the side effect is zero. No contradiction with annotations is present.

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 long, but every sentence earns its place: scoping, unit definitions, PDF caveat, persistence behavior, paging, and when to use it. It is front-loaded with the most important distinction first, but the sheer volume of detail keeps it from being maximally concise.

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 output schema, annotations, and sibling context, the description is complete. It explains unit kinds, anchor citation format, paging, the PDF exception, and the non-persistent read behavior—leaving no decision-relevant gap for an agent trying 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?

The schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantics on top: how units are indexed per file type, what anchors look like, how `from`/`limit`/`truncated`/`next` interact, and the `sheet` narrowing behavior. That added context justifies a 4 rather than a flat 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 opens with a precise scope boundary ('Vault source documents only; repository code is read through analyze_repo_structure') and names a specific verb and resource: 'Read the text of one raw source under sources/'. It distinguishes itself from sibling tools by defining exactly what it does and what it does not cover.

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

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

The description explicitly states when to use the tool: 'Use it in place of a shell command when a Compile, Check or ask turn needs what a DOCX or XLSX says.' It also gives an alternative for repository code, analyze_repo_structure, and warns that PDFs are not handled here because the runtime reads them natively.

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